Go import cycle 怎样拆成更稳定的包边界

我在把一个小 Go 服务拆成多个目录时，最容易低估的报错就是 import cycle not allowed。它看起来像是某个文件放错了位置，实际却是在提醒你：包依赖图已经形成闭环，编译器无法把包按单向顺序装载。解决办法不是调整 init，而是重新划分职责，让依赖只朝一个方向流动。

官方资料：https://go.dev/ref/spec

这篇只处理一个问题：怎样把现有的 import cycle 拆成更稳定的包边界。示例会用 domain/types 承载真正共享的数据，用消费方接口隔离实现，最后由 cmd/app 这个组合根完成装配。

先把报错还原成最小的导入环

Go 的一个包可以由同一目录下的多个源文件组成，而不同目录通常代表不同的可导入包。当 api 为了调用业务逻辑导入 service，service 又为了复用请求结构或错误类型导入 api，路径就会变成：

api -> service -> api。

这不是“两个包互相调用”这么简单，而是编译阶段无法先完成其中任何一个包。Go 规范对包初始化的描述也建立在导入包先于当前包初始化的前提上；导入图有环时，根本没有合法的先后顺序。

// 这个示例只展示职责错误：service 不应该反向依赖 api 的请求类型。
package api

import "example.com/demo/internal/service"

// Handler 把 HTTP 层输入交给业务包处理。
func Handler() {
	service.Run(Request{})
}

// 反向导入 api 后，api -> service -> api 形成 import cycle。
package service

import "example.com/demo/internal/api"

// Run 直接接收接口层的请求类型，业务包因此被接口层绑住。
func Run(req api.Request) {}

目录名本身没有魔法。把 api 改成 handler，或者把文件移动到 internal，如果导入方向没有改变，循环仍然存在。

先下沉共享数据，再处理行为依赖

第一步通常不是马上抽象一堆接口，而是找出两个包都需要、但不应该属于接口层的内容。例如用户资料、查询参数和业务错误可以移动到一个更中立的 internal/domain/types 包。这个包只放稳定的数据契约和纯值对象，不导入 api、service 或数据库适配器。

// domain/types 只描述业务数据，不知道请求来自 HTTP 还是命令行。
package types

// User 是 api 和 service 都需要理解的最小业务对象。
type User struct {
	ID   string
	Name string
}

// FindUserInput 只保留业务查询真正需要的字段。
type FindUserInput struct {
	ID string
}

调整后的方向可以是 api -> service -> domain/types，也可以是 api -> domain/types。关键不在于所有包都必须排成一条直线，而在于 domain/types 不再反向引用上层。

如果移动的是一个带有数据库连接、HTTP 响应或日志实现的“大杂烩结构”，循环很快会回来。共享层应当足够小：它承载跨边界必须共享的语义，不承载某个具体入口的全部上下文。

让接口靠近使用方，避免用别名掩盖循环

如果 service 需要读取用户，它不必导入某个具体数据库包，也不必让数据库包导入 service 的内部类型。更稳的方式是由使用方定义最小接口，具体适配器只负责实现它。

// service 只声明自己真正需要的能力，接口靠近消费方。
package service

import "example.com/demo/internal/domain/types"

// UserReader 的方法数量越小，适配器越容易替换和测试。
type UserReader interface {
	Find(input types.FindUserInput) (types.User, error)
}

// LoadUser 依赖能力，不依赖某个数据库包。
func LoadUser(reader UserReader, id string) (types.User, error) {
	return reader.Find(types.FindUserInput{ID: id})
}

这里的接口不是为了“抽象得更高级”，而是为了阻断反向 import。也不要用类型别名把接口层的类型原封不动暴露给业务层；别名能改变名字，却不会改变依赖图。

把具体实现放到外侧，在组合根完成装配

数据库适配器可以依赖 domain/types，实现 service.UserReader 所需的方法；它不需要导入 service，只要方法集合满足接口即可。应用入口 cmd/app 负责把具体实现传给业务函数。

// adapter 只处理外部存储，返回 domain/types 定义的数据。
package adapter

import "example.com/demo/internal/domain/types"

// MemoryUsers 用内存数据模拟一个外部实现，便于说明装配方向。
type MemoryUsers struct{}

// Find 满足 service.UserReader 的方法集合，但不导入 service。
func (MemoryUsers) Find(input types.FindUserInput) (types.User, error) {
	return types.User{ID: input.ID, Name: "demo"}, nil
}

// cmd/app 是组合根：知道具体实现，也知道业务入口，但不让业务包反向依赖入口。
package main

import (
	"fmt"

	"example.com/demo/internal/adapter"
	"example.com/demo/internal/service"
)

func main() {
	// 具体实现只在这里注入，service 仍然依赖 UserReader 能力。
	user, err := service.LoadUser(adapter.MemoryUsers{}, "u-1")
	if err != nil {
		// 入口统一处理错误，业务包不需要知道输出方式。
		panic(err)
	}
	fmt.Println(user.Name)
}

用 go list 找到还有哪条边没有拆掉

重构时不要只看报错中最后出现的两个包。先从模块范围列出依赖，再回到对应目录检查 Imports 字段，通常比凭目录名猜更快。

# -e 让 go list 尽量继续处理有错误的包，便于观察剩余依赖。
go list -deps -e ./...

# -json 展开每个包的 Imports，重点查看 api、service 和 domain/types。
go list -json -e ./internal/...

go list 的输出不是修复方案，但能帮你确认拆分后的依赖方向。排查时可以按下面顺序问三个问题：

• 报错路径中是否仍有上层入口包被业务包导入？
• 共享包是否偷偷依赖了数据库、HTTP 或命令行实现？
• 接口是否放在真正使用它的包里，而不是为了“集中管理”塞进实现包？

如果只是测试包形成了环，也要单独看测试文件的包声明。外部测试包和被测包是不同的编译边界，测试辅助代码不应把生产包的依赖方向重新拉回去。

按变更单顺序收口，避免循环反复出现

我更愿意把这次修复当成一次小型迁移，而不是一次“把编译器哄开心”的移动文件操作：

1. 记录报错中的最短环路，标出每条 import 的职责。
2. 把跨包共享的纯数据移动到中立包，先删掉上层依赖。
3. 让消费方定义最小接口，具体实现放在适配器或基础设施包。
4. 在 cmd/app 或其他组合根注入实现，禁止业务包反向导入入口。
5. 用 go list -json -e 检查残留依赖，再运行包测试和整模块构建。

最终判断标准不是目录看起来“分层”了，而是新增一个入口或替换一个适配器时，不需要让核心业务包重新认识入口细节。只要依赖方向稳定，未来继续拆包才不会每次都制造新的 import cycle。

常见疑问

能不能靠 init 或延迟初始化绕过 import cycle？

不能。init 发生在包已经通过导入分析之后，无法修复编译阶段的包环。

所有共享类型都应该放进一个 common 包吗？

不建议。只把确实跨边界共享且语义稳定的类型放到中立包；否则 common 会变成新的依赖汇聚点。

接口一定要单独建一个 interfaces 包吗？

不一定。更重要的是接口靠近使用方，并且只描述使用方需要的能力。单独建包不是解除循环的必要条件。