Go 的 internal 约定是编译器级硬限制，只要 import 路径含 /internal/ 且调用方不在其父目录树内，go build 就直接报错拒绝导入，该检查早于类型检查，不可绕过。
internal/ 目录为什么会让 go build 报错“imported and not used”以外的拒绝导入？
因为 Go 的 internal 约定是编译器级硬限制，不是文档建议。只要 import 路径里出现 /internal/，且调用方不在其父目录树下，go build 就直接失败，错误形如：import "xxx/internal/util" is not allowed by go.mod 或更直白的 use of internal package not allowed。
这个检查发生在解析 import 阶段，早于类型检查和未使用变量检测，所以它不会混在其他 warning 里——它就是一道门，跨不过去就停。
- 只认路径中的
/internal/（注意前后斜杠），internal作为包名或子目录名（如myinternal/）完全不受限 - 判定“是否允许导入”的依据是：调用方模块根目录（即含
go.mod的目录）是否在internal所在模块的目录树内 - 多模块项目中，即使两个模块在同一仓库，只要它们有各自独立的
go.mod，彼此也不能越过internal/边界
开源库把工具函数放 internal/ 后，下游用户还能用吗？
不能，除非你把它暴露成公开 API。这是 internal/ 的设计目的：明确划出「不承诺兼容、不供外部依赖」的边界。
常见误操作是：作者在 internal/ 里写了好用的 ParseURL 或 RetryClient，自己测试时从同一模块里调用没问题，就以为“别人也能用”。结果用户一 import "github.com/foo/bar/internal/http"，立刻 build 失败。
立即学习“go语言免费学习笔记（深入）”；
- 如果功能确实需要被下游使用，请放到顶层包（如
github.com/foo/bar/http）或显式导出子包（如github.com/foo/bar/pkg/client） -
internal/不是“暂时没文档”，而是“永远不许跨模块引用”——Go 不提供任何绕过机制（没有//go:allow-internal这种东西） - CI 中容易漏掉的问题：本地开发时所有代码在同一个模块下，
internal调用畅通无阻；但发布后用户单独go get，就彻底断连
internal/ 和 go:build tag 哪个更适合做 API 隔离？
internal/ 是隔离，//go:build 是条件编译——两者解决的问题根本不同，不能互相替代。
比如你想让某个函数只在 Linux 下编译，用 //go:build linux；但如果你想防止用户依赖你的序列化实现细节，就得靠 internal/encoding。前者控制“是否编译”，后者控制“是否可见”。
-
internal/隔离的是 import 路径可见性，与操作系统、架构、环境变量都无关 -
//go:build控制源文件是否参与构建，但它对包路径不做任何限制——你仍可import "xxx/internal/xxx"，只要该文件没被 build tag 排除 - 二者叠加使用很常见：比如
internal/platform/linux/下用//go:build linux，既保证跨平台安全，又守住内部边界
为什么有些知名开源库（如 golang.org/x/...）没用 internal/？
因为它们本身就是 Go 官方扩展生态的一部分，设计哲学是「稳定、可依赖、向后兼容」，所有包默认视为公共 API。它们不用 internal/，不是忘了加，而是刻意不加。
而你自己的库，只要没进 x/ 或被 Go 团队背书，就该默认假设：用户会把它当黑盒用，你不承诺内部结构稳定。这时候 internal/ 不是“防君子”，是防你自己未来改出 break change 后，用户哭着提 issue。
- 社区库越早用
internal/，重构成本越低——今天删掉internal/cache，没人会抱怨 - 别等 v1.0 再加：一旦公开路径被大量引用，再挪进
internal/就等于 breaking change - 真正难的不是加
internal/，而是判断哪些逻辑真该藏进去：比如 HTTP transport 层封装、proto 序列化桥接、配置加载策略——这些细节变起来最猛，也最该锁死
