生产环境应使用 gin.New() 手动注册中间件，避免 gin.Default() 的 gin.Logger() 造成 I/O 瓶颈导致 QPS 下降 15%~20%；需严格控制中间件挂载层级、Context 复用安全及 JSON 绑定方法选择。
gin.Default() 和 gin.New() 的选择直接影响性能与可观测性
默认用 gin.Default() 会自动加载 gin.Logger() 和 gin.Recovery()，适合开发阶段快速验证；但生产环境必须换用 gin.New() 手动控制中间件——因为 gin.Logger() 在高并发下会成为 I/O 瓶颈，实测 QPS 下降 15%~20%。
- 生产推荐写法：
Router := gin.New()，再按需注册gin.Recovery()（必须）和自定义日志中间件（如写入本地文件或发到 Loki） - 调试时可临时加
gin.LoggerWithWriter(os.Stdout)，避免干扰标准输出流 - 若启用了 Prometheus 指标采集，
gin.Recovery()必须放在指标中间件之后，否则 panic 会导致 counter 计数异常
路由分组 + 前缀路径要和中间件绑定顺序严格匹配
常见错误是把认证中间件挂错层级，导致部分接口未鉴权或重复校验。Gin 的中间件执行顺序由注册位置决定，不是按 Use() 调用先后——它只对当前 Group() 及其子分组生效。
- 正确做法：在最外层
r.Group("/api")绑定统一鉴权中间件，内部子分组如/v1/users不再重复加 - 错误示例：
v1 := r.Group("/api/v1"); v1.Use(AuthMw); users := v1.Group("/users"); users.Use(AuthMw)→ 导致两次解析 token - 动态前缀注意：如果用
r.Group("/svc/:service_name")，中间件里取c.Param("service_name")是安全的，但别在中间件里做耗时路由转发逻辑，会拖慢整个树匹配
Context 复用机制要求避免 goroutine 中直接传入 c
gin.Context 本身不是线程安全的，底层复用来自 sync.Pool，一旦被子 goroutine 持有并异步调用 c.JSON() 或 c.Abort()，极大概率触发 panic 或响应写入混乱。
- 必须拷贝：启动 goroutine 前调用
ctx := c.Copy()，再传入新协程 - 禁止操作：
go func() { c.JSON(200, data) }()—— 这类写法在压测中 100% 出现http: response.WriteHeader on hijacked connection - 替代方案：用
c.Request.Context().Done()监听取消信号，配合select控制超时，比手动起 goroutine 更可靠
JSON 绑定性能陷阱：ShouldBind vs ShouldBindJSON 的实际差异
多数人以为 c.ShouldBind() 是通用接口，其实它会根据 Content-Type 自动选解析器，而 c.ShouldBindJSON() 强制走 JSON 解析路径——前者多一层类型判断开销，在 10K+ RPS 场景下可观测到 3%~5% CPU 升高。
立即学习“go语言免费学习笔记（深入）”；
- 明确知道是 JSON 请求时，一律用
c.ShouldBindJSON(&req) - 结构体 tag 中避免冗余校验：比如
binding:"required"已足够，不必再加validate:"required"（validator 库重复跑） - 大请求体（>1MB）建议先用
c.Request.Body流式读取并限流，而不是全量加载进内存再 bind，否则容易 OOM
