go mod init 必须在项目根目录执行且模块名需与 git 仓库路径严格一致，否则导致依赖解析失败、ci 构建不一致及私有包无法导入；同时须全局配置 goproxy 和 goprivate，并规范 internal/ 与 pkg/ 边界、强制 pre-commit 检查。
go mod init 必须在项目根目录执行，且模块名要与 Git 仓库路径一致
模块名写错会导致依赖解析失败、CI 构建不一致、私有包无法导入。比如仓库地址是 git.internal.company.com/myorg/myapp，但执行了 go mod init myapp，后续所有 import "myapp/internal/user" 在其他团队成员机器上都会报 cannot find module providing package。
正确做法是：
- 进入项目根目录（即包含 cmd/、internal/ 的那一层）
- 执行 go mod init git.internal.company.com/myorg/myapp
- 检查生成的 go.mod 第一行是否为 module git.internal.company.com/myorg/myapp
常见坑：
- 在子目录下误执行 go mod init，导致模块路径嵌套（如 module git.internal.company.com/myorg/myapp/cmd/api）
- 使用本地路径（如 ./myapp）或短名（如 myapp）初始化，Git 仓库迁移后全部失效
- 模块名含大写字母或下划线（Go 模块路径应全小写、用连字符分隔，如 git.internal.company.com/my-org/my-app）
GOPROXY 和 GOPRIVATE 必须全局统一配置，不能靠“本地改一下就行”
团队里有人用 https://goproxy.cn，有人用 https://proxy.golang.org，还有人没设 GOPRIVATE，结果就是：同一行 go build 在 A 机器成功、B 机器报 unknown revision、C 机器卡在下载私有模块超时。
固化配置的实操方式：
- 所有人执行：go env -w GOPROXY="https://goproxy.cn,direct"
- 私有域名必须显式声明：go env -w GOPRIVATE="git.internal.company.com/*,github.com/myorg/private-*"
- 验证是否生效：go env GOPROXY GOPRIVATE，输出不能是空或 off
为什么必须这么做：
- GOPRIVATE 不是“可选开关”，而是告诉 go mod “这些路径不走代理，也不校验 checksum”，漏设就等于把私有模块当公开包处理
- direct 在 GOPROXY 列表末尾是兜底项，确保代理不可用时仍能 fallback 到直接拉取（但仅对非 GOPRIVATE 路径有效）
- Shell 配置文件（如 ~/.zshrc）里写 export GOPROXY=... 容易被忽略或覆盖，go env -w 写入的是 Go 自己的 env 文件，优先级更高
internal/ 和 pkg/ 的边界必须强制约定，否则循环依赖静默发生
Go 编译器不会在 go build 时报 import cycle 错误，只有 go list -f '{{.Deps}}' ./... 或某些 IDE 才会提示。而循环依赖的真实后果是：go test ./ 跳过部分测试、go mod graph 显示异常依赖边、线上 panic 出现在 init 阶段。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
明确分工：
- internal/：只供本模块使用，禁止被外部 import（Go 语言层自动 enforce）
- pkg/：提供稳定 API 给其他模块复用，需有清晰接口定义和版本兼容承诺
- cmd/：只放 main 函数，不放业务逻辑
检查手段：
- 运行 go list -f '{{.ImportPath}}: {{.Deps}}' ./... | grep internal 查看是否有 internal/order 依赖 internal/user 又反过来依赖的情况
- 在 CI 中加入脚本：go list -f '{{if .Stale}}STALE: {{.ImportPath}}{{end}}' ./... | grep STALE，Stale 往往是循环依赖的副作用
- 禁止在 internal/ 包里 import 同级其他 internal/xxx，只能向下依赖（如 internal/user → internal/util），这是最易落地的红线
pre-commit 必须跑 go vet + staticcheck，不能只靠 PR 时 CI 拦截
等 CI 报 go vet: assignment to nil map 再修，已经晚了——代码已提交，可能被其他人基于错误分支开发，修复成本翻倍。更糟的是，go vet 能发现的资源泄漏、未使用的变量、错误忽略，在运行时才暴露，很难定位。
实操建议：
- 在 .githooks/pre-commit 中写：go vet ./ && staticcheck ./
- 用 staticcheck 替代已归档的 golint：go install honnef.co/go/tools/cmd/staticcheck@latest
- 若项目较大，可限定范围：go vet ./internal/... ./cmd/...，跳过 vendor/ 和生成代码
容易被忽略的点：
- go vet 默认不检查第三方包，但团队自己的包必须全量覆盖
- staticcheck 的 SA1019（使用已弃用 API）能提前发现兼容性风险，比等升级 Go 版本时报错更早
- 不要把检查命令写成后台异步执行（如加 &），否则 pre-commit 总是成功，失去拦截意义
模块化本身不提高协作效率，真正起作用的是对 go mod 行为的一致预期、对包边界的物理约束、以及把检查动作压到开发者本地操作环节。任何一处松动，都会在多人并行开发时放大成构建失败、行为不一致、排查耗时数小时的问题。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
