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，结果导致外部项目依赖了本该私有的逻辑。
立即学习“go语言免费学习笔记（深入）”；
- 放进
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 前，花十秒想想它会不会在未来某天形成闭环——这种直觉比任何工具都管用。
