Golang如何正确组织项目包结构

Go项目应将main包置于根目录或cmd/子目录；internal/包仅限模块内导入，pkg/包供外部复用；测试文件须与被测源码同目录且同包名；go mod tidy不报循环依赖但会导致运行时问题，需按domain→repo→service分层并避免反向引用。

main 包必须放在项目根目录或独立 cmd/ 子目录下

Go 的构建工具 go build 默认只识别当前目录下有 func main() 的 main 包。如果把 main.go 放在 src/app/ 或 internal/main/ 这类嵌套路径里，go run . 会报 no Go files in 或 cannot find package。

推荐做法是：项目根目录放一个极简 main.go，只负责初始化和启动

；或者统一收口到 cmd/ 目录下，每个可执行文件一个子目录：

myapp/
├── cmd/
│   ├── api/
│   │   └── main.go  // package main
│   └── worker/
│       └── main.go  // package main
├── internal/
│   ├── handler/
│   ├── service/
│   └── repo/
├── pkg/
└── go.mod

这样既能避免多入口混乱，又方便用 go build ./cmd/api 单独构建。

internal/ 和 pkg/ 的边界不能靠直觉判断

internal/ 下的包只能被同一模块（即同个 go.mod 根目录）下的其他包导入，Go 编译器会强制检查；pkg/ 则是约定俗成的“可被外部引用的公共能力封装”。但很多人误把所有工具函数塞进 pkg/utils，结果导致外部项目依赖了本该私有的逻辑。

• 放进 internal/：数据库连接池初始化、HTTP 中间件、领域模型的具体实现
• 放进 pkg/：通用 JSON 解析器封装（如 pkg/jsonx）、跨项目的错误码定义（pkg/errcode）、与业务无关的 ID 生成器（pkg/snowflake）
• 不建议放任何地方：直接操作全局变量的“工具函数”，比如 pkg/global.SetConfig() —— 它会让测试和复用变得脆弱

测试文件命名和位置必须严格匹配被测包

Go 要求测试文件名以 _test.go 结尾，且必须和被测包在同一目录。不能把 service/user.go 的测试写在 test/service/user_test.go —— 这样 go test ./service 会找不到测试。

常见错误包括：

• 测试文件放在错误目录（如上级 tests/），导致 go test 扫描不到
• 测试包名写成 package user_test 但被测包是 package service，此时无法访问非导出字段和函数
• 想测私有方法却硬改成 package service_test，结果因无法访问内部符号而绕路 mock，反而掩盖设计问题

正确做法：测试文件和被测源码同目录，包名用 package service（不是 _test 后缀），这样才能直接调用未导出函数做白盒验证。

go mod tidy 会暴露包循环依赖，但不会告诉你哪条路径

当两个包互相 import，比如 service 引了 repo，而 repo 又通过某个 utils 间接引回 service，go mod tidy 不会直接报错，但运行时可能 panic 或编译失败。更隐蔽的是，某些 IDE（如 Goland）会缓存旧 import 路径，显示“找不到符号”，实际是循环导致解析中断。

排查建议：

• 用 go list -f '{{.ImportPath}}: {{.Deps}}' 查看依赖树
• 在 internal/ 下按功能分层，例如 internal/domain（纯结构体+接口）→ internal/repo（只依赖 domain）→ internal/service（依赖 domain + repo），禁止反向引用
• 避免在 repo 层直接使用 service 返回的 DTO 类型，应定义 domain.User 作为数据契约

包结构不是一劳永逸的设计，每次新增 import 前，花十秒想想它会不会在未来某天形成闭环——这种直觉比任何工具都管用。