Go 1.16+是硬性前提，因http.ServeMux路径匹配逻辑和Go Modules默认启用状态依赖此版本；需确认go version输出≥1.16，并验证go env GOPATH、GOROOT非空且PATH含$GOROOT/bin。
go version 必须输出 1.16+，否则 net/http 的一些关键行为（比如 http.ServeMux 的路径匹配逻辑）和 Go Modules 默认启用状态会出问题——这不是建议，是硬性前提。
确认 Go 版本与环境变量是否真正生效
很多人执行 go version 看到版本号就以为万事大吉，但实际项目中常因环境变量未加载或 shell 配置错位导致 go mod 失效或依赖解析异常。
- 在新终端中运行
go env GOPATH GOROOT，确认输出非空且路径合理（GOROOT通常为/usr/local/go或~/sdk/go；GOPATH在 Go 1.16+ 可省略，但若存在，不能指向系统目录如/usr） - 检查
PATH是否包含$GOROOT/bin和$GOPATH/bin（后者仅当需要本地安装 CLI 工具时才必要） - 避免在 root 用户下初始化项目——
go mod生成的go.sum文件权限可能引发后续 CI/CD 构建失败
用 go mod init 初始化模块时的命名陷阱
模块名不是随便起的。它直接影响 import 路径、私有仓库拉取逻辑，以及未来迁移到企业私有代理（如 JFrog Artifactory）时的解析规则。
- 本地开发可直接用
go mod init myapi，但上线前必须改为带域名的格式，例如go mod init github.com/myorg/myapi或go mod init gitlab.mycompany.com/backend/myapi - 模块名中不能含大写字母或下划线（Go 规范要求），否则某些 IDE 插件或静态分析工具会报错
- 如果项目将来要发布为公共库，模块名应与代码托管地址一致；否则
go get无法正确解析依赖
选 net/http 还是 gin？看这三点再决定
别被“高性能”宣传带偏。真实瓶颈往往不在框架层，而在数据库查询、序列化开销或中间件滥用。先明确你要解决的问题：
- 只需要几个固定端点、无复杂路由、不需中间件链管理 → 直接用
net/http：启动快、二进制小、调试链路短，http.HandleFunc+http.ListenAndServe足够 - 需要 JSON 绑定、参数校验、日志中间件、JWT 鉴权、Swagger 文档自动生成 → 上
github.com/gin-gonic/gin，但注意：gin.Default()自带Logger和Recovery，生产环境务必替换为自定义 Logger（避免日志刷屏掩盖真实错误） - 并发压测时发现 QPS 卡在 5k 以下 → 先检查是否用了
fmt.Sprintf拼接响应体、是否在 handler 里同步调用慢 DB 查询、是否启用了debug模式（gin.SetMode(gin.DebugMode)会显著拖慢性能）
go run 和 go build 在 API 开发中的实际分工
开发阶段用 go run main.go 是为了快速验证逻辑，但它每次都会重新编译整个依赖树，对大型项目很慢；而 go build 生成的二进制才是你最终交付的东西——它的启动时间、内存占用、信号处理行为都和 go run 不同。
立即学习“go语言免费学习笔记（深入）”；
- 本地调试时，加
-gcflags="all=-l -N"可禁用内联和优化，方便调试器单步进入标准库函数（比如想看http.ServeMux.ServeHTTP怎么匹配路由） - 构建生产二进制前，务必加
-ldflags="-s -w"去除符号表和调试信息，体积能减少 30%~50%，且避免被逆向分析出路径和函数名 - 不要把
go run当作部署手段——它不会自动 reload，也不会正确处理SIGHUP或SIGTERM，线上必须用./myapi启动
ReadTimeout 和 WriteTimeout。一个恶意客户端保持长连接不发数据，就能让 goroutine 卡住，最终耗尽服务器资源。哪怕只用 net/http，也得在 http.Server 实例上显式配置这两个字段。 
