internal包因Go编译器强制检查路径中/internal/而无法被外部模块导入，这是编译期硬性约束，非约定；其作用范围由go.mod所在模块边界决定，用于严格隔离实现细节与公共接口。
大型 Go 项目不是靠堆代码规模撑起来的，而是靠清晰的边界、可预测的导入规则和团队能一致遵守的约束。关键不在于“写多少”，而在于“谁能在哪改什么”——internal 是 Go 编译器给你的唯一硬性访问控制开关，用不好，模块就形同虚设。
internal 包为什么不能被外部模块导入
Go 编译器在构建时会静态检查每个 import 语句：只要路径中包含 /internal/，且导入方不在其父目录或父目录的同级目录下，就会报错 use of internal package not allowed。这不是约定，是编译期强制拦截。
- 错误示例：
myproject/internal/service/user可被myproject/cmd/app导入（因为cmd和internal同级），但不可被github.com/other/repo导入 - 陷阱：如果你把
internal放在子模块根目录下（如myproject/user-service/internal/...），而该子模块又作为独立仓库发布，那它的internal对外部仍是封闭的——这是正确行为，不是 bug - 注意：这个限制只作用于包路径，不影响
go mod vendor或构建产物；它纯粹是为了防止源码级误引用
pkg 与 internal 的分工必须明确
pkg 是你主动暴露的“公共接口层”，internal 是你默认隐藏的“实现细节区”。二者不能混用，否则会破坏抽象边界。
-
pkg/utils应提供无业务耦合的通用函数，比如TrimSpace、ParseDuration；它会被多个子模块甚至外部项目依赖 -
internal/config只负责解析本项目配置结构体，不导出解析逻辑给外部；如果其他服务也要读 config，应该抽成pkg/config并明确定义契约 - 常见错误：把数据库模型结构体放在
pkg/model，结果导致所有调用方都强依赖 ORM 实现细节；应改为internal/repository定义实体，pkg/domain定义纯业务结构体
go.mod 文件位置决定模块粒度
一个 go.mod 对应一个模块，模块路径（module example.com/foo）就是它的全局唯一标识。模块边界直接决定 internal 的作用范围。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- Monorepo 场景：整个项目只有一个
go.mod在根目录，所有internal/xxx都受同一套规则约束 - Polyrepo 场景：每个子服务有自己的
go.mod，比如user-service/go.mod中定义module github.com/org/user-service，那么它的internal只对这个模块生效 - 危险操作：在子目录里手动运行
go mod init创建新模块，却没调整 import 路径，会导致本地能编译、CI 失败（路径不匹配）
结构体字段命名与可见性要配合包边界
字段小写 + 方法导出，只是封装的第一层；真正起作用的是包层级的隔离。别指望靠私有字段挡住跨包误用。
- 反模式：
internal/service/user.go里定义type User struct { ID int; Name string }，然后在pkg/api里直接接收这个 struct —— 这等于把内部实现暴露给了 API 层 - 正解：在
pkg/domain定义User（导出字段），internal/service只通过方法参数或返回值与之交互；转换逻辑收口在internal/adapter - 性能提示：频繁在
internal和pkg之间做 struct 转换？说明边界划分过细，或缺少统一的领域模型层
最容易被忽略的一点：internal 不解决循环依赖，只解决非法导入。如果两个 internal 子包互相 import，Go 一样会报错——这时候得靠重构拆分，而不是加个中间包绕开。
