企业级Go项目需初始化时就规范模块名、目录结构与构建契约：模块名用合法URL格式且不含.git；cmd/按可执行程序隔离，internal/存放私有实现，pkg/仅放可复用库；配置加载须可测试，禁止直接调os.Getenv；首PR即严守规范防腐化。
企业级 Go 项目不是从 go mod init 开始就自动“企业级”了，关键在初始化时就约束好目录边界、依赖治理和构建契约——否则半年后你会在 internal/ 里翻出三个不同版本的 config 加载逻辑。
用 go mod init 但别用默认模块名
模块名不是包名，它要能支撑长期演进和多仓库协作。常见错误是直接用本地路径（如 go mod init myproject）或带 .git 后缀（github.com/org/repo.git），Go 会报错或导致代理失败。
- 模块名必须是合法 URL 格式，且不含
.git：用go mod init github.com/myorg/myapp - 如果项目暂不公开或不用 GitHub，可用内部域名（如
go mod init git.mycompany.com/platform/auth），前提是 GOPROXY 能解析该域名 - 模块名一旦提交到 Git，后续改名需同步更新所有
import语句、CI 脚本里的路径、以及依赖它的其他模块——成本极高，务必一次定准
目录结构按职责隔离，而非技术分层
企业项目最常踩的坑是照搬 Java 的 src/main/java/com/example/.../controller/ 模式，结果导致 pkg/ 里全是泛型工具、internal/ 里混着可复用组件、cmd/ 变成启动逻辑垃圾场。
-
cmd/下每个子目录对应一个独立可执行程序（如cmd/api,cmd/migrator），只保留最小 main 入口，业务逻辑全下沉 -
internal/是真正的私有域：所有不对外暴露的实现都放这里，包括 domain 模型、infrastructure（DB/Redis/Kafka 封装）、application service —— 它们之间可互相 import，但外部模块（含其他cmd/）不能 importinternal/xxx -
pkg/只放真正可被外部复用的库，比如pkg/logger或pkg/trace，且必须有清晰的 API 稳定性承诺（如 v1 标签、semver 版本号） - 避免
api/或proto/直接放在根目录；应归入internal/api/（服务端定义）或单独建api/（供外部消费的 OpenAPI/Swagger）
初始化时就要锁定构建与测试契约
很多团队等到上线前才发现 go test 跑不通 CI，因为没提前约定测试组织方式和覆盖率基线。
立即学习“go语言免费学习笔记（深入）”；
- 在
Makefile或justfile中固化命令：比如make test应等价于go test -race -coverprofile=coverage.out ./...，而非手敲一长串参数 - 禁用
go test ./...全局扫描：它会误跑cmd/下的 main 包（报no tests to run）或internal/xxx/testdata下的非测试文件；改用go test ./... -exclude=./cmd/...或显式列出包（go test ./internal/... ./pkg/...） - 首次提交前运行
go vet ./...和staticcheck ./...，把警告当错误处理；CI 中加入gofmt -s -d .检查格式，避免 PR 里塞满空格修改 - 配置
.golangci.yml时，不要全量启用所有 linter；优先开errcheck（忽略 error）、govet、gosimple，其他按团队节奏逐步接入
环境变量与配置加载必须可测试、不可 magic
用 os.Getenv("DB_URL") 直接读取环境变量看似简单，但会导致单元测试无法注入 mock 配置、本地调试依赖全局 shell 环境、K8s ConfigMap 更新后服务不 reload。
- 配置结构体必须定义在
internal/config/，用mapstructure或koanf解析，禁止在 handler 或 repository 层直接调os.Getenv - 支持多源加载：环境变量 > CLI flag > YAML 文件 > 默认值；顺序写死在代码里，不靠“运行时判断”
- 配置加载失败必须 panic 且打印明确错误（如
failed to load config: missing required field 'database.url'），而不是静默 fallback 到空字符串 - 单元测试中通过传入
io.Reader模拟 YAML 内容，或用koanf.WithConfigMap注入 map，确保配置解析逻辑可验证
真正难的不是搭出这个结构，而是让第一个 PR 就遵守它——尤其当有人想快速加个 “临时脚本” 放进 cmd/ 却偷偷 import 了 internal/ 里的未导出函数时，结构就从第一天开始腐化。
