Go 语言通过 internal/ 目录约定实现模块内私有包：仅同 module 的父/祖先目录代码可导入，外部模块导入会编译报错；需配合 go.mod、pkg/cmd 分层、文档说明及 CI 检查。
Go 语言本身没有“内部包”或“模块私有包”的语法机制，无法像 Java 的 package-private 或 C# 的 internal 那样通过关键字限制包的可见性。但你可以通过约定 + 目录结构 + Go Modules + 文档约束实现“仅同一模块内可访问”的效果，这是 Go 社区广泛接受的实践方式。
使用 internal/ 目录约定
Go 官方支持一种特殊目录名：internal/。任何位于 internal/ 子目录中的包，只能被其父目录（或祖先目录）中同属一个 module 的代码导入，否则 go build 会直接报错：
- 把希望“模块内私有”的包放在
./internal/xxx/下（例如./internal/hasher/、./internal/configloader/） - 确保你的项目已初始化为 Go Module（根目录下有
go.mod文件） - 外部模块（如别人
go get github.com/you/mymodule）无法 importgithub.com/you/mymodule/internal/hasher—— 编译器会拒绝 - 你自己的主程序、命令、其他内部包（如
./cmd/、./pkg/、./internal/同级或上级）可以正常导入它
配合 pkg/ 和 cmd/ 明确分层
合理组织模块结构，能自然强化 internal 的边界：
-
./cmd/myapp/：可执行入口，可 import./internal/...和./pkg/... -
./pkg/：供外部使用的公共 API 包（导出接口、类型、函数），不依赖 internal，也不暴露 internal 细节 -
./internal/：实现细节、工具类、中间件、私有模型等，只服务本模块 - 避免
./internal/中的包反向 import./pkg/或./cmd/，防止隐式耦合
用文档和代码注释明确意图
在 internal/ 包的 doc.go 或 README.md 中注明：
立即学习“go语言免费学习笔记（深入）”；
- “此包为模块内部实现，不保证向后兼容，外部不应直接依赖”
- 在
go.mod文件顶部加注释说明 internal 的使用规范 - CI 中可添加检查脚本，扫描是否有非本模块路径尝试 import
internal/（虽编译已拦截，但提前提示更友好）
不推荐的替代方案
以下做法不能真正解决问题，且易引发维护问题：
- 用未导出包名（如
myprivatelib）—— Go 不校验包名大小写，且无法阻止 import - 把代码全塞进
main包 —— 违背可测试性与关注点分离 - 用构建标签（
//go:build internal）控制文件编译 —— 复杂、难维护、不解决 import 可见性 - 靠 Git 子模块或私有代理隐藏 —— 不是语言层隔离，且对依赖管理无实质帮助
