feat: 配置 golangci-lint 静态分析并修复存量违规

- 新增 backend/.golangci.yml 配置 12 个 linter（forbidigo、errorlint、errcheck、staticcheck、revive、gocritic、gosec、bodyclose、noctx、nilerr、goimports、gocyclo）
- 新增 lefthook.yml 配置 pre-commit hook 自动运行 lint
- 修复存量代码违规：errors.Is/As 替换、zap.Error 替换、import 排序、errcheck 修复
- 更新 README 补充编码规范说明
- 归档 backend-code-lint 变更

backend/internal/handler/handler_supplemental_test.go

@@ -6,13 +6,13 @@ import (
 	"net/http/httptest"
 	"testing"
 
+	"nex/backend/internal/domain"
+	"nex/backend/tests/mocks"
+
 	"github.com/gin-gonic/gin"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/mock/gomock"
-
-	"nex/backend/internal/domain"
-	"nex/backend/tests/mocks"
 )
 
 func TestProviderHandler_CreateProvider_Success(t *testing.T) {
@@ -24,9 +24,9 @@ func TestProviderHandler_CreateProvider_Success(t *testing.T) {
 	h := NewProviderHandler(mockSvc)
 
 	body, _ := json.Marshal(map[string]string{
-		"id":      "p1",
-		"name":    "Test",
-		"api_key": "sk-test",
+		"id":       "p1",
+		"name":     "Test",
+		"api_key":  "sk-test",
 		"base_url": "https://api.test.com",
 	})
 	w := httptest.NewRecorder()

backend/internal/handler/handler_test.go

@@ -9,23 +9,22 @@ import (
 	"strings"
 	"testing"
 
+	"nex/backend/internal/domain"
+	"nex/backend/tests/mocks"
+
 	"github.com/gin-gonic/gin"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/mock/gomock"
 	"gorm.io/gorm"
 
-	"nex/backend/internal/domain"
 	appErrors "nex/backend/pkg/errors"
-	"nex/backend/tests/mocks"
 )
 
 func init() {
 	gin.SetMode(gin.TestMode)
 }
 
-
-
 func TestProviderHandler_CreateProvider_MissingFields(t *testing.T) {
 	ctrl := gomock.NewController(t)
 	defer ctrl.Finish()

backend/internal/handler/middleware/logging.go

@@ -20,7 +20,6 @@ func Logging(logger *zap.Logger) gin.HandlerFunc {
 		if id, ok := requestID.(string); ok {
 			requestIDStr = id
 		}
-		
 		logger.Info("请求开始",
 			pkglogger.Method(c.Request.Method),
 			pkglogger.Path(path),

backend/internal/handler/model_handler.go

@@ -4,13 +4,13 @@ import (
 	"errors"
 	"net/http"
 
+	"nex/backend/internal/domain"
+	"nex/backend/internal/service"
+
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 
 	appErrors "nex/backend/pkg/errors"
-
-	"nex/backend/internal/domain"
-	"nex/backend/internal/service"
 )
 
 // ModelHandler 模型管理处理器
@@ -58,16 +58,16 @@ func (h *ModelHandler) CreateModel(c *gin.Context) {
 
 	err := h.modelService.Create(model)
 	if err != nil {
-		if err == appErrors.ErrProviderNotFound {
+		if errors.Is(err, appErrors.ErrProviderNotFound) {
 			c.JSON(http.StatusBadRequest, gin.H{
 				"error": "供应商不存在",
 			})
 			return
 		}
-		if err == appErrors.ErrDuplicateModel {
+		if errors.Is(err, appErrors.ErrDuplicateModel) {
 			c.JSON(http.StatusConflict, gin.H{
-				"error":  "同一供应商下模型名称已存在",
-				"code":   appErrors.ErrDuplicateModel.Code,
+				"error": "同一供应商下模型名称已存在",
+				"code":  appErrors.ErrDuplicateModel.Code,
 			})
 			return
 		}
@@ -101,7 +101,7 @@ func (h *ModelHandler) GetModel(c *gin.Context) {
 
 	model, err := h.modelService.Get(id)
 	if err != nil {
-		if err == gorm.ErrRecordNotFound {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{
 				"error": "模型未找到",
 			})
@@ -166,7 +166,7 @@ func (h *ModelHandler) DeleteModel(c *gin.Context) {
 
 	err := h.modelService.Delete(id)
 	if err != nil {
-		if err == gorm.ErrRecordNotFound {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{
 				"error": "模型未找到",
 			})

backend/internal/handler/provider_handler.go

@@ -4,13 +4,13 @@ import (
 	"errors"
 	"net/http"
 
+	"nex/backend/internal/domain"
+	"nex/backend/internal/service"
+
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 
 	appErrors "nex/backend/pkg/errors"
-
-	"nex/backend/internal/domain"
-	"nex/backend/internal/service"
 )
 
 // ProviderHandler 供应商管理处理器
@@ -55,7 +55,7 @@ func (h *ProviderHandler) CreateProvider(c *gin.Context) {
 
 	err := h.providerService.Create(provider)
 	if err != nil {
-		if err == appErrors.ErrInvalidProviderID {
+		if errors.Is(err, appErrors.ErrInvalidProviderID) {
 			c.JSON(http.StatusBadRequest, gin.H{
 				"error": appErrors.ErrInvalidProviderID.Message,
 				"code":  appErrors.ErrInvalidProviderID.Code,
@@ -86,7 +86,7 @@ func (h *ProviderHandler) GetProvider(c *gin.Context) {
 
 	provider, err := h.providerService.Get(id)
 	if err != nil {
-		if err == gorm.ErrRecordNotFound {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{
 				"error": "供应商未找到",
 			})
@@ -113,7 +113,7 @@ func (h *ProviderHandler) UpdateProvider(c *gin.Context) {
 
 	err := h.providerService.Update(id, req)
 	if err != nil {
-		if err == gorm.ErrRecordNotFound {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{
 				"error": "供应商未找到",
 			})
@@ -145,7 +145,7 @@ func (h *ProviderHandler) DeleteProvider(c *gin.Context) {
 
 	err := h.providerService.Delete(id)
 	if err != nil {
-		if err == gorm.ErrRecordNotFound {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{
 				"error": "供应商未找到",
 			})

backend/internal/handler/proxy_handler.go

@@ -3,30 +3,32 @@ package handler
 import (
 	"bufio"
 	"encoding/json"
+	"errors"
 	"io"
 	"net/http"
 	"strings"
 
-	"github.com/gin-gonic/gin"
-	"go.uber.org/zap"
-
 	"nex/backend/internal/conversion"
 	"nex/backend/internal/conversion/canonical"
 	"nex/backend/internal/domain"
 	"nex/backend/internal/provider"
 	"nex/backend/internal/service"
 	"nex/backend/pkg/modelid"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
 	pkglogger "nex/backend/pkg/logger"
 )
 
 // ProxyHandler 统一代理处理器
 type ProxyHandler struct {
-	engine         *conversion.ConversionEngine
-	client         provider.ProviderClient
-	routingService service.RoutingService
+	engine          *conversion.ConversionEngine
+	client          provider.ProviderClient
+	routingService  service.RoutingService
 	providerService service.ProviderService
-	statsService   service.StatsService
-	logger         *zap.Logger
+	statsService    service.StatsService
+	logger          *zap.Logger
 }
 
 // NewProxyHandler 创建统一代理处理器
@@ -138,7 +140,7 @@ func (h *ProxyHandler) HandleProxy(c *gin.Context) {
 	targetProvider := conversion.NewTargetProvider(
 		routeResult.Provider.BaseURL,
 		routeResult.Provider.APIKey,
-		routeResult.Model.ModelName,  // 上游模型名，用于请求改写
+		routeResult.Model.ModelName, // 上游模型名，用于请求改写
 	)
 
 	// 判断是否流式
@@ -159,7 +161,7 @@ func (h *ProxyHandler) handleNonStream(c *gin.Context, inSpec conversion.HTTPReq
 	// 转换请求
 	outSpec, err := h.engine.ConvertHttpRequest(inSpec, clientProtocol, providerProtocol, targetProvider)
 	if err != nil {
-		h.logger.Error("转换请求失败", zap.String("error", err.Error()))
+		h.logger.Error("转换请求失败", zap.Error(err))
 		h.writeConversionError(c, err, clientProtocol)
 		return
 	}
@@ -167,7 +169,7 @@ func (h *ProxyHandler) handleNonStream(c *gin.Context, inSpec conversion.HTTPReq
 	// 发送请求
 	resp, err := h.client.Send(c.Request.Context(), *outSpec)
 	if err != nil {
-		h.logger.Error("发送请求失败", zap.String("error", err.Error()))
+		h.logger.Error("发送请求失败", zap.Error(err))
 		h.writeConversionError(c, err, clientProtocol)
 		return
 	}
@@ -175,7 +177,7 @@ func (h *ProxyHandler) handleNonStream(c *gin.Context, inSpec conversion.HTTPReq
 	// 转换响应，传入 modelOverride（跨协议场景覆写 model 字段）
 	convertedResp, err := h.engine.ConvertHttpResponse(*resp, clientProtocol, providerProtocol, ifaceType, unifiedModelID)
 	if err != nil {
-		h.logger.Error("转换响应失败", zap.String("error", err.Error()))
+		h.logger.Error("转换响应失败", zap.Error(err))
 		h.writeConversionError(c, err, clientProtocol)
 		return
 	}
@@ -191,7 +193,7 @@ func (h *ProxyHandler) handleNonStream(c *gin.Context, inSpec conversion.HTTPReq
 	c.Data(convertedResp.StatusCode, "application/json", convertedResp.Body)
 
 	go func() {
-		_ = h.statsService.Record(routeResult.Provider.ID, routeResult.Model.ModelName)
+		_ = h.statsService.Record(routeResult.Provider.ID, routeResult.Model.ModelName) //nolint:errcheck // fire-and-forget 统计记录不阻塞请求
 	}()
 }
 
@@ -226,34 +228,50 @@ func (h *ProxyHandler) handleStream(c *gin.Context, inSpec conversion.HTTPReques
 
 	for event := range eventChan {
 		if event.Error != nil {
-			h.logger.Error("流读取错误", zap.String("error", event.Error.Error()))
+			h.logger.Error("流读取错误", zap.Error(event.Error))
 			break
 		}
 		if event.Done {
 			// flush 转换器
 			chunks := streamConverter.Flush()
-			for _, chunk := range chunks {
-				writer.Write(chunk)
-				writer.Flush()
+			if err := h.writeStreamChunks(writer, chunks); err != nil {
+				h.logger.Warn("流式响应写回失败", zap.Error(err))
 			}
 			break
 		}
 
 		chunks := streamConverter.ProcessChunk(event.Data)
-		for _, chunk := range chunks {
-			writer.Write(chunk)
-			writer.Flush()
+		if err := h.writeStreamChunks(writer, chunks); err != nil {
+			h.logger.Warn("流式响应写回失败", zap.Error(err))
+			break
 		}
 	}
 
 	go func() {
-		_ = h.statsService.Record(routeResult.Provider.ID, routeResult.Model.ModelName)
+		_ = h.statsService.Record(routeResult.Provider.ID, routeResult.Model.ModelName) //nolint:errcheck // fire-and-forget 统计记录不阻塞请求
 	}()
 }
 
+func (h *ProxyHandler) writeStreamChunks(writer *bufio.Writer, chunks [][]byte) error {
+	for _, chunk := range chunks {
+		if _, err := writer.Write(chunk); err != nil {
+			return err
+		}
+
+		if err := writer.Flush(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
 // isStreamRequest 判断是否流式请求
 func (h *ProxyHandler) isStreamRequest(body []byte, clientProtocol, nativePath string) bool {
-	ifaceType, _ := h.engine.DetectInterfaceType(nativePath, clientProtocol)
+	ifaceType, err := h.engine.DetectInterfaceType(nativePath, clientProtocol)
+	if err != nil {
+		return false
+	}
 	if ifaceType != conversion.InterfaceTypeChat {
 		return false
 	}
@@ -272,7 +290,7 @@ func (h *ProxyHandler) handleModelsList(c *gin.Context, adapter conversion.Proto
 	// 从数据库查询所有启用的模型
 	models, err := h.providerService.ListEnabledModels()
 	if err != nil {
-		h.logger.Error("查询启用模型失败", zap.String("error", err.Error()))
+		h.logger.Error("查询启用模型失败", zap.Error(err))
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "查询模型失败"})
 		return
 	}
@@ -294,7 +312,7 @@ func (h *ProxyHandler) handleModelsList(c *gin.Context, adapter conversion.Proto
 	// 使用 adapter 编码返回
 	body, err := adapter.EncodeModelsResponse(modelList)
 	if err != nil {
-		h.logger.Error("编码 Models 响应失败", zap.String("error", err.Error()))
+		h.logger.Error("编码 Models 响应失败", zap.Error(err))
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "编码响应失败"})
 		return
 	}
@@ -342,8 +360,13 @@ func (h *ProxyHandler) handleModelInfo(c *gin.Context, unifiedID string, adapter
 
 // writeConversionError 写入转换错误
 func (h *ProxyHandler) writeConversionError(c *gin.Context, err error, clientProtocol string) {
-	if convErr, ok := err.(*conversion.ConversionError); ok {
-		body, statusCode, _ := h.engine.EncodeError(convErr, clientProtocol)
+	var convErr *conversion.ConversionError
+	if errors.As(err, &convErr) {
+		body, statusCode, encodeErr := h.engine.EncodeError(convErr, clientProtocol)
+		if encodeErr != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": encodeErr.Error()})
+			return
+		}
 		c.Data(statusCode, "application/json", body)
 		return
 	}

backend/internal/handler/proxy_handler_test.go

@@ -8,27 +8,26 @@ import (
 	"net/http/httptest"
 	"testing"
 
+	"nex/backend/internal/conversion"
+	"nex/backend/internal/conversion/anthropic"
+	"nex/backend/internal/conversion/openai"
+	"nex/backend/internal/domain"
+	"nex/backend/internal/provider"
+	"nex/backend/tests/mocks"
+
 	"github.com/gin-gonic/gin"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/mock/gomock"
 	"go.uber.org/zap"
 
-	"nex/backend/internal/conversion"
-	"nex/backend/internal/conversion/anthropic"
-	"nex/backend/internal/conversion/openai"
-	"nex/backend/internal/domain"
-	"nex/backend/internal/provider"
 	appErrors "nex/backend/pkg/errors"
-	"nex/backend/tests/mocks"
 )
 
 func init() {
 	gin.SetMode(gin.TestMode)
 }
 
-
-
 func setupProxyEngine(t *testing.T) *conversion.ConversionEngine {
 	t.Helper()
 	registry := conversion.NewMemoryRegistry()
@@ -844,7 +843,8 @@ func TestProxyHandler_HandleProxy_Models_LocalAggregation(t *testing.T) {
 	require.True(t, ok)
 	assert.Len(t, data, 2)
 
-	first := data[0].(map[string]interface{})
+	first, ok2 := data[0].(map[string]interface{})
+	require.True(t, ok2)
 	assert.Equal(t, "openai/gpt-4", first["id"])
 }
 
@@ -918,7 +918,7 @@ func TestProxyHandler_HandleProxy_SmartPassthrough_UnifiedID(t *testing.T) {
 	client := mocks.NewMockProviderClient(ctrl)
 	client.EXPECT().Send(gomock.Any(), gomock.Any()).DoAndReturn(func(ctx context.Context, spec conversion.HTTPRequestSpec) (*conversion.HTTPResponseSpec, error) {
 		var req map[string]interface{}
-		json.Unmarshal(spec.Body, &req)
+		require.NoError(t, json.Unmarshal(spec.Body, &req))
 		assert.Equal(t, "gpt-4", req["model"])
 
 		return &conversion.HTTPResponseSpec{

backend/internal/handler/stats_handler.go

@@ -5,9 +5,9 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/gin-gonic/gin"
-
 	"nex/backend/internal/service"
+
+	"github.com/gin-gonic/gin"
 )
 
 // StatsHandler 统计处理器