能跑起来的最小可行代码5行搞定，但上线前必须补3个关键配置：禁用gin.Default()默认中间件、区分路径与查询参数、修正struct tag大小写、注册缺失MIME类型，否则本地正常线上崩溃。
能跑起来的最小可行代码，5行就搞定；但真正上线前，至少要补3个关键配置，否则本地能通、线上崩。
gin.Default() 为什么不能直接上生产
它默认启用了 gin.Logger() 和 gin.Recovery() 中间件，开发时方便看日志、防 panic 崩服务，但 gin.Logger() 会把所有请求原样打到 stdout，线上日志系统通常不认这种格式，还会暴露敏感路径；gin.Recovery() 虽然捕获 panic，但返回的是 HTML 错误页（含堆栈），API 场景下前端根本没法解析。
- 生产环境应显式构造引擎：
r := gin.New()，再按需注册中间件 - 日志建议用
gin.LoggerWithWriter()接入文件或 logrus/zap - 错误恢复应自定义 handler，统一返回 JSON 格式错误，比如
c.JSON(500, gin.H{"error": "internal server error"})
路由参数和查询参数别混用
写 r.GET("/user/:id", ...) 时，:id 是路径参数，必须存在且不可选；而 c.Query("page") 拿的是 URL 查询字符串里的值，天然可空。很多人把分页参数硬塞进路径，比如 /list?page=1&size=20 写成 /list/:page/:size，结果一漏传就 404，而不是返回默认分页值。
- 路径参数用于资源标识（如
/users/123），语义强、必须存在 - 查询参数用于筛选/分页/排序（如
?sort=name&limit=10），语义弱、应有默认值 - 获取时别用
c.Param()硬取查询参数，会返回空字符串，也不报错
JSON 绑定时 struct tag 写错就静默失败
用 c.ShouldBindJSON(&u) 解析请求体时，如果 struct 字段没加 json tag，或者 tag 名和前端字段名不一致，Gin 不会报错，只是跳过赋值——u.Name 保持零值，你却以为前端没传，实际是绑定失败了。
立即学习“go语言免费学习笔记（深入）”；
- 必须写全小写 tag：
type User struct { Name string `json:"name"` }，大写"Name"或漏掉都不行 - 可选字段加
omitempty：Age int `json:"age,omitempty"`，避免零值覆盖 - 调试时先打印原始 body：
body, _ := io.ReadAll(c.Request.Body)，确认数据确实发过来了
静态文件服务容易忽略 MIME 类型
用 r.Static("/static", "./assets") 托管前端资源时，Gin 默认只认常见后缀（.js、.css、.png 等），遇到 .webp、.woff2、.mjs 就返回 text/plain，浏览器直接拒载。
- 手动注册 MIME 类型：
mime.AddType(".webp", "image/webp")，放在main()开头 - 更稳妥的方式是用
r.StaticFS()配合自定义http.FileSystem，控制 Content-Type - 注意路径别写错：
./assets是相对 main.go 的路径，不是 go.mod 所在目录
真正卡住人的从来不是语法，而是那些不报错、不提示、但请求就是不对的细节——比如 struct tag 大小写、MIME 类型缺失、路径参数强依赖。上线前扫一遍这四类点，比反复改接口逻辑省力得多。
