Go 语言通过 internal/ 目录约定实现模块内私有包：仅同 module 的父/祖先目录代码可导入，外部模块导入会编译报错；需配合 go.mod、pkg/cmd 分层、文档说明及 CI 检查。

Go 语言本身没有“内部包”或“模块私有包”的语法机制，无法像 Java 的 package-private 或 C# 的 internal 那样通过关键字限制包的可见性。但你可以通过约定 + 目录结构 + Go Modules + 文档约束实现“仅同一模块内可访问”的效果，这是 Go 社区广泛接受的实践方式。

使用 internal/ 目录约定

Go 官方支持一种特殊目录名：internal/。任何位于 internal/ 子目录中的包，只能被其父目录（或祖先目录）中同属一个 module 的代码导入，否则 go build 会直接报错：

import "mymodule/internal/auth" is not allowed to import "mymodule/internal/auth"

• 把希望“模块内私有”的包放在 ./internal/xxx/ 下（例如 ./internal/hasher/、./internal/configloader/）
• 确保你的项目已初始化为 Go Module（根目录下有 go.mod 文件）
• 外部模块（如别人 go get github.com/you/mymodule）无法 import github.com/you/mymodule/internal/hasher —— 编译器会拒绝
• 你自己的主程序、命令、其他内部包（如 ./cmd/、./pkg/、./internal/ 同级或上级）可以正常导入它

配合 pkg/ 和 cmd/ 明确分层

合理组织模块结构，能自然强化 internal 的边界：

Conventional Git

Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。

下载

• ./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 子模块或私有代理隐藏 —— 不是语言层隔离，且对依赖管理无实质帮助