Go模块拆分应避免循环依赖、接口与实现过度分离、构建膨胀及版本割裂，优先按变更频率和协作边界划分包，保持单module结构并共置强关联代码。
模块间循环依赖会直接导致构建失败
Go 的 go build 和 go mod tidy 在检测到循环导入时会立即报错，比如 A 包 import B，而 B 又 import A（哪怕只是通过间接依赖），错误信息类似：import cycle not allowed。拆分过细后，原本内聚的业务逻辑被分散到多个小包，极易因“为复用而拆分”引发隐式循环——例如把一个结构体定义在 model 包，把它的校验逻辑放在 validator 包，又把校验错误码放在 error 包，结果三者互相引用。
- 实际排查时，
go list -f '{{.Deps}}'可辅助查看依赖链 - 优先把强关联的类型、方法、错误定义保留在同一包内，哪怕暂时重复几行代码
- 用
//go:build ignore或临时注释掉部分 import 是调试循环依赖的最快手段
接口与实现绑定变脆弱，mock 成本飙升
过度拆分常导致接口定义和实现被强行隔离到不同包，比如 repository.Interface 放在 contract 包，repository.Postgres 放在 infra 包。表面看符合“面向接口编程”，但实际带来两个硬伤：一是测试时需手动构造完整依赖树（contract.NewRepo() 往往要传一堆 infra 实例）；二是只要接口字段微调，所有实现包都得同步改，失去“接口稳定、实现可换”的初衷。
- 接口定义尽量和默认实现共存于同一包，例如
repository包里同时有Repo接口和postgresRepo结构体 - 只在真正需要多实现（如内存版 vs 数据库版）且调用方完全不感知实现差异时，才把接口抽到独立包
- 单元测试中直接 new 实现 struct，比 mock 一整套 interface 更快更稳
构建时间和 vendor 体积明显增加
每个 Go 包对应一个编译单元，包越多，go build 并行调度开销越大，特别是启用了 -toolexec 或静态分析工具时。更直观的是 go mod vendor 后的体积膨胀——10 个各含 2 个文件的小包，可能比 1 个含 20 个文件的包多出 3–5 倍的目录层级和元数据（go.mod、go.sum 复制、缓存哈希等）。
- 用
go list -f '{{.ImportPath}} {{.Deps}}' ./...统计总包数和平均依赖深度 - 非核心功能（如 CLI 命令、HTTP handler）可先集中在一个
cmd或http包内，等逻辑稳定再按领域边界拆 -
vendor/下包名重复（如多个github.com/xxx/log变体）往往是拆分失控的信号
版本升级时语义化约束失效
Go 模块版本号（v1.2.3）作用于整个 module 路径，不是单个子包。当把 github.com/org/project 拆成 github.com/org/project/core、github.com/org/project/api 等多个 module，每个都独立发版，调用方就必须显式管理十几个 require 行。更麻烦的是，core/v2 升级可能要求 api/v2 同步升级，但 Go 的 go get 不会自动对齐——它只认 module 路径，不理解“这些包本该是一体的”。
- 除非子包确需独立演进（如 SDK 提供多个可选组件），否则坚持单 module 结构
- 用内部子目录（
project/internal/core）替代独立 module 来组织代码，既保持物理隔离又避免版本割裂 - 若必须多 module，用
replace在主模块go.mod中强制统一子模块版本
module github.com/org/project
go 1.21
require (
github.com/org/project/core v1.0.0
github.com/org/project/api v1.0.0
)
replace github.com/org/project/core => ./core
replace github.com/org/project/api => ./api
包拆分没有银弹，真正的边界来自“变更频率是否一致”和“谁会同时修改这些代码”。一个函数被三个不同团队频繁改动，就该拆；十个函数永远只被同一个 PR 修改，硬拆只会让问题更难定位。
