Go 包依赖图出现环时如何用接口拆开

遇到 import cycle not allowed 时，先别急着把文件搬来搬去。真正要拆的是包之间的依赖方向：如果 checkout 依赖 payment，而 payment 又依赖 checkout，Go 就无法编译。最稳妥的做法是让业务包定义自己需要的最小接口，让实现包只实现这个接口，最后在 main 组装两者。

先把 A → B → A 的循环边画出来

Go 规范把 import 声明定义为依赖关系，并明确禁止一个包直接或间接导入自己。因此下面这种结构不是运行时递归，而是在编译包图时就被拒绝：

checkout → payment → checkout

实际项目里，第二条边往往不是业务包直接调用业务包，而是支付实现为了复用订单类型、错误类型或回调函数，反过来导入了 checkout。这时要先问一句：支付包真的需要 checkout 的实现，还是只需要“扣款”这个能力？如果只是能力，接口就应该成为边界。

用接口倒转依赖时，接口该放在哪个包

接口的归属看“谁在消费能力”。checkout 需要支付，但它不应该知道具体是银行卡、沙箱还是第三方适配器，所以由 checkout 定义最小接口：

package checkout

import "context"

// PaymentGateway 是结算流程真正需要的能力，不暴露支付实现的细节。
type PaymentGateway interface {
	// Charge 只接收稳定的订单标识和金额，避免实现包反向依赖 checkout 的私有类型。
	Charge(ctx context.Context, orderID string, cents int64) error
}

// Service 只依赖能力，不依赖某个支付厂商或适配器。
type Service struct {
	payments PaymentGateway
}

// NewService 把依赖放在构造阶段，便于替换真实实现和测试替身。
func NewService(payments PaymentGateway) *Service {
	return &Service{payments: payments}
}

// Pay 完成结算侧的业务决策，再调用注入的支付能力。
func (s *Service) Pay(ctx context.Context, orderID string, cents int64) error {
	return s.payments.Charge(ctx, orderID, cents)
}

这里没有让实现包显式写“实现了 checkout.PaymentGateway”。Go 接口是隐式满足的，只要方法集合匹配即可。这样 payment 可以只依赖 context、网络客户端或更低层领域包：

package payment

import "context"

// Client 是支付适配器自己的配置和外部客户端边界。
type Client struct {
	endpoint string
}

// NewClient 创建支付实现；调用方不需要把实现细节带进 checkout。
func NewClient(endpoint string) *Client {
	return &Client{endpoint: endpoint}
}

// Charge 以与 checkout.PaymentGateway 相同的方法集合提供扣款能力。
func (c *Client) Charge(ctx context.Context, orderID string, cents int64) error {
	// 真实项目在这里调用支付服务，并处理 ctx 取消、超时和响应错误。
	return nil
}

在组合根组装，别让接口重新长回依赖环

最后把具体实现放到 main 或应用启动层。这里的导入关系是单向的：main 同时知道 checkout 和 payment，但两者不互相导入。

package main

import (
	"context"

	"example.com/shop/checkout"
	"example.com/shop/payment"
)

func main() {
	// 组合根拥有具体实现，把它交给只认识接口的业务服务。
	payments := payment.NewClient("https://pay.example.test")
	service := checkout.NewService(payments)

	// 这里仅示意组装边界；生产代码还应处理返回的业务错误。
	_ = service.Pay(context.Background(), "order-1001", 1999)
}

接口方法中的类型也很关键。如果把参数改成 *checkout.Order，实现包为了声明同样的方法就必须导入 checkout，循环可能再次出现。可以把共享的稳定数据移到低层 domain 包，或者先用 orderID、金额等基础类型表达契约，别把整个高层对象搬过边界。

用 go list 确认环已从包图消失

重构后可以先查看依赖列表，再正常编译目标包。排查重点是包路径是否仍指向高层，而不是只看某个文件能否通过语法解析。

# 输出当前模块的依赖包，确认 checkout 与 payment 不再互相回指。
go list -deps ./...

# 编译所有包；若仍有环，错误信息会给出一条 import 栈。
go test ./...

这两个命令不能替代设计判断，但能快速确认目录调整是否真的改变了包图。测试替身也应实现同一个小接口，而不是让测试包重新导入生产实现。

相关问题

把公共接口单独放到 common 包可以吗？

可以，但不要为了“公共”而提前抽象。若接口只服务一个消费者，放在消费者包通常更容易保持最小；只有多个独立消费者共享同一契约时，才考虑稳定的低层 contract 或 domain 包。

给实现类型加编译期接口检查有用吗？

有用，例如在实现包中写 var _ checkout.PaymentGateway = (*Client)(nil)，但这会让实现包显式导入 checkout。若该导入会形成环，就把检查放到组合根或测试包，不能为了检查破坏依赖方向。

接口能解决所有循环依赖吗？

不能。如果两个包共享的是数据模型、初始化副作用或双向事务边界，单独加接口可能只是把问题藏起来。此时应先拆出低层领域包，或重新划分职责，再决定接口位置。