从零写一个生产可用的 Gin 脚手架

# 步骤 1：创建项目目录并进入
mkdir -p gin-scaffold && cd gin-scaffold

# 步骤 2：初始化 Go module。
# 本项目直接以项目名作为 module 路径；要发布到 GitHub 的话，
# 习惯写成 github.com/你的用户名/gin-scaffold
go mod init gin-scaffold

# 步骤 3：安装本篇会用到的依赖（一次装齐）
go get github.com/gin-gonic/gin
go get gorm.io/gorm
go get gorm.io/driver/mysql
go get github.com/redis/go-redis/v9
go get go.uber.org/zap
go get gopkg.in/natefinch/lumberjack.v2
go get github.com/spf13/viper
go get github.com/go-viper/mapstructure/v2
go get github.com/golang-jwt/jwt/v5
go get github.com/google/uuid
go get github.com/google/wire
go get golang.org/x/crypto
go get golang.org/x/time
go get github.com/swaggo/files
go get github.com/swaggo/gin-swagger

mkdir -p cmd/server configs \
         internal/config internal/data internal/handler/dto internal/middleware \
         internal/model internal/repository internal/router internal/server internal/service \
         pkg/errcode pkg/jwt pkg/logger pkg/response

gin-scaffold/
├── cmd/
│   └── server/
│       ├── main.go        # 程序入口：只有"启动流程"，没有业务
│       ├── wire.go        # Wire 依赖声明（写给人看）
│       ├── wire_gen.go    # Wire 生成的装配代码（写给机器跑）
│       └── providers.go   # 配置结构转换的小适配函数
├── configs/
│   ├── config.yaml        # 开发环境配置
│   └── config.prod.yaml   # 生产环境配置（敏感项走环境变量）
├── internal/              # 私有代码，外部模块无法 import（编译器强制）
│   ├── config/            # 配置结构体定义、加载与校验
│   ├── data/              # 数据层：MySQL/Redis 客户端、连接池、事务管理器
│   ├── model/             # GORM 数据模型（表结构）
│   ├── repository/        # 数据访问层：只管读写库与缓存
│   ├── service/           # 业务层：业务规则、事务边界、错误翻译
│   ├── handler/           # 接口层：参数绑定校验、调用 service、渲染响应
│   │   └── dto/           # 请求/响应的数据传输对象
│   ├── middleware/        # 中间件：Recovery/RequestID/AccessLog/CORS/RateLimit/JWT
│   ├── router/            # 路由组装：中间件 + 分组 + 各 handler
│   └── server/            # HTTP Server 封装与生命周期管理
├── pkg/                   # 可复用公共库（与业务无关，可被任意项目抄走）
│   ├── errcode/           # 统一错误码定义
│   ├── jwt/               # JWT 签发与解析
│   ├── logger/            # zap 日志封装
│   └── response/          # 统一响应格式
├── Makefile               # 常用命令集合（run/build/test/wire/swagger…）
├── docker-compose.yml     # 一键启动 MySQL + Redis + 应用
├── Dockerfile             # 多阶段构建生产镜像
├── go.mod
└── go.sum

按模块分包（另一种常见做法）        按层分包 + 模块文件前缀（本项目）
├── internal/                     ├── internal/
│   ├── user/                     │   ├── handler/
│   │   ├── model.go              │   │   ├── user_handler.go
│   │   ├── repository.go         │   │   └── dto/
│   │   ├── service.go            │   ├── service/
│   │   └── handler.go            │   │   └── user_service.go
│   └── order/                    │   ├── repository/
│       └── ...                   │   │   └── user_repo.go
                                  │   └── model/
                                  │       └── user.go

// Config 应用全量配置根结构。
type Config struct {
	App       App       `mapstructure:"app"`
	HTTP      HTTP      `mapstructure:"http"`
	MySQL     MySQL     `mapstructure:"mysql"`
	Redis     Redis     `mapstructure:"redis"`
	JWT       JWT       `mapstructure:"jwt"`
	Log       Log       `mapstructure:"log"`
	RateLimit RateLimit `mapstructure:"rate_limit"`
	CORS      CORS      `mapstructure:"cors"`
}

// HTTP HTTP Server 配置，所有超时必须显式配置，防止慢连接拖垮服务。
type HTTP struct {
	Addr              string        `mapstructure:"addr"`
	ReadHeaderTimeout time.Duration `mapstructure:"read_header_timeout"`
	ReadTimeout       time.Duration `mapstructure:"read_timeout"`
	WriteTimeout      time.Duration `mapstructure:"write_timeout"`
	IdleTimeout       time.Duration `mapstructure:"idle_timeout"`
	// 可信代理 CIDR 列表。空列表 = 不信任任何代理，ClientIP 取直连地址；
	// 若不显式设置，gin 默认信任所有代理头，X-Forwarded-For 可被伪造，
	// 按 IP 的限流、风控将形同虚设
	TrustedProxies []string `mapstructure:"trusted_proxies"`
}

// MySQL 数据库配置。
type MySQL struct {
	DSN             string        `mapstructure:"dsn"`
	MaxOpenConns    int           `mapstructure:"max_open_conns"`
	MaxIdleConns    int           `mapstructure:"max_idle_conns"`
	ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"`
}

// Redis 缓存配置。
type Redis struct {
	Addr         string        `mapstructure:"addr"`
	Password     string        `mapstructure:"password"`
	DB           int           `mapstructure:"db"`
	PoolSize     int           `mapstructure:"pool_size"`
	DialTimeout  time.Duration `mapstructure:"dial_timeout"`
	ReadTimeout  time.Duration `mapstructure:"read_timeout"`
	WriteTimeout time.Duration `mapstructure:"write_timeout"`
}

// JWT 认证配置。
type JWT struct {
	Secret string        `mapstructure:"secret"`
	Issuer string        `mapstructure:"issuer"`
	Expire time.Duration `mapstructure:"expire"`
}

// Log / RateLimit / CORS 结构同理，字段见 config.yaml，此处略

// Load 从指定路径读取配置文件并完成环境变量覆盖与校验。
// 任何必填项缺失都会导致启动失败，错误信息中列出全部缺失字段。
func Load(path string) (*Config, error) {
	v := viper.New()
	v.SetConfigFile(path)

	// 步骤 1：环境变量覆盖规则。
	// 前缀 APP_ + 配置路径大写、点号转下划线：
	// mysql.dsn -> APP_MYSQL_DSN，jwt.secret -> APP_JWT_SECRET
	v.SetEnvPrefix("APP")
	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
	v.AutomaticEnv()

	// 步骤 2：读取并解析配置文件
	if err := v.ReadInConfig(); err != nil {
		return nil, fmt.Errorf("读取配置文件 %s 失败: %w", path, err)
	}

	var cfg Config
	// 步骤 3：关键！注册 decode hook，
	// 把 "5s" / "24h" 这类字符串正确映射为 time.Duration
	if err := v.Unmarshal(&cfg, viper.DecodeHook(mapstructure.StringToTimeDurationHookFunc())); err != nil {
		return nil, fmt.Errorf("解析配置失败: %w", err)
	}

	// 步骤 4：语义校验，任何必填项缺失立即返回错误
	if err := cfg.validate(); err != nil {
		return nil, err
	}
	return &cfg, nil
}

// validate 启动期强校验：缺配置直接 fail fast，而不是带病运行到第一次请求才报错。
func (c *Config) validate() error {
	// 步骤 1：收集所有缺失的必填项，一次性报出来
	// （而不是缺一个报一个，逼用户反复重启试错）
	var missing []string
	if c.HTTP.Addr == "" {
		missing = append(missing, "http.addr")
	}
	if c.MySQL.DSN == "" {
		missing = append(missing, "mysql.dsn")
	}
	if c.Redis.Addr == "" {
		missing = append(missing, "redis.addr")
	}
	if c.JWT.Secret == "" {
		missing = append(missing, "jwt.secret")
	}
	if len(c.JWT.Secret) < 32 {
		// HS256 密钥低于 32 字节可被暴力破解：启动期拦截
		missing = append(missing, "jwt.secret(长度须不少于 32 字节)")
	}
	if c.JWT.Issuer == "" {
		missing = append(missing, "jwt.issuer")
	}
	if c.JWT.Expire <= 0 {
		missing = append(missing, "jwt.expire")
	}
	if len(missing) > 0 {
		return fmt.Errorf("配置缺失必填项: %s", strings.Join(missing, ", "))
	}

	// 步骤 2：可信代理段在启动期完成 CIDR 解析校验，
	// 非法值 fail fast，避免运行期才发现 ClientIP 失真
	for _, cidr := range c.HTTP.TrustedProxies {
		if _, _, err := net.ParseCIDR(cidr); err != nil {
			return fmt.Errorf("http.trusted_proxies 包含非法 CIDR %q: %w", cidr, err)
		}
	}
	return nil
}

# 本地开发环境配置。
# 敏感项（数据库密码、JWT 密钥）支持环境变量覆盖：
# mysql.dsn -> APP_MYSQL_DSN，jwt.secret -> APP_JWT_SECRET

app:
  name: gin-scaffold
  version: 1.0.0
  debug_port: 6060      # pprof 调试端口（只监听 127.0.0.1），0 表示关闭

http:
  addr: ":8080"
  read_header_timeout: 5s
  read_timeout: 10s
  write_timeout: 10s
  idle_timeout: 120s
  trusted_proxies: []   # 空列表 = 不信任任何代理，防止 X-Forwarded-For 伪造

mysql:
  dsn: "root:123456@tcp(127.0.0.1:3306)/gin_scaffold?charset=utf8mb4&parseTime=True&loc=Local"
  max_open_conns: 100
  max_idle_conns: 10
  conn_max_lifetime: 1h

redis:
  addr: "127.0.0.1:6379"
  password: ""
  db: 0
  pool_size: 100
  dial_timeout: 3s
  read_timeout: 1s
  write_timeout: 1s

jwt:
  secret: "dev-only-secret-change-me-32bytes-ok!"   # 生产必须走 APP_JWT_SECRET 注入
  issuer: "gin-scaffold"
  expire: 24h

log:
  level: info           # 开发期可改 debug，SQL 日志会跟着打印
  dir: ./logs           # 留空表示只输出控制台（容器场景推荐）
  prefix: app            # -> app-2026-09-09.info.log / app-2026-09-09.error.log
  max_size: 100          # 单文件最大 MB，超过由 lumberjack 二次切割
  max_backups: 7         # 保留的归档天数
  max_age: 30            # 归档保留天数
  compress: true         # 历史日志 gzip 压缩

  console: true          # 控制台输出（zap 统一接管，含 gin 自身输出）
  console_async: false   # 控制台保持同步，顺序与实时性最好
  async: true            # 文件异步写入：业务只投递不落盘
  queue_size: 8192       # 异步队列容量
  batch_size: 256        # 攒够多少条批量写盘
  flush_interval: 1s     # 定时刷盘窗口
  enqueue_timeout: 200ms # 队列满时最长等待，超时丢弃并计数自报

  caller: true           # 打印调用点
  stacktrace: true       # error 及以上自动带堆栈

  slow_threshold: 500ms  # 访问日志：慢请求阈值，超过提升为 Warn 并打 slow 标记
  skip_paths:            # 探针路径不打访问日志，避免被健康检查刷爆
    - /healthz
    - /readyz

rate_limit:
  rps: 100              # 每秒每 IP 允许的请求数，0 表示关闭限流
  burst: 200

cors:
  allow_origins:
    - "http://localhost:3000"

app:
  build: .
  environment:
    APP_MYSQL_DSN: "root:123456@tcp(mysql:3306)/gin_scaffold?charset=utf8mb4&parseTime=True&loc=Local"
    APP_REDIS_ADDR: "redis:6379"
    APP_JWT_SECRET: "compose-only-secret-32bytes-change!"

go run ./cmd/server --config configs/config.yaml

// Config 日志配置。pkg 层包不引用 internal/config，
// 由 cmd/server 的 provider 负责把应用配置转换为本结构。
type Config struct {
	Level      string // debug / info / warn / error，默认 info
	Dir        string // 日志目录，为空表示只输出控制台（容器场景推荐）
	Prefix     string // 文件名前缀 -> app-2026-09-09.info.log
	MaxSizeMB  int    // 单文件最大 MB，超过由 lumberjack 二次切割
	MaxBackups int    // 保留的归档天数
	MaxAgeDays int    // 归档保留天数
	Compress   bool   // 历史日志 gzip 压缩

	Console      bool          // 是否输出控制台
	ConsoleAsync bool          // 控制台是否异步（容器采集建议 false）
	Async        bool          // 文件是否异步写入
	QueueSize    int           // 异步队列容量，默认 8192
	BatchSize    int           // 攒够多少条批量写盘，默认 256
	FlushInterval time.Duration // 定时刷盘窗口，默认 1s
	EnqueueTimeout time.Duration // 队列满时最长等待，超时丢弃，默认 200ms

	Caller     bool // 打印调用点
	Stacktrace bool // error 及以上自动带堆栈
}

	// 分级闸门：靠 LevelEnabler 过滤，而不是「写两份再靠文件名区分」，
	// 保证 error 不会重复出现在 info 文件里。
	infoLevel := zap.LevelEnablerFunc(func(l zapcore.Level) bool {
		return l >= level && l < zapcore.ErrorLevel
	})
	errorLevel := zap.LevelEnablerFunc(func(l zapcore.Level) bool {
		return l >= level && l >= zapcore.ErrorLevel
	})

	cores = append(cores,
		zapcore.NewCore(fileEncoder, infoWS, infoLevel),
		zapcore.NewCore(fileEncoder, errorWS, errorLevel),
	)

	log := zap.New(zapcore.NewTee(cores...), zap.AddCaller(), zap.AddStacktrace(zapcore.ErrorLevel))

	// 关停顺序不能反：先停投递并排空异步队列，最后刷盘，否则会丢一批日志
	cleanup := func() {
		for _, c := range closers {
			_ = c.Close()
		}
		_ = log.Sync()
	}
	return log, cleanup, nil

// New 构建日志实例。返回的 cleanup 负责关停异步队列并刷盘，
// 由 wire 编排为整个依赖清理链的一环，保证最后才关日志。
func New(cfg Config) (*zap.Logger, func(), error) {
	// 级别解析失败直接报错——启动即失败，
	// 杜绝"以为开了 debug 实际一条没打"的静默降级
	...

	// 控制台 core + info/error 两个文件 core，Tee 汇成一颗日志树
	...

	// 全局归口：标准库 log 与第三方库的输出也走 zap，避免日志分裂
	zap.ReplaceGlobals(log)
	zap.RedirectStdLog(log)

	cleanup := ...
	return log, cleanup, nil
}

log.Info("MySQL 连接就绪", zap.String("addr", "127.0.0.1:3306"))
log.Error("创建用户失败", zap.Error(err))

2026-09-09 13:01:02.512  INFO  data/data.go:75  MySQL 连接就绪  {"addr": "127.0.0.1:3306"}

{"level":"info","time":"2026-09-09T13:01:02.512+0800","caller":"data/data.go:75","msg":"MySQL 连接就绪","addr":"127.0.0.1:3306"}

type loggerKey struct{} // 空结构体做 context 键，全宇宙不撞车

// WithLogger 将日志实例（通常是带 request_id 字段的子实例）放入 context。
func WithLogger(ctx context.Context, log *zap.Logger) context.Context {
	return context.WithValue(ctx, loggerKey{}, log)
}

// FromContext 取出 context 中的日志实例；未注入时返回 Nop 实例，
// 保证任意代码路径下调用都不 panic。
func FromContext(ctx context.Context) *zap.Logger {
	if log, ok := ctx.Value(loggerKey{}).(*zap.Logger); ok {
		return log
	}
	return zap.NewNop()
}

// FromContextOrDefault 未注入时返回 fallback，
// 供 data 层等无法保证 context 一定携带日志的基础设施代码使用。
func FromContextOrDefault(ctx context.Context, fallback *zap.Logger) *zap.Logger {
	if log, ok := ctx.Value(loggerKey{}).(*zap.Logger); ok {
		return log
	}
	return fallback
}

// Data 聚合 MySQL 与 Redis 客户端，由 wire 构造为单例注入 repository。
type Data struct {
	db  *gorm.DB
	rdb redis.UniversalClient
}

// New 初始化数据层资源。
// 返回的 cleanup 由 wire 编排：应用关停时先关连接，再执行上游（日志）的清理。
func New(cfg *config.Config, log *zap.Logger) (*Data, func(), error) {
	// 步骤 1：打开 MySQL（gorm.Open 是惰性建连，此时还没真正拨号）
	db, err := gorm.Open(mysql.Open(cfg.MySQL.DSN), &gorm.Config{
		// 把驱动层错误翻译为 gorm 通用错误：
		// MySQL 1062 -> gorm.ErrDuplicatedKey，上层不再感知具体数据库
		TranslateError: true,
		Logger:         newGormLogger(log), // SQL 日志桥接到 zap，见 4.4
		PrepareStmt:    true,               // 预编译语句缓存，高频查询省一轮往返
	})
	if err != nil {
		return nil, nil, fmt.Errorf("连接 MySQL 失败: %w", err)
	}

	// 步骤 2：设置连接池参数（GORM 是壳，这里拿到底层的 *sql.DB）
	sqlDB, err := db.DB()
	if err != nil {
		return nil, nil, fmt.Errorf("获取底层 SQL 连接池失败: %w", err)
	}
	sqlDB.SetMaxOpenConns(cfg.MySQL.MaxOpenConns)
	sqlDB.SetMaxIdleConns(cfg.MySQL.MaxIdleConns)
	sqlDB.SetConnMaxLifetime(cfg.MySQL.ConnMaxLifetime)

	// 步骤 3：初始化 Redis 客户端
	rdb := redis.NewClient(&redis.Options{
		Addr:         cfg.Redis.Addr,
		Password:     cfg.Redis.Password,
		DB:           cfg.Redis.DB,
		PoolSize:     cfg.Redis.PoolSize,
		DialTimeout:  cfg.Redis.DialTimeout,
		ReadTimeout:  cfg.Redis.ReadTimeout,
		WriteTimeout: cfg.Redis.WriteTimeout,
	})

	// 步骤 4：启动期对 Redis 做连通性探测，fail fast 而不是运行期才暴露。
	// 失败时顺手把已建好的 MySQL 连接池关掉，不留半开的资源
	pingCtx, cancel := context.WithTimeout(context.Background(), cfg.Redis.DialTimeout)
	defer cancel()
	if err := rdb.Ping(pingCtx).Err(); err != nil {
		_ = sqlDB.Close()
		return nil, nil, fmt.Errorf("连接 Redis 失败: %w", err)
	}

	// 步骤 5：返回清理函数，关停时逆序释放（第八章看 wire 怎么编排它）
	cleanup := func() {
		_ = sqlDB.Close()
		_ = rdb.Close()
	}
	return &Data{db: db, rdb: rdb}, cleanup, nil
}

// DB 返回 GORM 会话入口。
func (d *Data) DB() *gorm.DB { return d.db }

// RDB 返回 Redis 客户端。
func (d *Data) RDB() redis.UniversalClient { return d.rdb }

// 反面教材：事务连接污染了所有方法签名
func (s *Service) Register(ctx context.Context, ...) error {
	tx := s.db.Begin()
	s.repo.Create(ctx, tx, user)      // 每个方法都多一个 tx 参数
	s.accountRepo.Init(ctx, tx, ...)  // 不用事务的方法也得带个 nil
	...
}

// txKey 事务连接在 context 中的存取键（包内私有，避免 key 冲突与误用）。
type txKey struct{}

// TxManager 事务管理器接口，service 层只依赖本接口开启事务，
// 不感知 GORM 类型，保持业务层与数据层的解耦。
type TxManager interface {
	// InTransaction 在 fn 执行期间把事务连接注入 ctx：
	// fn 内经由 DBFrom 获取连接的 repository 调用自动进入同一事务；
	// fn 返回 error 时整体回滚，返回 nil 时提交。
	InTransaction(ctx context.Context, fn func(ctx context.Context) error) error
}

// InTransaction 实现 TxManager。事务边界一律在 service 层开启与提交，
// repository 不得自行管理事务。
func (d *Data) InTransaction(ctx context.Context, fn func(ctx context.Context) error) error {
	return d.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
		return fn(context.WithValue(ctx, txKey{}, tx))
	})
}

// DBFrom 返回当前上下文中应使用的数据库连接：
// 处于事务中（ctx 由 InTransaction 注入）时返回事务连接，否则返回主连接。
// repository 层所有读写必须经由本函数取连接，才能透明地加入事务。
func DBFrom(ctx context.Context, fallback *gorm.DB) *gorm.DB {
	if tx, ok := ctx.Value(txKey{}).(*gorm.DB); ok && tx != nil {
		return tx
	}
	return fallback
}

// service 层：fn 里的所有 repo 调用自动进入同一事务
err := s.txm.InTransaction(ctx, func(ctx context.Context) error {
	if err := s.repo.Create(ctx, user); err != nil {
		return err // 返回 error，整体回滚
	}
	// 真实场景继续调用其他 repo：初始化账户、发放积分……
	return nil // 返回 nil，整体提交
})

// slowSQLThreshold 慢 SQL 阈值，超过则打 WARN 日志。
const slowSQLThreshold = 200 * time.Millisecond

// newGormLogger 把 GORM 的日志桥接到 zap，级别随应用日志级别联动：
// debug -> 逐条记录 SQL；info -> 只记慢 SQL 和错误；再高 -> 只记错误
func newGormLogger(log *zap.Logger) gormlogger.Interface {
	lvl := gormlogger.Warn
	switch zapcore.Level(log.Level()) {
	case zapcore.DebugLevel:
		lvl = gormlogger.Info
	case zapcore.InfoLevel:
		lvl = gormlogger.Warn
	default:
		lvl = gormlogger.Error
	}
	return &gormLogger{log: log, level: lvl}
}

// Trace 是 GORM 每条 SQL 执行完的回调（Info/Warn/Error/LogMode 是
// 接口要求的样板方法，略）。执行出错 -> error、慢查询 -> warn。
func (g *gormLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error) {
	if g.level <= gormlogger.Silent {
		return
	}
	elapsed := time.Since(begin)
	sql, rows := fc()
	fields := []zap.Field{
		zap.Duration("elapsed", elapsed),
		zap.Int64("rows", rows),
		zap.String("sql", sql),
	}
	// 关键一行：从 context 取出带 request_id 的子日志实例，
	// SQL 日志因此和访问日志、业务日志共用同一串 ID
	log := logger.FromContextOrDefault(ctx, g.log)

	switch {
	case err != nil && !errors.Is(err, gorm.ErrRecordNotFound):
		log.Error("sql 执行失败", append(fields, zap.Error(err))...)
	case elapsed > slowSQLThreshold:
		log.Warn("慢 SQL", fields...)
	case g.level >= gormlogger.Info:
		log.Debug("sql", fields...)
	}
}

成功：{"code": 0,      "msg": "success",   "data": {...}}
失败：{"code": 200002, "msg": "用户名已存在", "data": null}

// Body 统一响应体。
type Body struct {
	Code int    `json:"code"`
	Msg  string `json:"msg"`
	Data any    `json:"data"`
}

// PageData 分页响应的 data 结构。
type PageData struct {
	List     any   `json:"list"`
	Total    int64 `json:"total"`
	Page     int   `json:"page"`
	PageSize int   `json:"page_size"`
}

// OK 返回成功响应。
func OK(c *gin.Context, data any) {
	c.JSON(http.StatusOK, Body{
		Code: errcode.Success.Code(),
		Msg:  errcode.Success.Msg(),
		Data: data,
	})
}

// Page 返回分页成功响应。
func Page(c *gin.Context, list any, total int64, page, pageSize int) {
	OK(c, PageData{List: list, Total: total, Page: page, PageSize: pageSize})
}

// Fail 返回失败响应。只接受错误码与消息，
// 避免调用方把内部错误细节（堆栈、SQL 等）直接透出。
func Fail(c *gin.Context, code int, msg string) {
	c.JSON(http.StatusOK, Body{Code: code, Msg: msg})
}

// ErrCode 业务错误类型，实现了 error 接口，
// 可通过 errors.Is / errors.As 与哨兵错误比较。
type ErrCode struct {
	code int
	msg  string
}

// New 创建一个错误码定义，仅允许在本包内集中声明，禁止散落在业务代码中。
func New(code int, msg string) *ErrCode { return &ErrCode{code: code, msg: msg} }

func (e *ErrCode) Code() int { return e.code }
func (e *ErrCode) Msg() string { return e.msg }
func (e *ErrCode) Error() string {
	return fmt.Sprintf("code: %d, msg: %s", e.code, e.msg)
}

// 通用错误段：100000-199999
var (
	Success            = New(0, "success")
	ErrServer          = New(100001, "服务器内部错误") // 细节只写日志，不暴露给调用方
	ErrInvalidParams   = New(100002, "参数错误")
	ErrNotFound        = New(100003, "资源不存在")
	ErrUnauthorized    = New(100004, "未授权或登录已过期")
	ErrTokenGenerate   = New(100005, "令牌生成失败")
	ErrTooManyRequests = New(100006, "请求过于频繁，请稍后再试")
)

// 用户模块错误段：200000-299999
var (
	ErrUserNotFound  = New(200001, "用户不存在")
	ErrUserDuplicate = New(200002, "用户名已存在")
	// 用户不存在与密码错误共用此码，不区分是哪个，防止账号枚举探测
	ErrPasswordWrong = New(200003, "用户名或密码错误")
	ErrUserDisabled  = New(200004, "用户已被禁用")
)

// Error 把任意 error 翻译为统一响应：
// 业务错误（*errcode.ErrCode）原样透出；其余一律归为服务器内部错误。
func Error(c *gin.Context, err error) {
	var ec *errcode.ErrCode
	if errors.As(err, &ec) {
		Fail(c, ec.Code(), ec.Msg())
		return
	}
	Fail(c, errcode.ErrServer.Code(), errcode.ErrServer.Msg())
}

// NewRecovery panic 恢复中间件：兜住所有 handler 里未捕获的 panic，
// 记录堆栈日志后返回统一错误响应，避免单个请求的 panic 打挂整个进程。
func NewRecovery(log *zap.Logger) gin.HandlerFunc {
	return func(c *gin.Context) {
		defer func() {
			if rec := recover(); rec != nil && rec != http.ErrAbortHandler {
				// 优先用 context 里带 request_id 的子日志实例，
				// 取不到才回退到传入的基础实例（比如 panic 发生在 RequestID 之前）
				logger.FromContextOrDefault(c.Request.Context(), log).Error("panic 已恢复",
					zap.Any("panic", rec),
					zap.ByteString("stack", debug.Stack()),
					zap.String("path", c.Request.URL.Path),
					zap.String("method", c.Request.Method),
				)
				// HTTP 500 而非业务码包 200：网关、LB 与监控的状态码
				// 告警只认 HTTP 状态码，panic 全走 200 会变成监控盲区
				//（与 readyz 的非 2xx 原则一致）。响应体仍保持统一格式。
				c.JSON(http.StatusInternalServerError, response.Body{
					Code: errcode.ErrServer.Code(),
					Msg:  errcode.ErrServer.Msg(),
				})
				c.Abort()
			}
		}()
		c.Next()
	}
}

// HeaderXRequestID 请求追踪头，响应中原样透传。
const HeaderXRequestID = "X-Request-ID"

// NewRequestID 请求追踪中间件：
//  1. 优先透传上游网关传入的 X-Request-ID，没有则生成 UUID；
//  2. 写回响应头，调用方可据此排查问题；
//  3. 构造带 request_id 字段的子日志实例并注入 context，
//     后续所有日志（访问日志、SQL 日志、业务日志）自动携带该字段。
func NewRequestID(log *zap.Logger) gin.HandlerFunc {
	return func(c *gin.Context) {
		// 步骤 1：上游（网关/前端）带了 ID 就沿用——跨服务串联靠它
		requestID := c.GetHeader(HeaderXRequestID)
		if requestID == "" {
			requestID = uuid.NewString()
		}
		// 步骤 2：写回响应头——客户端报障时报这串
		c.Header(HeaderXRequestID, requestID)

		// 步骤 3：造一个带 request_id 字段的子日志实例，注入 context。
		// 之后所有 FromContext 取日志的地方都自动带上这个字段
		ctx := logger.WithLogger(c.Request.Context(), log.With(zap.String("request_id", requestID)))
		c.Request = c.Request.WithContext(ctx)
		c.Next()
	}
}

// NewAccessLog 结构化访问日志中间件：每个请求结束时输出一行日志，
// 携带 request_id、方法、路径、状态码、耗时、客户端 IP 等字段。
func NewAccessLog(cfg AccessLogConfig) gin.HandlerFunc {
	...
	return func(c *gin.Context) {
		// 探针降噪：健康检查每秒都在打，全量记录会把日志刷爆
		if _, ok := skip[c.Request.URL.Path]; ok {
			c.Next()
			return
		}

		start := time.Now()
		c.Next() // 关键：先放行，让后面的中间件和 handler 执行

		log := logger.FromContext(c.Request.Context()) // 自动带 request_id
		fields := []zap.Field{
			zap.String("method", c.Request.Method),
			zap.String("path", c.Request.URL.Path),
			zap.String("query", sanitizeQuery(c.Request.URL.RawQuery)),
			// 路由模板（如 /users/:id）而非真实参数，便于聚合统计
			zap.String("handler", c.FullPath()),
			zap.Int("status", c.Writer.Status()),
			zap.Int64("latency_ms", time.Since(start).Milliseconds()),
			zap.String("client_ip", c.ClientIP()),
			zap.Int("body_size", c.Writer.Size()),
			zap.String("user_agent", c.Request.UserAgent()),
			zap.String("referer", c.Request.Referer()),
			zap.Bool("slow", latency >= slow),
		}

		switch {
		case status >= http.StatusInternalServerError:
			log.Error("access", fields...) // 5xx 记 error，告警直接按 level 捕获
		case status >= http.StatusBadRequest, isSlow:
			log.Warn("access", fields...) // 4xx 与慢请求记 warn
		default:
			log.Info("access", fields...)
		}
	}
}

// NewCORS 跨域中间件。允许的来源由配置注入，支持 "*" 与精确域名列表；
// 携带凭证时不允许回显 "*"，因此对具体域名原样回显并设置 Vary: Origin。
func NewCORS(allowOrigins []string) gin.HandlerFunc {
	allowAll := len(allowOrigins) == 1 && allowOrigins[0] == "*"
	originSet := make(map[string]struct{}, len(allowOrigins))
	for _, o := range allowOrigins {
		originSet[o] = struct{}{}
	}

	return func(c *gin.Context) {
		origin := c.GetHeader("Origin")
		if origin != "" {
			_, allowed := originSet[origin]
			if allowAll || allowed {
				// 回显具体 Origin 而不是 "*"：带 Cookie/Authorization 的
				// 跨域请求，浏览器不接受通配符
				c.Header("Access-Control-Allow-Origin", origin)
				c.Header("Vary", "Origin") // 告诉 CDN/缓存：不同 Origin 响应不同
				c.Header("Access-Control-Allow-Credentials", "true")
				c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
				c.Header("Access-Control-Allow-Headers", "Authorization, Content-Type, X-Request-ID")
				c.Header("Access-Control-Max-Age", "86400") // 预检结果缓存一天
			}
		}
		// 预检请求（OPTIONS）直接返回 204，不进入业务 handler
		if c.Request.Method == http.MethodOptions {
			c.AbortWithStatus(http.StatusNoContent)
			return
		}
		c.Next()
	}
}

// ipLimiter 按客户端 IP 维护独立的令牌桶。
// 说明：单机内存限流仅适用于单体服务；多实例部署时应在网关层
// 或使用 Redis + Lua 实现分布式限流。
type ipLimiter struct {
	mu       sync.Mutex
	visitors map[string]*visitor
	stop     chan struct{}
}

type visitor struct {
	limiter  *rate.Limiter
	lastSeen time.Time
}

// NewRateLimit 按 IP 限流中间件。rps <= 0 时视为关闭限流（直接放行）。
//
// 返回值第二个为销毁函数：关闭限流器内部的后台清理 goroutine。
// 忘记调用不影响请求处理，但 goroutine 与 visitor map 会一直
// 驻留到进程退出——测试中反复构建 router 时尤其明显。
func NewRateLimit(rps float64, burst int) (gin.HandlerFunc, func()) {
	if rps <= 0 {
		return func(c *gin.Context) { c.Next() }, func() {}
	}

	l := newIPLimiter()
	return func(c *gin.Context) {
		ip := c.ClientIP()
		if !l.allow(ip, rps, burst) {
			response.Fail(c, errcode.ErrTooManyRequests.Code(), errcode.ErrTooManyRequests.Msg())
			c.Abort()
			return
		}
		c.Next()
	}, l.Close // router 层把它编进应用关停链（见第九章）
}

// allow 判断该 IP 本次请求是否放行，并刷新其活跃时间。
func (l *ipLimiter) allow(ip string, rps float64, burst int) bool {
	l.mu.Lock()
	defer l.mu.Unlock()

	v, ok := l.visitors[ip]
	if !ok {
		v = &visitor{limiter: rate.NewLimiter(rate.Limit(rps), burst)}
		l.visitors[ip] = v
	}
	v.lastSeen = time.Now()
	return v.limiter.Allow()
}

// cleanupLoop 每 5 分钟清理一次空闲超过 5 分钟的 IP 记录。
func (l *ipLimiter) cleanupLoop() {
	ticker := time.NewTicker(5 * time.Minute)
	defer ticker.Stop()
	for {
		select {
		case <-ticker.C:
			l.cleanup()
		case <-l.stop:
			return // Close 后退出，goroutine 不再泄漏
		}
	}
}

// Close 停止后台清理 goroutine；sync.Once 保证幂等，
// 重复调用不会因 channel 重复关闭而 panic。
func (l *ipLimiter) Close() {
	l.stopOnce.Do(func() { close(l.stop) })
}

// BaseModel 所有模型的公共字段，软删除由 gorm.DeletedAt 实现。
type BaseModel struct {
	ID        uint64         `gorm:"primaryKey;autoIncrement" json:"id"`
	CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at"`
	UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at"`
	// 软删除：DELETE 实际是把 deleted_at 置为当前时间，
	// 查询自动过滤已删除记录。json:"-" 表示永不序列化给客户端
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

// User 用户表模型。
// json tag 主要服务于 Redis 缓存序列化；对外接口响应一律使用 handler 的 DTO，
// 模型永远不会被直接序列化给客户端。
type User struct {
	BaseModel
	Username string `gorm:"size:64;uniqueIndex;not null" json:"username"` // 唯一索引
	Password string `gorm:"size:100;not null" json:"-"`                    // bcrypt 哈希，绝不外泄
	Email    string `gorm:"size:128" json:"email"`
	Status   int8   `gorm:"not null;default:1" json:"status"` // 1 启用 / 2 禁用
}

// TableName 显式指定表名，避免复数形式推断带来的歧义。
func (User) TableName() string { return "users" }

// 用户状态常量，禁止在业务代码中出现魔法数字。
const (
	UserStatusEnabled  int8 = 1
	UserStatusDisabled int8 = 2
)

// LoginRequest 登录请求。
type LoginRequest struct {
	Username string `json:"username" binding:"required,min=3,max=64"`
	// Password bcrypt 有效输入上限为 72 字节
	Password string `json:"password" binding:"required,min=6,max=72"`
}

// CreateUserRequest 创建用户请求。
type CreateUserRequest struct {
	Username string `json:"username" binding:"required,min=3,max=64"`
	Password string `json:"password" binding:"required,min=6,max=72"`
	Email    string `json:"email" binding:"required,email,max=128"`
}

// UpdateUserRequest 更新用户请求（PUT 全量更新语义）。
type UpdateUserRequest struct {
	Email  string `json:"email" binding:"required,email,max=128"`
	Status int8   `json:"status" binding:"required,oneof=1 2"`
}

// ListUsersRequest 分页查询请求。
type ListUsersRequest struct {
	Page     int `form:"page" binding:"omitempty,min=1"`
	PageSize int `form:"page_size" binding:"omitempty,min=1,max=100"`
}

// UserResponse 用户信息响应——注意：根本没有 Password 字段。
type UserResponse struct {
	ID        uint64    `json:"id"`
	Username  string    `json:"username"`
	Email     string    `json:"email"`
	Status    int8      `json:"status"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

// 查不到、唯一索引冲突等数据层事实以本包哨兵错误的形式向上抛出，
// 由 Service 层翻译为业务错误码，保证 Service 不依赖 GORM。
var (
	ErrUserNotFound    = errors.New("user not found")
	ErrDuplicateUser   = errors.New("duplicate user")
)

const (
	userCacheKeyPrefix = "scaffold:user:"
	userCacheTTL       = 10 * time.Minute
	// 明确列出查询字段：避免 SELECT *，同时从结构上防止密码哈希外泄
	userSafeFields = "id, username, email, status, created_at, updated_at"
)

// UserRepo 用户数据访问接口。
type UserRepo interface {
	Create(ctx context.Context, user *model.User) error
	// GetByID 按主键查询（cache-aside：先查 Redis，未命中回源 MySQL 并回填）
	GetByID(ctx context.Context, id uint64) (*model.User, error)
	// GetByUsername 按用户名查询完整字段（登录校验需要密码哈希与状态）
	GetByUsername(ctx context.Context, username string) (*model.User, error)
	ListByPage(ctx context.Context, offset, limit int) ([]*model.User, int64, error)
	UpdateByID(ctx context.Context, id uint64, fields map[string]any) error
	DeleteByID(ctx context.Context, id uint64) error
}

// userRepo UserRepo 的 GORM + Redis 实现。
// 事务约定：所有 GORM 调用一律经由 data.DBFrom(ctx, r.db) 取连接。
type userRepo struct {
	db  *gorm.DB
	rdb redis.UniversalClient
}

// NewUserRepo 构造用户 repository，由 wire 注入 data.Data。
func NewUserRepo(data *data.Data) UserRepo {
	return &userRepo{db: data.DB(), rdb: data.RDB()}
}

// Create 写入新用户。
func (r *userRepo) Create(ctx context.Context, user *model.User) error {
	if err := data.DBFrom(ctx, r.db).WithContext(ctx).Create(user).Error; err != nil {
		if errors.Is(err, gorm.ErrDuplicatedKey) { // TranslateError 的功劳，见 4.2
			return ErrDuplicateUser
		}
		return err
	}
	return nil
}

// GetByID 按 ID 查询用户详情，标准的 cache-aside 缓存模式。
// 三个防护：空值占位防穿透、并发回源合并防击穿、缓存故障直接回源防雪崩放大。
func (r *userRepo) GetByID(ctx context.Context, id uint64) (*model.User, error) {
	key := userCacheKey(id)

	// 步骤 1：先查缓存；缓存挂了不阻断主流程，直接回源数据库
	if val, err := r.rdb.Get(ctx, key).Result(); err == nil {
		switch val {
		case userNegativePlaceholder: // 命中空值占位：此 ID 近期确认不存在
			return nil, ErrUserNotFound   // 不把这类请求打到 MySQL（防穿透）
		default:
			var user model.User
			if json.Unmarshal([]byte(val), &user) == nil {
				return &user, nil
			}
		}
	}

	// 步骤 2：缓存未命中，回源 MySQL；同一 key 的并发请求只放一个进来（防击穿）
	user, exists, err := r.loadWithSingleFlight(ctx, id)
	if err != nil {
		return nil, err
	}

	if !exists {
		// 步骤 3a：查不到也缓存——写一个短 TTL 的空值占位。
		// TTL 故意短（30s）：记录真正创建后很快就能被读到
		_ = r.rdb.Set(ctx, key, userNegativePlaceholder, userNegativeCacheTTL).Err()
		return nil, ErrUserNotFound
	}

	// 步骤 3b：回填完整缓存；回填失败不影响本次请求结果
	if payload, err := json.Marshal(user); err == nil {
		_ = r.rdb.Set(ctx, key, payload, userCacheTTL).Err()
	}
	return user, nil
}

// UpdateByID 更新指定用户的字段（key 为数据库列名）。
func (r *userRepo) UpdateByID(ctx context.Context, id uint64, fields map[string]any) error {
	res := data.DBFrom(ctx, r.db).WithContext(ctx).Model(&model.User{}).
		Where("id = ?", id).Updates(fields)
	if res.Error != nil {
		if errors.Is(res.Error, gorm.ErrDuplicatedKey) {
			return ErrDuplicateUser
		}
		return res.Error
	}
	if res.RowsAffected == 0 {
		// 值未变也会是 0，二次确认记录是否真的不存在
		var count int64
		if err := data.DBFrom(ctx, r.db).WithContext(ctx).Model(&model.User{}).
			Where("id = ?", id).Count(&count).Error; err != nil {
			return err
		}
		if count == 0 {
			return ErrUserNotFound
		}
	}
	// 写操作后删除缓存，下次读取时回源加载最新值
	_ = r.rdb.Del(ctx, userCacheKey(id)).Err()
	return nil
}

// UserService 用户业务接口。
type UserService interface {
	Login(ctx context.Context, username, password string) (*LoginResult, error)
	CreateUser(ctx context.Context, params *CreateUserParams) (uint64, error)
	GetUser(ctx context.Context, id uint64) (*UserInfo, error)
	ListUsers(ctx context.Context, page, pageSize int) ([]*UserInfo, int64, error)
	UpdateUser(ctx context.Context, id uint64, params *UpdateUserParams) error
	DeleteUser(ctx context.Context, id uint64) error
}

// userService UserService 实现。
type userService struct {
	repo repository.UserRepo
	// txm 事务管理器：跨 repository 的多步写操作必须经 InTransaction 编排
	txm  data.TxManager
	auth *jwt.Manager
	log  *zap.Logger
}

// NewUserService 构造用户 service，依赖均由 wire 注入。
func NewUserService(repo repository.UserRepo, txm data.TxManager, auth *jwt.Manager, log *zap.Logger) UserService {
	return &userService{repo: repo, txm: txm, auth: auth, log: log}
}

// Login 校验用户名密码并签发令牌。
//
// 安全约定：用户不存在与密码错误返回同一个错误码（ErrPasswordWrong），
// 不向调用方泄露账号是否存在，防止账号枚举探测。
func (s *userService) Login(ctx context.Context, username, password string) (*LoginResult, error) {
	user, err := s.repo.GetByUsername(ctx, username)
	if err != nil {
		if errors.Is(err, repository.ErrUserNotFound) {
			// 与存在用户的路径跑同样的 bcrypt 开销，保证恒时——
			// 否则响应耗时会泄露"用户名是否存在"（时序侧信道）
			_ = bcrypt.CompareHashAndPassword(dummyBcryptHash, []byte(password))
			return nil, errcode.ErrPasswordWrong // 用户不存在也报"密码错误"
		}
		return nil, s.internalError(ctx, "查询用户失败", err)
	}
	if user.Status == model.UserStatusDisabled {
		return nil, errcode.ErrUserDisabled
	}
	// bcrypt 比对：恒定时间比较，时序攻击也探不出密码对错
	if bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(password)) != nil {
		return nil, errcode.ErrPasswordWrong
	}

	token, err := s.auth.GenerateToken(user.ID, user.Username)
	if err != nil {
		s.log.Error("签发令牌失败", zap.Uint64("user_id", user.ID), zap.Error(err))
		return nil, errcode.ErrTokenGenerate
	}
	return &LoginResult{Token: token, ExpiresIn: int64(s.auth.Expire().Seconds())}, nil
}

// CreateUser 创建用户：密码 bcrypt 哈希后落库，禁止明文存储。
//
// 事务演示：单个 INSERT 本身不需要事务，这里用 InTransaction 包一层，
// 演示跨 repository 多步写入的标准编排方式——真实场景
// （如「创建用户 + 初始化账户 + 发放新人积分」）把多个 repo 调用
// 依次放进 fn 即可，任一失败整体回滚。
func (s *userService) CreateUser(ctx context.Context, params *CreateUserParams) (uint64, error) {
	// bcrypt 单向摘要 + 自带盐；DefaultCost=10，可按机器性能上调
	hashed, err := bcrypt.GenerateFromPassword([]byte(params.Password), bcrypt.DefaultCost)
	if err != nil {
		return 0, errcode.ErrServer
	}
	user := &model.User{
		Username: params.Username,
		Password: string(hashed),
		Email:    params.Email,
		Status:   model.UserStatusEnabled,
	}
	// fn 内的 repo 调用经由 data.DBFrom 取到事务连接，自动进入同一事务
	err = s.txm.InTransaction(ctx, func(ctx context.Context) error {
		return s.repo.Create(ctx, user)
	})
	if err != nil {
		if errors.Is(err, repository.ErrDuplicateUser) {
			return 0, errcode.ErrUserDuplicate // 哨兵错误 -> 业务错误码
		}
		return 0, s.internalError(ctx, "创建用户失败", err)
	}
	return user.ID, nil
}

// internalError 统一处理未预期的内部错误：
// 完整细节写入带 request_id 的链路日志，对外只暴露通用错误码。
func (s *userService) internalError(ctx context.Context, msg string, err error) error {
	logger.FromContextOrDefault(ctx, s.log).Error(msg, zap.Error(err))
	return errcode.ErrServer
}

// UserHandler 用户模块 HTTP 接口。
type UserHandler struct {
	svc service.UserService // 依赖接口，不是具体实现
}

// NewUserHandler 构造 UserHandler，依赖 service 接口（面向接口编程）。
func NewUserHandler(svc service.UserService) *UserHandler {
	return &UserHandler{svc: svc}
}

// Create 创建用户
//
//	@Summary      创建用户
//	@Description  创建新用户，密码在服务端 bcrypt 哈希后落库
//	@Tags         users
//	@Accept       json
//	@Produce      json
//	@Security     BearerAuth
//	@Param        request body dto.CreateUserRequest true "创建用户请求"
//	@Success      200 {object} response.Body{data=dto.CreateUserResponse}
//	@Router       /users [post]
func (h *UserHandler) Create(c *gin.Context) {
	var req dto.CreateUserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		// 校验失败：把 validator 的英文错误翻译成用户友好文案
		response.Fail(c, errcode.ErrInvalidParams.Code(), translateBindingError(err))
		return
	}

	id, err := h.svc.CreateUser(c.Request.Context(), &service.CreateUserParams{
		Username: req.Username,
		Password: req.Password,
		Email:    req.Email,
	})
	if err != nil {
		response.Error(c, err) // service 保证只回 *ErrCode，直接渲染
		return
	}
	response.OK(c, dto.CreateUserResponse{ID: id})
}

// Get 用户详情
//
//	@Summary      查询用户详情
//	@Description  按用户 ID 查询详情（服务端 cache-aside 缓存）
//	@Tags         users
//	@Security     BearerAuth
//	@Param        id path int true "用户 ID" minimum(1)
//	@Success      200 {object} response.Body{data=dto.UserResponse}
//	@Router       /users/{id} [get]
func (h *UserHandler) Get(c *gin.Context) {
	id, ok := parseUintParam(c, "id")
	if !ok {
		return
	}

	info, err := h.svc.GetUser(c.Request.Context(), id)
	if err != nil {
		response.Error(c, err)
		return
	}
	response.OK(c, toUserResponse(info))
}

// translateBindingError 把 validator 的错误翻译成对用户友好的提示，
// 例如 "username 长度或取值过小"。
func translateBindingError(err error) string {
	var valErrs validator.ValidationErrors
	if !errors.As(err, &valErrs) || len(valErrs) == 0 {
		return errcode.ErrInvalidParams.Msg()
	}

	fe := valErrs[0] // 只报第一个错误，一次改一个，体验更好
	var reason string
	switch fe.Tag() {
	case "required":
		reason = "不能为空"
	case "min":
		reason = "长度或取值过小"
	case "max":
		reason = "长度或取值过大"
	case "email":
		reason = "格式必须为合法邮箱"
	case "oneof":
		reason = "取值必须为 " + fe.Param()
	default:
		reason = "不符合规则（" + fe.Tag() + "）"
	}
	return strings.ToLower(fe.Field()) + " " + reason
}

// toUserResponse service 出参转接口 DTO，保持两层结构解耦。
func toUserResponse(info *service.UserInfo) *dto.UserResponse {
	return &dto.UserResponse{
		ID:        info.ID,
		Username:  info.Username,
		Email:     info.Email,
		Status:    info.Status,
		CreatedAt: info.CreatedAt,
		UpdatedAt: info.UpdatedAt,
	}
}

// 反面教材：手工装配。组件少时还行，多了以后——
// 顺序错了编译不报错（运行才炸），加组件要人肉找插入点，
// 关闭顺序要自己维护一份和初始化完全相反的清单
log, cleanupLog, _ := logger.New(...)
d, cleanupData, _ := data.New(cfg, log)
auth := jwt.NewManager(...)
repo := repository.NewUserRepo(d)
svc := service.NewUserService(repo, d, auth, log)
h := handler.NewUserHandler(svc)
r := router.New(cfg, log, d, auth, h)
srv := server.New(cfg, r, log)

//go:build wireinject
// +build wireinject

package main

// wireApp 依赖注入入口：wire 在编译期生成 wire_gen.go 中的真实实现。
// 依赖链：Config -> Logger/JWT -> Data -> UserRepo -> UserService
//         -> UserHandler -> Router(Engine) -> Server
func wireApp(cfg *config.Config) (*server.Server, func(), error) {
	panic(wire.Build(
		newLogger,              // providers.go 里：config -> zap.Logger
		newJWTManager,          // providers.go 里：config -> jwt.Manager
		data.New,               // config + logger -> Data（带 cleanup）
		repository.NewUserRepo, // Data -> UserRepo
		service.NewUserService, // repo + TxManager + jwt + logger -> UserService
		handler.NewUserHandler, // UserService -> UserHandler
		router.New,             // 一切 -> gin.Engine
		server.New,             // engine + config + logger -> Server
		// 两个"类型绑定"：告诉 wire 具体类型满足哪个接口
		wire.Bind(new(http.Handler), new(*gin.Engine)),  // gin.Engine 当 http.Handler 用
		wire.Bind(new(data.TxManager), new(*data.Data)), // Data 当 TxManager 用
	))
}

// newLogger 把应用配置转换为 pkg/logger 的独立配置并构建日志实例。
// pkg 包不反向依赖 internal/config，保持基础库的可复用性。
func newLogger(cfg *config.Config) (*zap.Logger, func(), error) {
	return logger.New(logger.Config{
		Level:      cfg.Log.Level,
		Dir:        cfg.Log.Dir,
		Filename:   cfg.Log.Filename,
		MaxSizeMB:  cfg.Log.MaxSize,
		MaxBackups: cfg.Log.MaxBackups,
		MaxAgeDays: cfg.Log.MaxAge,
		Compress:   cfg.Log.Compress,
	})
}

// newJWTManager 从配置构建 JWT 管理器。
func newJWTManager(cfg *config.Config) *jwt.Manager {
	return jwt.NewManager(cfg.JWT.Secret, cfg.JWT.Issuer, cfg.JWT.Expire)
}

// Code generated by Wire. DO NOT EDIT.

//go:build !wireinject

package main

func wireApp(cfg *config.Config) (*server.Server, func(), error) {
	logger, cleanup, err := newLogger(cfg)
	if err != nil {
		return nil, nil, err
	}
	dataData, cleanup2, err := data.New(cfg, logger)
	if err != nil {
		cleanup() // 失败回滚：data 起不来，把已启动的 logger 清掉
		return nil, nil, err
	}
	manager, err := newJWTManager(cfg)
	if err != nil {
		cleanup2() // jwt 构造失败（如密钥过短）也要逆序回滚前两个
		cleanup()
		return nil, nil, err
	}
	userRepo := repository.NewUserRepo(dataData)
	userService := service.NewUserService(userRepo, dataData, manager, logger)
	userHandler := handler.NewUserHandler(userService)
	engine, cleanup3 := router.New(cfg, logger, dataData, manager, userHandler)
	serverServer := server.New(cfg, engine, logger)
	return serverServer, func() {
		cleanup3() // 先关 router 层后台资源（限流清理 goroutine）
		cleanup2() // 再关数据层（MySQL + Redis）
		cleanup()  // 最后刷日志——日志必须活到最后一刻
	}, nil
}

// New 构建 gin 引擎并完成全部路由注册。依赖均由 wire 注入。
// 返回的销毁函数用于释放中间件持有的后台资源（如限流器的清理 goroutine）。
func New(cfg *config.Config, log *zap.Logger, data *data.Data, auth *jwt.Manager,
	userHandler *handler.UserHandler) (*gin.Engine, func()) {

	// 接管 gin 自身输出（[GIN-debug] 路由表、[WARNING] 等）统一交给 zap，
	// 必须在 gin.New() 之前调用，否则抓不到启动期的路由表打印
	logger.RedirectGinLog(log)

	// 生产默认 ReleaseMode；显式设置 GIN_MODE 时尊重环境变量
	if os.Getenv("GIN_MODE") == "" {
		gin.SetMode(gin.ReleaseMode)
	}

	r := gin.New() // 注意是 New 不是 Default：Default 自带 gin.Logger/Recovery，我们用自己的

	// 可信代理：gin 默认信任所有代理头，X-Forwarded-For 可被客户端伪造，
	// 导致按 IP 的限流被轻易绕过。空列表表示不信任任何代理，
	// ClientIP 回退为 TCP 直连地址。CIDR 合法性已在配置加载时校验（见 2.4）。
	if err := r.SetTrustedProxies(cfg.HTTP.TrustedProxies); err != nil {
		panic(fmt.Sprintf("设置可信代理失败: %v", err)) // 理论上不可达
	}

	// 中间件顺序即第六章讲的那条流水线
	rateLimit, closeRateLimit := middleware.NewRateLimit(cfg.RateLimit.RPS, cfg.RateLimit.Burst)
	r.Use(
		middleware.NewRecovery(log),
		middleware.NewRequestID(log),
		middleware.NewAccessLog(middleware.AccessLogConfig{
			SlowThreshold: cfg.Log.SlowThreshold,
			SkipPaths:     cfg.Log.SkipPaths,
		}),
		middleware.NewCORS(cfg.CORS.AllowOrigins),
		rateLimit,
	)

	registerHealth(r, data)
	registerAPIs(r, auth, userHandler)

	// Swagger 文档：/swagger/index.html，建议生产环境按需关闭
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	return r, closeRateLimit
}

// registerHealth 注册健康检查探针：
// /healthz 存活探针（进程活着即返回成功），
// /readyz 就绪探针（依赖的 MySQL / Redis 均可用才返回成功）。
func registerHealth(r *gin.Engine, data *data.Data) {
	r.GET("/healthz", func(c *gin.Context) {
		response.OK(c, gin.H{"status": "ok"})
	})
	r.GET("/readyz", func(c *gin.Context) {
		if err := data.Ping(c.Request.Context()); err != nil {
			// 就绪探针失败必须返回非 2xx：K8s 等编排系统只认 HTTP 状态码，
			// 若沿用统一响应格式（200 + 业务码），依赖挂掉时探针仍判定 ready，
			// 滚动发布会把流量打向坏实例
			c.JSON(http.StatusServiceUnavailable, response.Body{
				Code: errcode.ErrServer.Code(),
				Msg:  "依赖不可用",
			})
			return
		}
		response.OK(c, gin.H{"status": "ready"})
	})
}

// Claims 自定义载荷，业务侧只透出必要的身份字段。
type Claims struct {
	UserID   uint64 `json:"user_id"`
	Username string `json:"username"`
	jwt.RegisteredClaims
}

// Manager 令牌管理器，由依赖注入构造，全应用共享一个实例。
type Manager struct {
	secret []byte
	issuer string
	expire time.Duration
}

// NewManager 构造 Manager。secret 长度不少于 32 字节（生产环境要求），
// 不满足时返回 ErrSecretTooShort，由配置校验层在启动期拦截——
// 弱密钥是"带病上线"，宁可启动失败也不能靠注释约束。
func NewManager(secret, issuer string, expire time.Duration) (*Manager, error) {
	if len(secret) < 32 {
		return nil, ErrSecretTooShort
	}
	return &Manager{secret: []byte(secret), issuer: issuer, expire: expire}, nil
}

// GenerateToken 为指定用户签发 access token。
func (m *Manager) GenerateToken(userID uint64, username string) (string, error) {
	now := time.Now()
	claims := Claims{
		UserID:   userID,
		Username: username,
		RegisteredClaims: jwt.RegisteredClaims{
			Issuer:    m.issuer,
			Subject:   username,
			IssuedAt:  jwt.NewNumericDate(now),
			ExpiresAt: jwt.NewNumericDate(now.Add(m.expire)),
		},
	}
	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(m.secret)
}

// ParseToken 校验并解析令牌，返回业务载荷。
func (m *Manager) ParseToken(tokenString string) (*Claims, error) {
	claims := &Claims{}
	token, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (any, error) {
		// 锁死签名算法，防止算法替换攻击（如把 HS256 的 token 当 RS256 验证）
		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, ErrTokenInvalid
		}
		return m.secret, nil
	})
	if err != nil {
		if errors.Is(err, jwt.ErrTokenExpired) {
			return nil, ErrTokenExpired
		}
		return nil, ErrTokenInvalid
	}
	if !token.Valid {
		return nil, ErrTokenInvalid
	}
	return claims, nil
}

// NewAuth JWT 鉴权中间件：校验 Authorization: Bearer <token>，
// 解析通过后把用户身份写入 gin.Context，供 handler 取用。
func NewAuth(mgr *jwt.Manager) gin.HandlerFunc {
	return func(c *gin.Context) {
		authHeader := c.GetHeader("Authorization")
		if !strings.HasPrefix(authHeader, "Bearer ") {
			response.Fail(c, errcode.ErrUnauthorized.Code(), errcode.ErrUnauthorized.Msg())
			c.Abort() // 关键：不放行，后面的 handler 不会执行
			return
		}

		claims, err := mgr.ParseToken(strings.TrimPrefix(authHeader, "Bearer "))
		if err != nil {
			// 令牌过期与非法统一返回未授权，不向调用方暴露具体校验细节
			response.Fail(c, errcode.ErrUnauthorized.Code(), errcode.ErrUnauthorized.Msg())
			c.Abort()
			return
		}

		c.Set("context_user_id", claims.UserID)   // 身份落进 gin.Context
		c.Set("context_username", claims.Username)
		c.Next()
	}
}

func registerAPIs(r *gin.Engine, auth *jwt.Manager, userHandler *handler.UserHandler) {
	apiV1 := r.Group("/api/v1")

	// 公开路由：登录（不登录怎么拿令牌呢）
	authGroup := apiV1.Group("/auth")
	{
		authGroup.POST("/login", userHandler.Login)
	}

	// 受保护路由：用户 CRUD，整组挂载 JWT 鉴权
	users := apiV1.Group("/users")
	users.Use(middleware.NewAuth(auth))
	{
		users.POST("", userHandler.Create)
		users.GET("", userHandler.List)
		users.GET("/:id", userHandler.Get)
		users.PUT("/:id", userHandler.Update)
		users.DELETE("/:id", userHandler.Delete)
	}
}

make swagger   # 等价于 go tool swag init -g cmd/server/main.go -o api/swagger

// Server 业务 HTTP 服务器。
type Server struct {
	httpSrv  *http.Server
	debugSrv *http.Server // pprof 调试服务，可选
	log      *zap.Logger
}

// New 构建服务器。所有超时参数显式来自配置，杜绝慢连接资源耗尽。
func New(cfg *config.Config, engine http.Handler, log *zap.Logger) *Server {
	s := &Server{
		log: log,
		httpSrv: &http.Server{
			Addr:              cfg.HTTP.Addr,
			Handler:           engine,
			ReadHeaderTimeout: cfg.HTTP.ReadHeaderTimeout, // 只读 header 的上限，最先生效
			ReadTimeout:       cfg.HTTP.ReadTimeout,       // 读完整请求（含 body）的上限
			WriteTimeout:      cfg.HTTP.WriteTimeout,      // 写响应上限
			IdleTimeout:       cfg.HTTP.IdleTimeout,       // Keep-Alive 空闲连接上限
		},
	}
	// pprof 独立端口且只监听回环地址，避免在生产环境对外暴露
	if cfg.App.DebugPort > 0 {
		s.debugSrv = &http.Server{
			Addr:    fmt.Sprintf("127.0.0.1:%d", cfg.App.DebugPort),
			Handler: http.DefaultServeMux,
		}
	}
	return s
}