go mod init 必须显式指定模块路径，如github.com/username/myapp或example.com/myapp，不可依赖目录名推断；路径需与所有import语句严格匹配，否则导致构建失败、依赖无法解析，且后续修改成本极高。
直接用 go mod init 初始化，不是“先建目录再写代码”，而是“先定模块路径，再建结构”。模块路径错了，后续所有 import 都会出问题，改起来成本远高于初始化时多想两秒。
go mod init 必须显式指定模块路径
不加参数运行 go mod init 会让 Go 尝试从当前目录名推导，比如你在 myapp 目录下执行，它可能生成 module myapp —— 这个路径无法被他人 go get，也不符合 Go 生态惯例。
- 正确做法：用真实或可预期的托管地址，如
go mod init github.com/yourname/myapp（即使还没 push 到 GitHub） - 本地开发可用
example.com/myapp，但别用myapp或./myapp - 路径中不能含
.git、v1、空格或非法字符；也不能是相对路径 - 执行后检查
go.mod第一行是否为预期的module声明，再运行go list -m确认输出一致
项目目录结构要从第一天就分清 internal 和 pkg
Go 不靠文件系统隔离访问权限，而靠 internal/ 目录名实现编译期私有约束——任何在 internal/ 下的包，只能被其父目录或同级子目录中的代码导入，外部模块无法引用。
-
cmd/：放主程序入口，每个子目录对应一个二进制，如cmd/myapp/main.go -
internal/：业务核心逻辑，如internal/service、internal/repository，绝不对外暴露 -
pkg/：设计为可复用、可独立go get的公共能力，如pkg/utils、pkg/middleware -
api/或proto/：接口定义、IDL 文件，与实现分离 - 避免把所有代码堆在根目录或
src/下——那是 GOPATH 时代的遗留习惯
go.mod 写错或路径变更后怎么救
模块路径写错不会报错，但后续 go build 时若代码里还按旧路径 import，就会出现 cannot find module providing package；更隐蔽的是，别人 clone 后 go run main.go 失败，却查不出原因。
立即学习“go语言免费学习笔记（深入）”；
- 修正命令优先用
go mod edit -module github.com/correct/path，比手动编辑go.mod更安全 - 改完必须同步更新所有
import语句，包括测试文件里的引用 - 运行
go mod tidy，观察是否出现require ...: version "" invalid—— 出现说明还有残留旧路径引用 - CI 流程中建议加一条
go list -m校验，确保模块名与预期完全一致
GO111MODULE=on 不是绝对保险
虽然 Go 1.16+ 默认开启模块模式，但某些场景下会静默退回到 GOPATH 模式，导致依赖不加载、go.mod 被忽略，而且不报错。
- 典型触发条件：当前路径含空格；
go get目标不含域名（如go get foo）；或目录不在任何go.mod的子树中 - 验证方式：运行
go env GO111MODULE，输出必须是on；再执行go list -m，应返回你的模块路径，而非command-line-arguments - 最稳做法：始终在项目根目录（即含
go.mod的目录）下操作，且路径不含空格和中文
真正容易被忽略的，是模块路径和目录结构的耦合性——它不只影响构建，更决定别人能否正确引用你的包、IDE 能否跳转、CI 能否复现环境。初始化那条 go mod init 命令，本质是在签一份契约：你承诺这个路径下的所有代码，将按这个路径被导入和维护。
