Go项目包管理失效的根本原因是模块路径与导入路径不匹配：go mod init必须在根目录执行，确保go.mod中模块路径与import语句完全一致；internal/仅限本模块使用，pkg/用于外部复用；cmd/需按二进制拆分子目录；测试文件须与被测代码同目录且以_test.go结尾。
Go 项目一旦超过十几个包，main.go 开始“找不到”自己写的模块，go build 报 import path does not exist，或者 go test 在子目录里跑不通——根本不是语法问题，是包结构没对齐 Go 的导入模型。
为什么 go mod init 必须在项目根目录执行
Go 的模块路径（module github.com/yourname/project）决定了所有 import 语句的解析起点。如果在 cmd/api 下误执行 go mod init api，模块名变成 api，那你在 internal/service 里写 import "github.com/yourname/project/internal/repo" 就会失败——Go 不会自动向上找，它只认 go.mod 里声明的模块路径。
实操建议：
- 项目初始化前，先
cd到你希望作为模块根的目录（通常是 Git 仓库根），再运行go mod init github.com/yourname/project - 检查
go.mod第一行是否与你预期的 import 路径完全一致（包括大小写、斜杠方向） - 避免在子目录下单独 init 模块；多模块项目是例外，但需明确用
replace或require显式链接
internal/ 和 pkg/ 的分工必须严格
internal/ 是 Go 官方约定的“仅本模块可用”区域，任何外部模块 import yourproject/internal/xxx 都会在 go build 时直接报错；而 pkg/ 是你主动暴露给外部复用的公共能力层（比如通用校验、ID 生成器）。
立即学习“go语言免费学习笔记（深入）”；
常见错误现象：
- 把数据库 client 放进
pkg/db，结果其他团队引入后发现依赖了你私有的internal/config，编译失败 - 把核心业务逻辑塞进
internal/，但 CLI 工具又需要调用它，只能硬拆出pkg/core，导致逻辑重复
正确做法：
-
internal/存放：领域模型、仓储实现、HTTP handler、配置加载器等强耦合代码 -
pkg/存放：可独立测试、无项目特有依赖的工具函数，例如pkg/ulid、pkg/httputil - 如果 CLI 和 API 共享大量逻辑，优先考虑抽成
internal/app+ 接口抽象，而非暴露internal内容
命令行入口（cmd/）必须按二进制粒度拆分
一个 cmd/ 目录下不能只有一个 main.go。当项目要同时提供 HTTP 服务、后台 worker、CLI 工具时，每个可执行文件应是独立子目录：cmd/api、cmd/worker、cmd/cli。它们各自有独立的 main.go，但共享 internal/ 和 pkg/。
这样做的关键好处：
- 构建不同二进制时互不影响：
go build -o bin/api ./cmd/api不会打包 worker 的依赖 - 便于 CI 分发：可以为
cmd/worker单独做 Docker 镜像，不带 HTTP 路由相关代码 - 避免
main.go变成“上帝文件”，里面堆满 flag 解析和条件启动逻辑
示例结构：
project/
├── go.mod
├── cmd/
│ ├── api/
│ │ └── main.go
│ ├── worker/
│ │ └── main.go
│ └── cli/
│ └── main.go
├── internal/
│ ├── handler/
│ ├── service/
│ └── repo/
└── pkg/
└── uuid/
测试文件位置和 go test 范围容易被忽略
Go 不强制测试文件和被测代码同目录，但 go test ./... 默认只递归当前目录下的 *_test.go。如果你把集成测试放在 test/e2e/，它不会被自动执行；如果把单元测试放在 internal/service/testdata/，go test 会跳过——因为 Go 只识别 xxx_test.go 后缀且位于包目录内。
实操要点：
- 单元测试必须和被测代码在同一包目录，文件名形如
service.go→service_test.go - 集成测试建议放在
internal/xxx/integration/，并用//go:build integration标签隔离，运行时加-tags integration - 避免在
cmd/下写测试：命令入口逻辑应极薄，重点测internal/层；若真要测 CLI 行为，用os/exec调用构建后的二进制，而非在cmd/xxx/main_test.go里 mockos.Args
最常被绕过的其实是 go.mod 中 replace 的副作用：本地开发时用 replace github.com/xxx => ../xxx 很方便，但一提交就失效；CI 环境里没这个路径，构建直接失败。真要解耦，用 go.work 或发布临时 tag，别让 replace 进主干。
