go mod init的模块名必须是全局唯一且可解析的路径（如github.com/org/project），因为它直接决定import解析、依赖拉取及replace/require行为，否则会导致跨环境构建失败。
Go 环境本身不强制要求统一目录结构，但团队协作中若放任各自随意组织，go mod 会因路径差异、replace 写法不一致、CI 构建失败等问题高频报错——真正需要统一的不是物理路径，而是模块语义和导入路径的一致性。
为什么 go mod init 的模块名必须是全局唯一且可解析的
模块名（如 github.com/org/project）不只是个字符串，它直接决定 Go 工具链如何解析 import 语句、从哪拉取依赖、是否启用 replace 或 require。如果 A 同学初始化为 myproject，B 同学初始化为 github.com/team/myproject，哪怕代码完全一样，go build 在对方机器上也会报 cannot load myproject/xxx: module myproject@latest found (v0.0.0-00010101000000-000000000000), but does not contain package myproject/xxx。
- 模块名应与代码托管地址严格对齐，例如 GitHub 仓库地址是
https://github.com/acme/backend，则必须用go mod init github.com/acme/backend - 不要用本地路径（如
./backend）、相对路径或简写（如backend）作为模块名 - 私有仓库需提前配置
GOINSECURE或GOPRIVATE，否则go get会因 HTTPS 重定向或认证失败中断
internal/ 目录不是摆设：它的导入限制由编译器硬性执行
Go 编译器在构建时会静态检查所有 import 路径，一旦发现外部模块（比如 github.com/other/repo）试图 import github.com/acme/backend/internal/auth，会直接报错：use of internal package github.com/acme/backend/internal/auth not allowed。这是 Go 唯一靠语言机制保障的“访问控制”。
-
internal/下的包只能被同一模块根目录下的代码导入（即github.com/acme/backend下的cmd/或pkg/可以 import，其他模块绝对不行） - 团队必须约定好哪些逻辑属于“内部实现细节”，并放入
internal/；哪些是稳定对外暴露的 API，必须放在pkg/或模块根下 - 切勿在
internal/中定义供外部调用的接口类型，否则下游无法实现该接口（因为无法 import 定义）
CI 构建失败八成是因为 GOBIN 和 PATH 没配对
本地能 go run cmd/api/main.go 成功，CI 却卡在 command not found: golangci-lint 或 cannot find module providing package github.com/acme/backend/cmd/api，往往不是代码问题，而是环境变量没对齐。
-
GOBIN是 Go 工具链安装二进制的位置（如golangci-lint、mockgen），但 CI 默认不会把它加进PATH—— 必须显式追加，例如在 GitHub Actions 中加一步：echo "$HOME/go/bin" >> $GITHUB_PATH - 本地开发常用
export PATH=$PATH:$GOBIN，但 CI 流水线每个 step 是独立 shell，PATH 不继承，必须每步都重置或用add-path（已弃用）或$GITHUB_PATH（推荐） - 不要在 CI 中用
go install安装工具到默认位置（$GOROOT/bin），那需要 sudo 权限；统一用go install -o $GOBIN/toolname
真正难统一的从来不是文件夹名字，而是每个开发者对“这个包能不能被别人 import”“这个命令在 CI 里到底跑在哪”“模块名改了要不要同步更新所有 replace 行”的直觉判断。这些判断一旦出错，错误信息不会告诉你“你违反了团队规范”，只会甩给你一行模糊的 no required module provides package —— 那才是协作成本最高的地方。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
