Go版本≥1.16且GOPROXY必须配对，否则go get会写入src而非go.mod导致undefined错误；需先go mod init再写代码，gin.Default()不自动注册路由，404多因漏写r.GET等注册语句。
开发环境必须配对 Go 版本和 GOPROXY
Go 1.16 是硬门槛，低于这个版本 go mod 默认关闭，go get github.com/gin-gonic/gin 会写进 $GOROOT/src 而非项目 go.mod，导致 import "github.com/gin-gonic/gin" 报 undefined。运行 go version 确认输出类似 go version go1.21.0 darwin/arm64；国内务必设代理，否则 go get 极易卡死或超时：
go env -w GOPROXY=https://goproxy.cn,direct- 别用
proxy.golang.org（国内不稳定） - 不建议手动创建
vendor/或删go.sum——Gin 依赖极轻，go mod tidy就够
初始化项目不能跳过 go mod init
新建目录后直接 go mod init your-module-name，不是 go init，也不是空着不管。这一步生成 go.mod，后续所有 go get 才会正确记录依赖。常见错误是先写 main.go 再补 go mod init，结果 gin 包没进依赖树，go run main.go 仍报未定义。
- 模块名建议用实际路径或仓库地址，比如
github.com/yourname/myapi - 如果只是本地练习，用
myapp也行，但别留空或用中文 - 执行完检查
go.mod是否含require github.com/gin-gonic/gin v1.9.0类似行
启动后 404 不是 Gin 问题，是路由没注册
gin.Default() 只返回一个带 Logger 和 Recovery 的空引擎，它不自动挂任何路由。你看到服务起来、访问 localhost:8080 却返回 404，99% 是因为漏写了 r.GET(...) 这类注册语句。
- 必须显式调用
r.GET("/ping", func(c *gin.Context) { c.JSON(200, gin.H{"message": "pong"}) }) - 路径严格匹配：
/v1/user不响应/v1/user/（末尾斜杠不自动补全） - 静态资源如
r.StaticFS("/static", http.Dir("./assets"))，要确保./assets目录真实存在，否则请求照样 404，且启动时不报错
开发阶段用 YAML 配置，但别在 init() 里加载
开发时用 config.dev.yaml 最方便，有缩进、能加注释。但加载逻辑必须放在 main() 函数里，不能塞进 init()。否则单元测试时无法 mock ENV 变量，一跑测试就 panic。
- 读取方式：用
os.Getenv("ENV")拿环境名，再传给viper.SetConfigName("config." + env) - 禁用
viper.AutomaticEnv()开发阶段——它会把所有环境变量都映射成配置项，干扰调试 - YAML 文件放项目根目录，
viper.AddConfigPath(".")即可，不用写死绝对路径 - 启动前加校验：
if !viper.IsSet("server.addr") { log.Fatal("missing server.addr") }，别只靠GetString返回空字符串来判断
