Go项目初始化需执行三步：立即运行go mod tidy、手动补全go版本声明、检查replace路径；cmd/下按可执行目标拆分目录；internal/用业务域命名包并限制导出符号；首次提交前须通过go test、go vet和Docker构建验证。
Go项目初始化不是执行一条 go mod init 就完事——它直接决定后续依赖是否可复现、模块边界是否清晰、CI能否稳定构建。错一步，半年后你会在 go.sum 冲突和 import 循环里反复横跳。
go mod init 后必须立刻做三件事
很多团队跑完 go mod init example.com/myapp 就开始写业务，结果第二天发现依赖版本混乱、本地构建成功但 CI 失败。根本原因是没固化基础约束：
- 立即运行
go mod tidy：它会拉取当前代码中所有import的实际依赖，并写入go.mod；不执行这步，go.mod只是空壳 - 手动补全
go版本声明：在go.mod末尾加一行go 1.26（与你本地go version输出一致），避免不同 Go 版本下编译行为差异（比如泛型解析规则） - 检查并清理
replace：如果用了replace github.com/some/pkg => ./local-patch，确认该路径存在且已git add；否则go build会静默失败或 fallback 到远端旧版
cmd/ 目录不能只放一个 main.go
把所有启动逻辑塞进 cmd/myapp/main.go 是最常见结构退化起点。一旦你要同时支持 API 服务、定时任务、CLI 工具，就会出现条件编译、flag 冲突、配置加载耦合等问题。
- 按可执行目标拆子目录：
cmd/api/、cmd/worker/、cmd/cli/，每个目录下只有main.go和必要 flag 解析 -
main.go里禁止出现业务逻辑：不能有if env == "prod"分支，不能调用user.Create()，只能做四件事——解析 flag、加载internal/config、构造internal/server实例、调用.Run() - 共享初始化逻辑必须下沉：比如日志、trace、DB 连接池，统一放在
internal/bootstrap/，由各main.go显式调用，而非复制粘贴
internal/ 下的包名必须对应业务域，不是技术层
看到 internal/controllers/、internal/services/ 这类目录，基本可以判定项目半年内将陷入“改一个登录要 grep 七个文件”的状态。技术分层目录让业务边界彻底消失。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 用业务名词作包名：
internal/user、internal/order、internal/payment，每个包内再按职责分文件（service.go、repo.go、handler.go） - 跨业务调用必须走接口：比如
order需要用户信息，不能import "myapp/internal/user/repo"，而应定义user.UserService接口，由 DI 容器注入实现 - 包内导出符号要克制：一个
internal/user包，对外只暴露UserService接口和CreateUserRequest类型，绝不导出userModel结构体或 SQL 查询函数
第一次提交前必须验证的三项检查
很多人在 git commit -m "init" 后才发现 go test ./... 失败、go vet 报错、Docker 构建卡住。这些本该在首次提交前堵死：
- 运行
go test ./...：确保所有包（包括internal/下）有基础测试或空测试文件（哪怕只写func TestStub(t *testing.T) {}），避免后续 CI 因无测试文件报错 - 执行
go vet ./...：检查未使用的变量、死代码、printf 格式错误等静态问题，这类问题不会阻断编译但会导致线上诡异行为 - 验证
Dockerfile可构建：哪怕只是多阶段构建最简版（FROM golang:1.26-alpine → COPY . . → RUN go build -o /app ./cmd/api），确保go build路径正确、没有遗漏internal/引用
真正容易被忽略的是 internal/ 包的导入路径合法性——Go 工具链只检查路径中是否含 /internal/，不校验它是否在 module 根目录下。如果你把项目放到 ~/work/myapp/，但 go mod init 时用了 example.com/myapp，然后又在 cmd/api/main.go 里写 import "example.com/myapp/internal/user"，看似合理，实则 Go 会因路径不匹配拒绝编译。路径必须与 go.mod 中的 module 名完全一致，少一个字符都不行。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
