Go项目规范落地的四大雷区：go.mod必须声明≥1.20版本；internal/须严格置于项目根目录下以触发编译器强制隔离；sql.DB连接池参数需初始化后立即配置；HTTP handler必须封装响应逻辑，禁用裸写状态码与Header。
Go 项目一旦跨过单人小工具阶段，不落地规范就等于埋雷——不是“要不要做”，而是“哪几处不规范会立刻炸”。
go.mod 必须显式声明 go 版本且不低于 1.20
很多团队还在用 go mod init 生成默认的 go 1.16 或更低版本，这会导致两个实际问题：一是 embed、type alias 等关键特性不可用；二是某些新驱动（比如 gorm.io/driver/mysql v1.1+）在旧版本下编译失败或行为异常。
正确做法是初始化时就指定：
go mod init example.com/service<br>go mod edit -go=1.25
后续升级 Go 版本时，必须同步执行 go mod edit -go=1.25，不能只改本地 GOROOT。CI 流水线应校验 go version 与 go.mod 中声明的一致，否则直接失败。
立即学习“go语言免费学习笔记（深入）”；
internal/ 与 pkg/ 的边界必须由目录结构硬性隔离
Go 的 internal 包机制不是靠文档约定，而是由编译器强制检查：任何位于 /internal/ 子目录下的包，**仅能被其父目录或同级目录中的代码导入**。但很多人误以为只要起名叫 internal 就安全，结果把 internal 放在 pkg/internal 下，导致完全失效。
正确结构只有这一种：
-
./internal/service→ 可被./cmd和./internal/handler导入，但./pkg/utils不可导入 -
./pkg/utils→ 可被所有目录导入，包括外部模块 -
./cmd/api/main.go→ 只 importexample.com/service和example.com/pkg/utils，绝不 importexample.com/internal/xxx
一旦违反，go build 会报错：import "example.com/internal/db": use of internal package not allowed，但这个错误只在构建时暴露，测试和本地运行可能绕过——所以必须靠目录层级卡死。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
database/sql 连接池参数必须在初始化后立即设置
常见错误是调用 sql.Open 后直接使用，以为连接已就绪。实际上 sql.Open 只校验 DSN 格式，不建连；真正建连发生在第一次 Query 或 Exec 时，此时才触发连接池初始化，默认参数极不友好：
-
SetMaxOpenConns(0)→ 无上限，DB 很快被撑爆 -
SetMaxIdleConns(2)→ 默认值太小，高并发下频繁新建/销毁连接 -
SetConnMaxLifetime(0)→ 连接永不过期，MySQL 的wait_timeout会静默断连，后续请求报invalid connection
正确姿势是创建 *sql.DB 后立刻配置：
db, err := sql.Open("mysql", dsn)<br>if err != nil {<br> return err<br>}<br>db.SetMaxOpenConns(50)<br>db.SetMaxIdleConns(25)<br>db.SetConnMaxLifetime(1 * time.Hour)注意：SetConnMaxLifetime 值必须**小于数据库侧的 wait_timeout**（MySQL 默认 8 小时），否则连接会在 DB 端先被 kill，Go 客户端无法感知。
HTTP handler 中禁止直接写死 status code 和 header
看似简单的 w.WriteHeader(400) + w.Write([]byte(...)) 在真实服务中会迅速失控：错误码散落各处、Content-Type 忘设、JSON 响应没加 application/json、日志缺失 traceID、错误结构不统一。
必须封装响应逻辑，例如：
func JSONError(w http.ResponseWriter, code int, msg string) {<br> w.Header().Set("Content-Type", "application/json; charset=utf-8")<br> w.WriteHeader(code)<br> json.NewEncoder(w).Encode(map[string]string{"error": msg})<br>}更进一步，应统一用结构体返回：
type Response struct {<br> Code int `json:"code"`<br> Msg string `json:"msg"`<br> Data interface{} `json:"data,omitempty"`<br>}这样前端解析一致，中间件可统一注入 X-Request-ID，错误监控也能按 Code 聚类。手写裸 HTTP 响应只允许出现在健康检查（/healthz）等极简路径。
最常被跳过的其实是 internal 目录的物理位置和 sql.DB 的连接池初始化时机——它们不报编译错误，却在压测或上线后集中爆发。
