internal 是 Go 编译器强制的访问边界，路径匹配严格且仅在编译期生效；仅允许直接祖先或其子目录导入，不递归识别、不区分大小写错误，测试应同包进行，跨模块共享需独立成包。
internal 包不是“建议用”，而是编译器强制的访问边界——写错路径或放错位置，go build 直接报错，没商量。
为什么 import "xxx/internal/yyy" 会编译失败
Go 的 internal 机制只在编译期生效，且路径匹配严格：调用方必须位于 internal 所在目录的**直接祖先目录或其子目录内**。比如：
-
github.com/org/project/internal/repo只能被github.com/org/project/cmd、github.com/org/project/internal/handler导入 -
github.com/org/project-v2/cmd即使名字相似，也不行——路径字面不匹配 -
github.com/org/project/internal/repo不能被github.com/org/shared导入，哪怕两个模块在同一 Git 仓库
常见错误是把 internal 放在子模块根目录下（如 payment/internal/db），但主模块的 go.mod 声明的是 github.com/org/payment，此时 payment/cmd 能导入，而 order/cmd 就不行——因为 order 和 payment 是两个独立模块，彼此看不到对方的 internal。
internal 目录下还能再建 internal 吗
不能。Go 不递归识别 internal，只检查路径中是否**字面包含 /internal/**。所以：
立即学习“go语言免费学习笔记（深入）”；
-
internal/repo/mysql✅ 合法，受保护 -
internal/repo/internal/mysql❌ 多余，第二层internal不起作用，还误导人 -
Internal或internall❌ 大小写或拼写错误，完全不触发限制
如果需要跨多个业务包共享逻辑（比如 user 和 order 都要用的 ID 生成器），不要塞进某个 internal 下再硬导出，而是提成独立模块：github.com/org/idgen，放进 pkg/ 或单独发版。
测试时想调用 internal 里的函数怎么办
别 export，别 move 出去，也别用 replace 或软链接绕过——这些在 CI、vendor、交叉编译里全崩。正确做法就一个：
- 保持函数私有（小写开头）
- 在同包下写
xxx_test.go文件 - 直接调用，无需 import —— Go 允许同包测试文件访问所有非导出符号
例如 internal/user/service.go 里有个 validateEmail()，就在 internal/user/service_test.go 里测它。不需要把它提到 pkg/，更不该为测试开个后门。
go mod tidy 报 internal 引用错误，怎么查
这类错误往往不是代码写错了，而是模块路径污染了：
- 检查
go.mod的module声明：是否误写成module github.com/org/project/internal/db？这会让整个子路径变成可公开模块，破坏隔离 - 确认没有在
replace或require里引用自己项目的internal子路径 - CI 打包时是否意外把
internal/目录打包进了发布 artifact？下游项目解压后路径结构变了，go build自然判定越权
最稳妥的自查方式：删掉本地 go.sum 和 vendor/，执行 go mod tidy -v，看它实际解析出哪些 module path —— 如果出现带 /internal/ 的路径，就是根源。
真正难的不是写对 internal，而是守住它的语义：它代表“这里的东西你不该碰”，而不是“我暂时不想让你碰”。一旦开始绕过，边界就塌了，后面所有人写的代码都会默认它可导出。
