结论是：Gin从零到上线核心在于守住三件事——规范go mod依赖管理、正确选用gin.Default()或gin.New()、提前规划路由分组与中间件绑定结构；其余皆可按需填空。
直接上结论：Gin 从零到上线，核心不是学完所有 API，而是守住三件事——go mod 管理依赖不乱、gin.Default() 和 gin.New() 别混用、路由分组 + 中间件绑定必须提前规划好结构。其余都是填空。
go mod 初始化和依赖锁定怎么写才不出错
很多人在 go get github.com/gin-gonic/gin 后发现本地跑通了，一上生产就 panic，八成是依赖没锁死。
-
go mod init your-app-name必须在空目录下执行，且模块名不能含中文或空格 - 别用
go get -u，它会自动升版，而v1.9.1和v1.10.0在中间件行为上有差异（比如Recovery()默认是否捕获http.ErrAbortHandler） - 上线前务必检查
go.mod中的版本号，手动改成带具体小版本的写法：github.com/gin-gonic/gin v1.9.1 - 如果公司私有代理不稳定，加一行
replace github.com/gin-gonic/gin => ./vendor/gin临时兜底，但仅限调试，不可提交
gin.Default() 和 gin.New() 什么时候该选哪个
gin.Default() 自带 Logger() 和 Recovery()，开发阶段省事；gin.New() 是白板，生产环境更可控——但很多人误以为“默认=安全”，结果线上日志打满磁盘或 panic 没被捕获。
- 本地开发、CI 构建阶段，用
gin.Default()即可，但要加gin.SetMode(gin.ReleaseMode)关掉 debug 提示 - 生产部署时，如果已有统一日志系统（如 Loki + Promtail），建议用
gin.New()，自己注册轻量级中间件：r.Use(customLogger(), customRecovery()) -
Recovery()默认会打印堆栈到标准输出，K8s 环境下可能触发 liveness probe 失败，必须重写其 handler 或禁用
路由分组和中间件绑定的实际坑点
看似只是语法糖，但分组层级错了，中间件作用域就全偏了。常见错误是把鉴权中间件挂到 r.Group("/api")，结果 /healthz 也被拦住。
- 健康检查、指标接口（如
/metrics、/healthz）一定放在根路由或独立 group，不套任何中间件 - API 版本控制必须体现在 group 路径里：
apiV1 := r.Group("/api/v1")，别用 query 参数或 header 做版本路由 - 中间件注册顺序 = 执行顺序：
apiV1.Use(authMw, logMw)表示先鉴权、再记日志；反过来可能导致未鉴权请求也进日志 - 路径参数绑定时，
GET "/user/:id"的:id无法被c.ShouldBindQuery(&v)解析，得用c.Param("id")单独取
上线前必须验证的三个冷门但致命细节
多数人只测接口通不通，但真正卡上线的是这些不起眼的配置。
-
r.Run(":8080")在容器里会绑定到0.0.0.0:8080，但若 K8s Service 指向的是80端口，得显式写成r.Run("0.0.0.0:80")或通过环境变量注入端口 - Gin 默认信任所有代理（
TrustedProxies为空），Nginx 或 ALB 转发后c.ClientIP()会返回内网地址，必须调用r.SetTrustedProxies([]string{"10.0.0.0/8"}) - 静态文件服务（如
r.Static("/static", "./assets")）路径必须是相对 binary 所在目录的路径，Docker 镜像里常因 WORKDIR 不一致导致 404
