应避免在main.go中直接写业务，因Go无隐式依赖机制，会导致import循环、测试困难、难以维护；需遵循“main包极薄”原则，将逻辑下沉至internal/等分层目录。
为什么不能直接从 main.go 开始写业务
因为 Go 没有隐式包依赖或自动加载机制，所有导入路径都基于项目根目录（go.mod 所在位置）解析。一旦把业务逻辑全塞进 main 包，很快就会遇到：import cycle not allowed、测试无法独立运行、接口无法 mock、命令行参数和 http 路由混在一起难以维护。
核心原则是：让 main 包极薄——只做三件事：初始化配置、构建依赖图、启动服务。其余全部下沉到可测试、可复用的内部包中。
-
cmd/下每个子目录对应一个可执行程序（如cmd/api、cmd/migrate），各自有独立的main.go -
internal/存放仅本项目使用的业务逻辑，外部模块无法 import（Go 1.14+ 对internal有强制限制） -
pkg/放真正可复用的工具库，比如自定义的httpclient、idgen，对外提供稳定 API - 配置文件（
config.yaml）、迁移脚本（migrations/）、API 文档（openapi.yaml）统一放在项目根下，不嵌套进internal
internal/ 里该分几层：domain、service、infrastructure？
不是必须分三层，但要按“变化原因”隔离。比如用户注册流程里，密码加密算法可能换（infrastructure 层变），校验规则可能加字段（domain 层变），而注册入口可能是 HTTP 或 CLI（Interface 层变）。硬套 DDD 分层容易过早抽象，建议先按职责粗分：
-
internal/domain/：纯结构体 + 接口定义，不含任何外部依赖。例如User结构体、UserRepository接口 -
internal/service/：实现核心业务逻辑，依赖domain接口，不碰数据库或 HTTP 客户端 -
internal/infrastructure/：具体实现，比如postgres.UserRepo、mailgun.EmailSender -
internal/handler/（或internal/api/）：只负责请求解析、响应包装，调用service，不写业务判断
如果项目初期只有 CRUD，service 和 handler 可暂时合并；等出现多个调用方（比如同时支持 REST 和 gRPC）再拆。
立即学习“go语言免费学习笔记（深入）”；
如何避免 go build 时误编译测试文件或未使用的包
Go 编译器默认会扫描整个模块路径，但实际生效的是你显式 import 的包。常见误伤场景：
- 把
internal/xxx_test.go放在非_test包里 → 编译失败，因测试辅助函数被当成正式代码引用 - 在
cmd/api/main.go中 import 了internal/migration，但没调用 → 仍会链接进去，增大二进制体积 - 使用
//go:build ignore注释跳过某些文件，但忘记加+build ignore（旧语法）导致 CI 环境行为不一致
推荐做法：
- 测试文件严格放在
xxx_test.go，且 package 名为xxx_test（非xxx） - 用
go list -f '{{.ImportPath}}' ./...检查哪些包会被实际加载 - 对非主入口的命令，用
go build -o bin/migrate ./cmd/migrate显式指定路径，不依赖通配符
什么时候该把代码拆成独立 module（go.mod）？
只有当某部分代码需要被其他 git 仓库复用，且版本迭代节奏与主项目不同时，才值得单独建 module。例如公司内多个服务共用的认证 SDK、监控中间件。否则，多 go.mod 会带来这些麻烦：
- 本地开发时
replace配置易出错，ide 可能无法正确跳转 - CI 构建需额外处理
go mod edit -replace步骤 - 语义化版本（v1.2.0）与主项目发布周期脱钩，反而增加协调成本
更轻量的做法是：保持单 go.mod，用 pkg/ 目录组织可导出能力，并通过 go doc pkg/auth 提供清晰文档。真要拆，也等第一个外部调用方出现后再动。
最常被忽略的一点：internal/ 下的包名不必和目录名一致，但必须确保同一目录下所有 .go 文件 package 名相同；否则 go build 会静默忽略部分文件。