模块边界不清晰导致循环依赖的根源是业务语义模糊，应通过降级数据引用、提取共用逻辑、明确 internal/pkg 职责、调用方定义接口及审慎使用 replace 来系统治理。
模块边界不清晰导致循环依赖
最常见现象是 go build 报错 import cycle not allowed，但真正问题不在编译器——它只是暴露了架构裂痕。当你发现 user 包 import order，而 order 又 import user，说明业务边界被模糊处理了。
解决方法不是加个 internal/ 目录就完事，而是回退一步问：这两个包之间是否真的存在「双向业务语义」？比如「用户下单」和「订单归属用户」本质是单向依赖——订单需要用户 ID，但用户不需要知道订单状态流转细节。
- 把跨域数据引用降级为值类型（如
UserID int），而非结构体或接口 - 将共用逻辑（如 ID 生成、基础校验）提取到
pkg/id或pkg/validate，禁止直接 import 对方业务包 - 用
go list -f '{{join .Deps "\n"}}' ./user检查依赖链，确认是否意外引入了反向路径
internal/ 和 pkg/ 的误用场景
很多人把 internal/config 当成“所有配置都往里塞”的垃圾桶，结果 cmd/api 和 cmd/worker 都依赖它，却各自加载不同环境变量，最终在 CI 中跑出不一致行为。
internal/ 不是“内部代码存放区”，而是 Go 工具链强制的**可见性防火墙**；pkg/ 也不是“公共工具集合”，而是对外提供契约的**稳定接口层**。
立即学习“go语言免费学习笔记（深入）”；
-
internal/config只负责解析原始配置（YAML/JSON），返回结构体，不做任何业务判断 -
pkg/logger必须有明确接口定义（如LogInfo(ctx, msg string, fields ...any)），且不依赖具体实现（zap/logrus） - 一旦
pkg/util开始出现func NewOrderClient(...)这类业务强相关函数，说明它已越界，该拆成pkg/orderclient
跨模块调用时的接口放置位置
错误做法：在 order/service.go 里定义 UserGetter 接口，再让 user 包实现它——这等于把订单模块的依赖契约强加给用户模块，违反了依赖倒置原则。
正确做法是让调用方定义所需能力，被调用方适配。比如订单创建流程需要获取用户信息，那就在 order 包里声明：
package order
type UserReader interface {
GetUserByID(ctx context.Context, id int) (*User, error)
}
然后由 user 包提供实现，并通过构造函数注入到 OrderService 中。
- 接口永远放在**调用方所在模块**，这是解耦的第一道防线
- 禁止在
pkg/下放业务接口（如pkg/useriface），那是对复用性的误判 - 如果多个模块都要调用同一能力（如发邮件），应由它们共同依赖一个新
pkg/notifier，而非各自定义相似接口
replace 本地开发与正式构建的割裂风险
用 replace github.com/org/project => ./local-fork 很方便，但容易忽略：CI 构建时不会走 replace 路径，导致本地能跑通、线上 panic。
关键不是禁用 replace，而是控制它的作用范围和验证节奏。
- 只对尚未发布的内部模块使用 replace，第三方库一律走真实版本
- 每次提交前运行
go mod verify+go build -o /dev/null ./...，确保无 replace 也能构建 - 在
go.mod顶部加注释说明 replace 用途，例如：// replace: temp fix for issue #123, remove after v1.4.0 release
真正难的不是画清模块边界，而是当产品提了一个“用户下单后自动发优惠券”需求时，你得立刻判断这个逻辑该落在 order、coupon 还是新建 promotion 包——边界感来自对业务语义的持续校准，不是一次设计就能定终身。
