go项目目录结构应依实际需求演进而非强制规范：满足多main、跨包复用、独立测试、依赖隔离等条件时才拆包；internal/需严格限定导入关系，pkg/应延后提取并附约束文档，cmd/按可执行文件分目录。
Go 项目没有强制的目录规范，但混乱的包结构会让 go build 失败、go test 找不到用例、依赖注入变脆弱，甚至让新成员花半天搞不清 internal 和 pkg 的边界。
什么时候该拆出一个新包？
不是按功能模块“感觉上”该分就分，而是看是否满足以下任一条件：
-
go list ./...显示该目录下有多个main函数或多个独立可测试逻辑单元 - 某组类型/函数被至少两个其他包导入，且不依赖当前主应用逻辑（比如通用校验、加密工具）
- 想对某部分代码做单独的
go test -race或打桩（mock），但当前包里混着 HTTP handler、DB 初始化和业务逻辑 - 该目录下
go.mod依赖项与其他包明显不同（例如只在这里用golang.org/x/exp/slices，其他包完全不用）
internal/ 不是“放所有内部代码的垃圾桶”
它只用于阻止外部模块直接 import —— 但很多人误以为只要放进去就安全。实际上，internal/foo 可被 cmd/app 和 pkg/bar 同时 import，这反而制造了隐式耦合。
真正合理的用法是：
立即学习“go语言免费学习笔记（深入）”；
-
internal/handler：只被cmd/xxx导入，绝不被pkg/下任何包 import -
internal/repo：只被internal/service导入，且其接口定义在pkg/domain中 - 一旦发现
pkg/xxximport 了internal/yyy，说明抽象层漏了——该把接口提到pkg/，实现留在internal/
别把 pkg/ 当作“可复用库”的默认前缀
很多团队一上来就建 pkg/utils、pkg/config，结果半年后发现：pkg/config 里硬编码了 Kubernetes ConfigMap 路径，根本没法被 CLI 工具复用。
更稳妥的做法是：
- 先写死在
internal/，跑通流程 - 等同一逻辑被第二个服务/命令复用时，再提取：把接口放
pkg/xxx，实现按场景分到internal/xxx/k8s和internal/xxx/file -
pkg/下每个子包必须带明确约束文档，例如pkg/trace的go:generate注释要写清：“仅允许依赖context.Context和标准库，禁止 import 任何internal/”
cmd/ 目录下不止能放 main.go
当项目需要多个可执行文件（如 myapp、myapp-migrate、myapp-debug），不要把它们全塞进一个 main.go 里用 flag 分支——这会让编译产物无法按需裁剪。
正确做法：
- 每个命令独占一个子目录：
cmd/myapp、cmd/myapp-migrate - 各自
main.go只做三件事：解析 flag → 构建依赖图（DI 容器）→ 调用入口函数 - 共用逻辑（如日志初始化、配置加载）抽到
internal/bootstrap，但确保它不 import 任何业务包
cmd/myapp-migrate/main.go
package main
import (
"log"
"myproject/internal/bootstrap"
"myproject/internal/migration"
)
func main() {
cfg := bootstrap.LoadConfig()
db := bootstrap.NewDB(cfg)
if err := migration.Run(db); err != nil {
log.Fatal(err)
}
}
最常被忽略的一点：包层级不是设计出来的，是随着测试覆盖率上升、重构次数增加、协作者反馈增多而自然沉淀下来的。过早套用“标准结构”，往往比从 main.go 开始写更危险。
