gin服务启动后返回404是因为未显式注册路由，gin.default()仅创建带中间件的空引擎，必须调用r.get()等方法注册路由且需r.run()启动监听。
直接上手 Gin 不用绕弯子：只要 Go ≥ 1.16、go mod init 初始化过、显式注册了路由，r.Run() 启动后就能访问——其他全是细节优化或排障点。
go mod 和 gin import 报错 undefined: gin
这不是 Gin 问题，是模块没生效。常见现象：go run main.go 报 undefined: gin，或 go get -u github.com/gin-gonic/gin 后 import "github.com/gin-gonic/gin" 仍标红。
- 执行
go version确认输出中包含go1.16或更高版本；低于此版本默认关闭 module 模式，go get会写入$GOROOT/src而非go.mod - 项目根目录下必须先运行
go mod init your-module-name（名称可任意，但不能含空格或大写字母） - 国内环境务必设置代理：
go env -w GOPROXY=https://goproxy.cn,direct，否则go get可能卡住或失败 - 删掉手动建的
vendor/或go.sum——Gin 依赖极少，go mod tidy自动收敛即可
启动后访问 localhost:8080 返回 404
Gin 不自动注册任何路由。gin.Default() 只返回一个带 Logger 和 Recovery 的空引擎，没加 r.GET() 就等于没写服务逻辑。
- 必须显式调用路由注册方法，例如：
r.GET("/ping", func(c *gin.Context) { c.String(200, "ok") }) - 路径严格匹配：
r.GET("/v1/user", ...)不会响应/v1/user/（末尾斜杠不自动补全），也不响应/v1/user?id=1（查询参数不影响路径匹配） - 静态文件需确保目录真实存在：
r.StaticFS("/static", http.Dir("./assets"))中的./assets必须是当前工作目录下的有效路径，否则请求 404 且启动时不报错
c.Param() / c.Query() / c.PostForm() 拿不到值
这三个方法来源完全不同，混用必空。Gin 不做类型校验，运行时才发现取不到。
-
c.Param("id")只取路径参数，如/user/:id对应 URL/user/123→ 得到"123"；若 URL 是/user?id=123，这里永远为空 -
c.Query("page")取 URL 查询参数，/list?page=2&size=10→"2"；重复 key 如?a=1&a=2只返回第一个值，要全量用c.Request.URL.Query()["a"] -
c.PostForm("name")仅适用于application/x-www-form-urlencoded表单；JSON 请求体必须用c.ShouldBindJSON(&struct{})，否则始终为空字符串
r.Run() 在生产环境裸跑的风险
r.Run() 看似方便，实则绕过关键控制点：无法设超时、无法优雅关闭、无法绑定 TLS 或 Unix socket。
- 默认监听
0.0.0.0:8080，Docker 容器里可能意外暴露给外网；生产建议显式指定r.Run(":8080")或绑定内网地址 - 要加读写超时，必须自己构造
*http.Server：srv := &http.Server{Addr: ":8080", Handler: r, ReadTimeout: 5 * time.Second} - 进程退出前必须调
srv.Shutdown()，否则正在处理的请求会被粗暴中断；Gin 自己不管理这个生命周期 -
r.RunTLS()需提前提供证书路径，且不支持 Let's Encrypt 自动续签
最常被忽略的是：路由注册和参数来源的严格对应关系。写错一个 c.Query 当成 c.Param，前端传参完全正确，后端就是空——这种问题不会报错，只能靠日志或调试器逐行确认数据来源。
