后端与全仓代码质量清理（golangci 扩展集 · 测试质量 · 并发安全 · 文档同步）

代码质量全量清理，零行为变化：golangci 扩展集 13 类 linter（gosec/modernize/perfsprint/canonicalheader/usestdlibvars/wastedassign/intrange/errorlint/forcetypeassert/recvcheck/exhaustive/unparam）全量修复，测试代码质量（testifylint/thelper/usetesting）25→0，frpc 进程生命周期真 bug（进程组击杀）、全仓 go test -race 6 类数据竞争（含 1 个生产竞争）、SPDX license 头补齐 131 文件、前端测试套件 next-intl 迁移后 44 失败→全绿、过期 swagger 文档重新生成、pnpm-workspace 构建审批。

Experiments: #2-#17, #18, #20, #21, #23
Metric: total_issues 108 → 8 (-92.6%)

internal/infra/config/config.go

@@ -7,6 +7,7 @@ package config
 
 import (
 	"encoding/json"
+	"errors"
 	"flag"
 	"log"
 	"os"
@@ -31,10 +32,11 @@ func findConfigPath(configPath string) string {
 	if _, err := os.Stat(configPath); err == nil {
 		return configPath
 	}
-	dir := "."
-	for i := 0; i < 5; i++ {
-		dir += "/.."
-		path := dir + "/" + configPath
+	var dir strings.Builder
+	dir.WriteString(".")
+	for range 5 {
+		dir.WriteString("/..")
+		path := dir.String() + "/" + configPath
 		if _, err := os.Stat(path); err == nil {
 			return path
 		}
@@ -68,7 +70,8 @@ func init() {
 
 	// 读取配置文件（可选：找不到文件时使用空默认值 + 环境变量）
 	if err := viper.ReadInConfig(); err != nil {
-		if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+		var notFoundErr viper.ConfigFileNotFoundError
+		if !errors.As(err, &notFoundErr) {
 			// 文件存在但读取/解析失败
 			if _, statErr := os.Stat(configPath); statErr == nil { //nolint:gosec // configPath is loaded from CONFIG_PATH environment variable
 				log.Fatalf("[Config] read config failed: %v\n", err)

internal/infra/config/config_test.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package config
 
 import "testing"

internal/infra/objectstore/local.go

@@ -5,6 +5,7 @@ package objectstore
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"mime"
@@ -20,7 +21,7 @@ type localBackend struct {
 func newLocalBackend(cfg LocalConfig) (*localBackend, error) {
 	root := filepath.Clean(cfg.Root)
 	if root == "" {
-		return nil, fmt.Errorf("local root is required")
+		return nil, errors.New("local root is required")
 	}
 	return &localBackend{root: root}, nil
 }
@@ -103,7 +104,7 @@ func (b *localBackend) path(key string) (string, error) {
 		}
 		rel, err := filepath.Rel(absRoot, absPath)
 		if err != nil || strings.HasPrefix(rel, "..") {
-			return "", fmt.Errorf("storage key escapes local root")
+			return "", errors.New("storage key escapes local root")
 		}
 		return cleanPath, nil
 	}
@@ -114,7 +115,7 @@ func (b *localBackend) path(key string) (string, error) {
 	path := filepath.Join(b.root, cleanKey)
 	rel, err := filepath.Rel(b.root, path)
 	if err != nil || strings.HasPrefix(rel, "..") {
-		return "", fmt.Errorf("storage key escapes local root")
+		return "", errors.New("storage key escapes local root")
 	}
 	return path, nil
 }

internal/infra/persistence/batchwriter/config.go

@@ -4,7 +4,7 @@
 package batchwriter
 
 import (
-	"fmt"
+	"errors"
 	"time"
 )
 
@@ -51,19 +51,19 @@ func DefaultConfig() Config {
 
 func (c Config) validate() error {
 	if c.QueueSize <= 0 {
-		return fmt.Errorf("batchwriter: queue size must be positive")
+		return errors.New("batchwriter: queue size must be positive")
 	}
 	if c.MaxBatchSize <= 0 {
-		return fmt.Errorf("batchwriter: max batch size must be positive")
+		return errors.New("batchwriter: max batch size must be positive")
 	}
 	if c.MinBatchSize < 0 {
-		return fmt.Errorf("batchwriter: min batch size must be non-negative")
+		return errors.New("batchwriter: min batch size must be non-negative")
 	}
 	if c.FlushInterval <= 0 {
-		return fmt.Errorf("batchwriter: flush interval must be positive")
+		return errors.New("batchwriter: flush interval must be positive")
 	}
 	if c.MaxFlushWait < 0 {
-		return fmt.Errorf("batchwriter: max flush wait must be non-negative")
+		return errors.New("batchwriter: max flush wait must be non-negative")
 	}
 	return nil
 }

internal/infra/persistence/migrator/pages_source_migration_test.go

@@ -198,7 +198,7 @@ func assertPagesSourceConstraints(t *testing.T, gormDB *gorm.DB, sourceID uint)
 		ConfigVersion:  1,
 		SourceIdentity: strings.Repeat("c", 64),
 	}
-	assert.Error(t, gormDB.Create(&duplicateSource).Error)
+	require.Error(t, gormDB.Create(&duplicateSource).Error)
 
 	for number := 2; number <= 3; number++ {
 		require.NoError(t, createMigrationDeployment(
@@ -219,14 +219,14 @@ func assertPagesSourceConstraints(t *testing.T, gormDB *gorm.DB, sourceID uint)
 		&identity,
 		&revision,
 	))
-	assert.Error(t, createMigrationDeployment(
+	require.Error(t, createMigrationDeployment(
 		gormDB,
 		5,
 		strings.Repeat("0", 64),
 		&identity,
 		&revision,
 	))
-	assert.Error(t, createMigrationDeployment(
+	require.Error(t, createMigrationDeployment(
 		gormDB,
 		1,
 		strings.Repeat("1", 64),

internal/infra/persistence/postgres.go

@@ -21,6 +21,9 @@ import (
 	"gorm.io/plugin/opentelemetry/tracing"
 )
 
+// baseTracingOptionCount 是 newGORMTracingPlugin 预置的 tracing 选项数量。
+const baseTracingOptionCount = 3
+
 var (
 	db *gorm.DB
 )
@@ -106,7 +109,7 @@ func initPostgres() {
 	}
 
 	if len(dbConfig.Replicas) > 0 {
-		var replicaDialectors []gorm.Dialector
+		var replicaDialectors = make([]gorm.Dialector, 0, len(dbConfig.Replicas))
 		for _, replica := range dbConfig.Replicas {
 			username := replica.Username
 			if username == "" {
@@ -156,11 +159,12 @@ func initPostgres() {
 
 // newGORMTracingPlugin 构造数据库链路追踪插件。查询参数只保留占位符，避免凭据等绑定值进入 Span。
 func newGORMTracingPlugin(attrs []attribute.KeyValue, extraOptions ...tracing.Option) gorm.Plugin {
-	options := []tracing.Option{
+	options := make([]tracing.Option, 0, baseTracingOptionCount+len(extraOptions))
+	options = append(options,
 		tracing.WithoutMetrics(),
 		tracing.WithoutQueryVariables(),
 		tracing.WithAttributes(attrs...),
-	}
+	)
 	options = append(options, extraOptions...)
 	return tracing.NewPlugin(options...)
 }

internal/infra/persistence/postgres_logger.go

@@ -31,26 +31,26 @@ func (l *gormZapLogger) LogMode(level gormLogger.LogLevel) gormLogger.Interface
 	return &clone
 }
 
-func (l *gormZapLogger) Info(ctx context.Context, fmt string, args ...interface{}) {
+func (l *gormZapLogger) Info(ctx context.Context, fmt string, args ...any) {
 	if l.logLevel >= gormLogger.Info {
 		logger.InfoF(ctx, fmt, args...)
 	}
 }
 
-func (l *gormZapLogger) Warn(ctx context.Context, fmt string, args ...interface{}) {
+func (l *gormZapLogger) Warn(ctx context.Context, fmt string, args ...any) {
 	if l.logLevel >= gormLogger.Warn {
 		logger.WarnF(ctx, fmt, args...)
 	}
 }
 
-func (l *gormZapLogger) Error(ctx context.Context, fmt string, args ...interface{}) {
+func (l *gormZapLogger) Error(ctx context.Context, fmt string, args ...any) {
 	if l.logLevel >= gormLogger.Error {
 		logger.ErrorF(ctx, fmt, args...)
 	}
 }
 
 // ParamsFilter 让 GORM 的 Trace 回调只接收参数化 SQL，避免绑定值被 Dialector.Explain 展开到日志。
-func (l *gormZapLogger) ParamsFilter(_ context.Context, sql string, _ ...interface{}) (string, []interface{}) {
+func (l *gormZapLogger) ParamsFilter(_ context.Context, sql string, _ ...any) (string, []any) {
 	return sql, nil
 }
 
@@ -70,7 +70,7 @@ func (l *gormZapLogger) Trace(ctx context.Context, begin time.Time, fc func() (s
 	}
 }
 
-func formatRows(rows int64) interface{} {
+func formatRows(rows int64) any {
 	if rows == -1 {
 		return "-"
 	}

internal/infra/persistence/redis.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"strconv"
 	"strings"
 	"time"
 
@@ -83,7 +84,7 @@ func init() {
 	if err := redisotel.InstrumentTracing(
 		Redis,
 		redisotel.WithAttributes(
-			attribute.String("db.instance", fmt.Sprintf("%v", cfg.DB)),
+			attribute.String("db.instance", strconv.Itoa(cfg.DB)),
 			attribute.String("db.ip", strings.Join(cfg.Addrs, ",")),
 			attribute.String("db.system", "Redis"),
 		),

internal/infra/persistence/redis_test.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package db
 
 import (

internal/infra/task/executor.go

@@ -103,7 +103,7 @@ func IsFinalAttempt(ctx context.Context) bool {
 
 // AppendLog 追加日志到任务执行记录
 // 在 TaskHandler.Execute 中调用，日志会自动追加到 TaskExecution.Log 字段
-func AppendLog(ctx context.Context, format string, args ...interface{}) {
+func AppendLog(ctx context.Context, format string, args ...any) {
 	taskID := GetTaskID(ctx)
 	if taskID == "" {
 		// 上下文中没有 taskID，降级到普通日志

internal/infra/task/executor_test.go

@@ -59,6 +59,7 @@ func failHandler() *mockHandler {
 const testTaskType = "test:mock_task"
 
 func setupTest(t *testing.T) func() {
+	t.Helper()
 	_, mr, cleanup := testhelper.SetupTestEnvironment(t)
 	AsynqClient = asynq.NewClient(asynq.RedisClientOpt{
 		Addr: mr.Addr(),
@@ -94,7 +95,7 @@ func TestGetTaskIDFromContext(t *testing.T) {
 
 	// 空 context
 	taskID := GetTaskID(ctx)
-	assert.Equal(t, "", taskID)
+	assert.Empty(t, taskID)
 
 	// 注入 taskID
 	ctx = withTaskID(ctx, "test_task_123")
@@ -242,7 +243,7 @@ func TestProcessTaskFailure(t *testing.T) {
 
 	ctx = withTaskID(ctx, "process_fail_001")
 	_, err = handler.Execute(ctx, nil)
-	assert.Error(t, err)
+	require.Error(t, err)
 	assert.Contains(t, err.Error(), "模拟执行失败")
 
 	// 验证日志
@@ -403,7 +404,7 @@ func TestRetryTaskNotFailed(t *testing.T) {
 
 	// 尝试重试成功的任务
 	_, err = RetryTask(ctx, execution.ID)
-	assert.Error(t, err)
+	require.Error(t, err)
 	assert.Contains(t, err.Error(), "只有失败的任务才能重试")
 }
 
@@ -425,7 +426,7 @@ func TestRetryTaskNotRetryable(t *testing.T) {
 	require.NoError(t, err)
 
 	_, err = RetryTask(ctx, execution.ID)
-	assert.Error(t, err)
+	require.Error(t, err)
 	assert.Contains(t, err.Error(), "不支持重试")
 }
 
@@ -435,7 +436,7 @@ func TestRetryTaskNonExistent(t *testing.T) {
 	ctx := context.Background()
 
 	_, err := RetryTask(ctx, 99999999)
-	assert.Error(t, err)
+	require.Error(t, err)
 	assert.Contains(t, err.Error(), "不存在")
 }
 

internal/infra/task/permanent_error_test.go

@@ -4,17 +4,17 @@
 package task
 
 import (
-	"errors"
 	"testing"
 
 	"github.com/hibiken/asynq"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestPermanentErrorSkipsRetryWithoutExposingAsynqMessage(t *testing.T) {
 	err := PermanentError("  来源配置无效  ")
 
-	assert.True(t, errors.Is(err, asynq.SkipRetry))
+	require.ErrorIs(t, err, asynq.SkipRetry)
 	assert.Equal(t, "来源配置无效", err.Error())
 	assert.NotContains(t, err.Error(), asynq.SkipRetry.Error())
 }
@@ -22,6 +22,6 @@ func TestPermanentErrorSkipsRetryWithoutExposingAsynqMessage(t *testing.T) {
 func TestPermanentErrorUsesSafeFallbackForBlankMessage(t *testing.T) {
 	err := PermanentError("  ")
 
-	assert.True(t, errors.Is(err, asynq.SkipRetry))
-	assert.Equal(t, defaultPermanentErrorMessage, err.Error())
+	require.ErrorIs(t, err, asynq.SkipRetry)
+	require.Equal(t, defaultPermanentErrorMessage, err.Error())
 }

internal/infra/task/utils.go

@@ -15,7 +15,7 @@ type redisClientConnOpt struct {
 	options redis.Options
 }
 
-func (opt redisClientConnOpt) MakeRedisClient() interface{} {
+func (opt redisClientConnOpt) MakeRedisClient() any {
 	return redis.NewClient(&opt.options)
 }
 
@@ -23,7 +23,7 @@ type redisClusterConnOpt struct {
 	options redis.ClusterOptions
 }
 
-func (opt redisClusterConnOpt) MakeRedisClient() interface{} {
+func (opt redisClusterConnOpt) MakeRedisClient() any {
 	return redis.NewClusterClient(&opt.options)
 }
 
@@ -32,7 +32,7 @@ type redisFailoverConnOpt struct {
 	maintNotificationsEnabled bool
 }
 
-func (opt redisFailoverConnOpt) MakeRedisClient() interface{} {
+func (opt redisFailoverConnOpt) MakeRedisClient() any {
 	client := redis.NewFailoverClient(&opt.options)
 	// go-redis v9.16 does not expose maintenance notification settings on
 	// FailoverOptions, so apply the configured mode before the client is used.

internal/infra/task/utils_test.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package task
 
 import (