Go包设计需严守四原则：包名与目录名一致；导出标识符最小化；消除循环导入；避免全局变量滥用。核心是明确暴露边界，控制依赖与生命周期。
包名与目录名不一致导致 import 失败
Go 要求 import 路径的末段必须与包声明的 package 名完全一致（大小写敏感），但很多人误以为只要目录结构对就行。比如目录是 ./utils/stringutil，却在文件里写 package strutil，结果 import "myproj/utils/stringutil" 时，stringutil 包暴露的却是 strutil 这个名字，调用 stringutil.ToUpper 直接报错 undefined: stringutil。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 包名用小写纯字母，避免下划线或驼峰；优先选短、明确、不易冲突的词，如
sqlx、zap，而非MyUtils - 新建包时，先定好
package xxx，再建同名目录；不要靠 IDE 自动推导或重命名目录后忘记改package声明 - 用
go list -f '{{.Name}}' ./path/to/pkg快速验证实际解析出的包名
公开标识符首字母大写失控，暴露内部实现
Go 依赖首字母大小写控制可见性：大写 = 导出（public），小写 = 包内私有。常见错误是把本该封装的结构体字段、辅助函数、中间类型全设为大写，导致使用者误用或强依赖内部细节。例如导出 type Config struct { Timeout int }，后续想加校验逻辑或改为 time.Duration 就得大版本升级。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 只导出使用者**必须直接调用**的接口、函数、类型；字段除非明确要被外部读写，否则一律小写
- 用小写字段 + 大写方法封装访问，如
timeout int配Timeout() time.Duration和SetTimeout(d time.Duration) - 对内部工具函数，加
_后缀或放internal/子目录（如internal/encoding），利用 Go 的internal导入限制拦截越界引用
循环导入（import cycle）硬编码修复失败
两个包互相 import 是编译错误，但开发者常试图“绕过”：比如 A 包把本该在 B 包定义的回调类型移到 A 中，再让 B 接收该类型——表面解了 cycle，实则把 B 的抽象能力锁死在 A 的上下文里。更糟的是，有人用 _ "xxx" 强制触发 init，掩盖真正依赖路径。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 遇到 cycle，第一反应不是改 import，而是问：是否职责混杂？通常意味着缺少一个中间抽象层，比如提取公共接口到新包
contract或model - 用
go mod graph | grep 'pkgA.*pkgB\|pkgB.*pkgA'定位具体哪条路径成环 - 避免在
init()里做跨包状态初始化；状态应由上层（如main）显式传递，而非靠 import 触发隐式耦合
未约束包生命周期，全局变量滥用
Go 包级变量（尤其是 var 声明的指针、map、sync.Pool）天然单例，但很多人忽略其生命周期与程序主流程脱钩。典型如 HTTP 中间件包里定义 var cache = map[string]string{}，没加锁、没清理、没测试并发安全，上线后 panic 或内存泄漏。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 包级变量只用于真正无状态、不可变或只读数据（如
var Version = "1.2.0"）；可变状态必须封装进结构体，由使用者显式创建实例 - 需要共享资源（如连接池、缓存）时，提供
NewXxx() *Xxx构造函数，而非暴露全局变量；让调用方控制生命周期 - 若真需全局单例（如 logger），用
sync.Once延迟初始化，并确保初始化函数幂等、无副作用
包设计最难的不是语法，而是判断哪些东西该“露出来”、哪些该“藏起来”，以及藏到什么程度。很多问题在单元测试里不暴露，一到集成环境就崩——因为测试总在理想路径跑，而真实依赖链会不断试探你的边界。
