Go 包组织与导入管理：拆包、import 分组…

在创建 Go 包、组织 import、规划代码分包或启动新 Go 项目时，用一套约定把包名、包大小、导入分组、init()、main() 与命令行 flag 规范化。

适用场景

解决思路

1. 按需读取参考文档：分组导入、使用空白导入/点导入/导入别名时读 references/IMPORTS.md；拆分包、避免 init、组织 main、设计 CLI flag/子命令时读 references/PACKAGE-SIZE.md。
2. 不要建泛化包：包名要描述它提供什么，避免 util、helper、common 这类名字，它们会掩盖含义并导致导入冲突。
3. 泛化词只能作为包名的一部分（如 stringutil），不能成为整个包名。
4. 用判据决定是否拆包：无法用一句话描述包用途 → 按职责拆分。
5. 用判据决定是否拆包：多个文件之间从不共享未导出符号 → 这些文件可以拆成独立包。
6. 用判据决定是否拆包：不同用户群使用包内不同部分 → 按用户边界拆分。
7. 用判据决定是否拆包：godoc 页面过于庞杂 → 拆分以提升可发现性。
8. 不要拆包的情况：仅因为单个文件太长、为了创建单类型包、或拆分会产生循环依赖。
9. import 按空行分组，标准库永远放最前；用 goimports 自动维护。
10. 分组规则：标准库在前，然后是外部包；扩展规则为 标准库 → 其他 → protos → 副作用导入（side-effects）。
11. 避免重命名导入，除非有命名冲突；冲突时重命名最局部的那个导入；proto 包统一加 pb 后缀。
12. 空白导入 import _ 只允许出现在 main 包或测试中。
13. 点导入 import . 永不使用，仅在测试文件处理循环依赖时例外。
14. 尽量避免 init()；无法避免时必须满足：完全确定性、不依赖其他 init() 的顺序、不依赖环境状态（环境变量、工作目录、参数）、不做 I/O（文件系统、网络、系统调用）。
15. init() 可接受的用途：无法写成单条赋值的复杂表达式、可插拔钩子（如 database/sql dialect）、确定性预计算。
16. os.Exit 或 log.Fatal* 只在 main() 中调用，其他所有函数都应返回 error（否则控制流不直观、不可测试、defer 会被跳过）。
17. 采用 run() 模式：把逻辑抽到 func run() error，在 main() 中调用并只保留一个退出点（if err := run(); err != nil { log.Fatal(err) }）。
18. 只在 package main 中定义 flag。
19. flag 名用 snake_case，如 --output_dir 而非 --outputDir。
20. 库应以参数接收配置，不直接读取 flag，以保持可测试与可复用。
21. 优先使用标准库 flag 包；只有在需要 POSIX 约定（双横线、单字符短选项）时才用 pflag。
22. 在 main 中解析 flag 后把取值作为参数传给库函数，例如 flag.String("output_dir", ".", "directory for output files") 后调用 mylib.Generate(*outputDir)。
23. 跨主题转交：包命名/避免 stutter/导出符号命名看 go-naming；跨包错误处理（%w vs %v）看 go-error-handling；导入 lint（goimports local-prefixes、强制导入分组）看 go-linting；用显式初始化替换 init() 或避免可变全局看 go-defensive。

适用边界 · 注意事项

• 命名包内单个标识符（包名选择、避免 stutter、导出符号命名）时，应改用 go-naming。
• 组织单个文件内部的函数时，应改用 go-functions。
• 配置强制导入规则的 linter 时，应改用 go-linting。