Go 中重构包需保持导出一致性、依赖方向清晰和 API 稳定性；拆分应解决职责混杂问题，合并须统一版本与错误类型，辅以 gorename 等工具验证依赖流向。
在 Go 中重构包（拆分或合并模块）不是靠改 import 路径那么简单，核心是保持 导出一致性 、 依赖方向清晰 和 API 稳定性。只要遵循 Go 的包语义和最小依赖原则，拆分与合并都可平滑推进。
明确拆分目标：从“职责混杂”到“单一接口”
当一个包同时处理数据库操作、HTTP 序列化、业务校验和日志埋点时，它就该拆了。拆分前先回答三个问题：
- 哪些类型 / 函数被多个上层模块共用？—— 这些应保留在基础包（如
model或domain） - 哪些逻辑只被某类 handler 使用？—— 可抽成
http/xxx或api/xxx - 是否有跨包循环依赖？—— 拆分后必须消除，否则编译失败
安全拆分四步法（不破坏现有调用）
以将 pkg/service 拆出 数据访问 层为例：
- 新建包：
pkg/repository，把原 service 中的 SQL 构建、DB 调用相关结构体和方法移入 - 保留旧符号（临时）：在
pkg/service中用type UserRepository = repository.UserRepository类型别名，或转发关键方法 - 更新 import 并验证：确保所有调用方仍能编译；用
go list -f '{{.Deps}}' ./……检查依赖是否反向渗透 - 逐步迁移 + 弃用提示：在旧包中为移走的函数加
// Deprecated: use repository.XXX instead注释，后续版本删除
谨慎合并：避免“大包主义”，但允许合理聚合
合并通常发生在过度拆分之后（比如 user/v1、user/v2、user/common 并存）。合并不是简单删文件夹，而是：
立即学习“go 语言免费学习笔记（深入）”；
- 统一版本标识：若各子包语义一致，合并后用
pkg/user，内部通过 interface + struct 实现多态（如UserStorer接口，不同实现对应不同存储） - 收敛错误类型：把分散的
ErrNotFound统一定义在pkg/user/errors.go，其他地方只 import 使用 - 导出最小集：合并后不暴露底层细节（如 SQL driver），只导出
CreateUser()、FindUserByID()等业务方法
工具 辅助与验证要点
手动重构易出错，推荐组合使用：
-
gofmt+goimports：自动修复 import 列表和格式 -
gorename（来自 golang.org/x/tools）：安全重命名符号，跨包引用自动更新 -
go mod graph | grep yourpkg：确认依赖流向是否符合预期（例如handler→service→repository，不可倒置） - 写轻量 smoke test：在
pkg/service目录下放一个service_smoke_test.go，只调用入口函数验证行为未变
包结构优化本质是让代码更贴近业务演进节奏。拆分不是为了“微服务化包”，合并也不是为了“省目录”。关键是每次改动后，新老代码都能跑通、新人能看懂依赖链、扩展功能时不用动三处才能加一个字段。
