gin的调试模式需显式调用gin.setmode(gin.debugmode)而非依赖环境变量，因环境变量仅初始化时读取；结构体json序列化要求字段首字母大写并加json tag；调试接口需手动打印请求详情、校验路由顺序与反向代理配置。
为什么 Gin 的 gin.DebugMode 不能靠环境变量自动开启？
Gin 默认在 DEBUG 环境变量为 true、1 或 on 时启用调试模式，但这个行为只在 gin.Default() 或 gin.New() 初始化时读取一次——如果后续代码里改了 os.Setenv("GIN_MODE", "debug")，Gin 不会重新加载。更关键的是，Docker 容器或某些 CI 环境里，环境变量可能被覆盖或延迟生效，导致你以为开了调试却没日志。
实操建议：
- 显式调用
gin.SetMode(gin.DebugMode)，比依赖环境变量更可靠 - 在
main()最开头就设置，避免中间件或路由注册后才生效 - 调试阶段可加一行校验：
log.Printf("Gin mode: %s", gin.Mode())
如何让接口返回带结构体字段名的 JSON 而不是空对象？
常见错误是定义结构体时字段全小写或没加 JSON tag，比如 type User { name string }，调用 c.JSON(200, user) 返回 {}——因为 Go 的 JSON 包默认只序列化首字母大写的导出字段，且不加 json: tag 时用字段名原样输出（但小写字段不可导出）。
实操建议：
- 结构体字段必须首字母大写，例如
Name string，而非name string - 加上明确的
jsontag，控制键名和空值行为：Name string `json:"name"` - 需要忽略零值字段时用
omitempty：Age int `json:"age,omitempty"` - 调试时用
c.IndentedJSON(200, data)替代c.JSON，输出格式化 JSON，肉眼排查字段是否真的为空更方便
如何快速验证一个接口是否收到请求、参数是否解析正确？
光看终端日志不够：Gin 默认日志不打印请求体（body）、查询参数（query）和表单数据（form），而 c.Request.URL.Query() 或 c.ShouldBind() 出错时也容易静默失败。
实操建议：
- 在 handler 开头加临时调试日志：
log.Printf("Query: %+v, Body: %s", c.Request.URL.Query(), httputil.DumpRequest(c.Request, false))（需导入net/http/httputil） - 对 JSON 请求，优先用
c.ShouldBindJSON(&v)而非c.BindJSON，前者出错只记录日志不中断流程，方便观察错误原因 - 测试时用
curl -v查看完整请求头和响应状态，避免 Postman 隐藏重定向或自动加 header 带来干扰 - 若参数总为空，检查前端是否漏传
Content-Type: application/json，或后端是否误用了c.ShouldBindQuery解析 body
为什么本地调试正常，部署到服务器后接口 404 或 panic？
典型原因是路由注册顺序或路径匹配逻辑差异：Gin 的 router.GET("/user/:id", ...) 和 router.GET("/user/new", ...) 会因顺序不同导致 /user/new 被 /user/:id 拦截（new 被当成 :id 值）；另外，Nginx 反向代理时若没配置 proxy_pass 末尾斜杠，可能导致路径被拼接错位。
实操建议：
- 把静态路径（如
/health、/user/new）写在动态路径（如/user/:id）之前 - 启动时打印所有注册路由：
router.Routes()返回[]gin.RouteInfo，遍历输出方法和路径 - 服务器部署前，在 main 函数末尾加
log.Println("Routes registered:", len(router.Routes())) - 确认反向代理配置中
proxy_pass http://127.0.0.1:8080/;末尾有斜杠，否则/api/user可能被转发成http://127.0.0.1:8080/api/user，而你的路由是/user
router.Use(gin.Recovery()) 是基础，但真正要定位问题，得在关键 handler 里手动打点、检查 c.Errors、并确保日志不被缓冲。
