go 中 internal 包仅允许同一 go.mod 模块路径前缀下的包导入，跨模块即使同 go.work 也不行；它仅在 import 阶段校验路径前缀，不提供运行时封装，需配合小写字段和接口实现真正隐藏。
为什么 go.work 下的 module 互相 import internal 包会报错
这不是 bug，是 Go 编译器按模块路径前缀硬编码的检查逻辑：只要 import 路径里含 /internal/，就只允许**同一 go.mod 声明的模块路径前缀下**的包导入。哪怕两个 module 在同一个 go.work 下，它们仍是独立模块，路径不构成父子关系。
常见错误现象：use of internal package not allowed 出现在 module-b 尝试 import "module-a/internal/db" 时；本地开发可能“侥幸通过”，但 CI 构建失败——大概率是工作目录路径（如 /tmp/build）和 go.mod 中声明的模块名不一致，导致路径匹配失效。
- 验证方式：运行
go list -f '{{.Module.Path}}' .确认当前目录所属模块路径 - 检查
go.work中是否用use ./module-a正确声明，而非仅靠文件系统位置假设可见性 -
vendor目录下的internal仍按原始模块路径判断，不是以vendor根为基准
internal 包在本模块内其实完全开放
internal 不限制包内访问、不隐藏符号、不约束运行时行为。它只是 import 阶段的守门员，不是私有封装机制。只要标识符首字母大写，cmd/、pkg/、甚至同模块下的测试文件（*_test.go）都能直接调用、实例化、反射读取。
典型误用：把 type Config struct { DBURL string } 和 func NewConfig() *Config 放进 internal/config，结果 cmd/api 直接 new 并修改 DBURL 字段——这违背了“隐藏实现”的初衷，后续重构时下游代码立刻崩。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 真正想隐藏细节，必须配合小写首字母字段 + 导出接口 + 工厂函数，例如返回
io.Reader而非具体struct - 测试文件若需隔离，不能依赖
internal，而要用package xxx_test显式声明包名 -
internal里的导出函数仍可被本模块其他包调用，无法防止内部误用
什么时候该用 internal，什么时候该用小写字段
internal 解决的是**跨模块依赖边界问题**；小写首字母解决的是**包内符号可见性问题**。两者目标不同，不能互相替代。
使用场景差异：
- 放
internal/middleware：适合 HTTP 中间件这类只供本项目多个 cmd 复用、但绝不希望外部项目import "github.com/myorg/app/internal/middleware"的逻辑 - 放
pkg/util：适合通用校验、HTTP 封装等明确设计为对外复用的能力，需配完整测试和文档 - 结构体字段用小写：比如
type User struct { id int; Name string }，确保外部无法直接读写id，只能通过方法暴露必要操作 - JSON 序列化时小写字段会被静默忽略，必须大写 +
json:"id"tag 控制 key 名
多模块项目中 internal 边界容易误判的三个点
最常被忽略的是：Go 不按文件系统路径，而按 go.mod 声明的模块路径做匹配。一个看似合理的目录结构，可能因模块声明偏差导致 internal 失效或过度封锁。
-
replace不能绕过internal检查：即使replace github.com/a/b => ./local，只要./local/internal/c被外部模块导入，照样报错 - CI 构建失败但本地 OK？优先检查
go env GOPATH和工作目录是否与go.mod模块路径对齐，go list -f '{{.Imports}}' ./cmd比直觉更可靠 - 真正共用逻辑，只有两个干净解法：提到独立公共 module（非
internal），或彻底放弃internal，改用小写类型 + 显式 API 设计
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
