第一步是用 go list -json -exported -deps=false ./... 提取真实导出符号，因其能稳定获取函数名、方法签名、结构体字段名和类型等唯一可信的编译器导出信息。
用 go list -json 提取真实导出符号作为比对基准
接口兼容性检查的第一步不是写代码，而是确认「什么算 API 变更」。Go 没有 ABI 定义，唯一可信的是编译器实际导出的符号——函数名、方法签名、结构体字段名和类型。直接解析源码（ast）或依赖文档注释会漏掉泛型约束、类型别名、嵌入字段等关键信息。
-
go list -json -exported -deps=false ./...是唯一能稳定提取当前模块所有可导出标识符的方式；缺-exported会丢掉 struct 字段和方法，缺-deps=false会混入第三方包符号 - 输出是 JSON 行流（每行一个对象），必须逐行解析；不能
json.Unmarshal整个响应，否则会因换行符解析失败 - 重点关注
Exported字段为true的条目，过滤掉内部类型（如unexported字段、_开头变量） - 字段类型变更（如
int→int64）和方法签名变化（参数顺序、error 类型拼写差异）必须体现在Type字段中，这是后续比对的原始依据
用 golang.org/x/tools/go/packages 解析归一化方法签名
仅靠 go list 无法判断「参数名改了但类型没变」是否影响调用——它不关心语义，只管符号存在性。真正要校验的是函数/方法的「可调用契约」：接收者类型、参数类型列表、返回类型列表、是否含 error。这必须用 packages 加载类型信息后提取 *types.Signature。
- 加载时必须设
Mode: packages.NeedName | packages.NeedTypes | packages.NeedSyntax | packages.NeedTypesInfo；漏掉任一 flag 都会导致TypesInfo缺失或签名不完整 - 遍历目标包的
pkg.TypesInfo.Defs，跳过pkg.TypesInfo.Implicits（那是编译器生成的中间符号，非 API） - 对每个函数，调用
sig.String()得到规范字符串（如func(context.Context, string) (User, error)），比对前后版本字符串是否一致——比结构体深比较更鲁棒，且天然忽略参数名 - 注意接收者类型：指针接收者
(*T).Method和值接收者T.Method在签名中体现为不同 receiver 类型，不可互换
在 CI 中强制执行 var _ Interface = (*Type)(nil) 编译期断言
接口新增方法后旧实现未补全，是运行时 panic 最常见来源。Go 编译器不会主动扫描所有实现类型，只在校验「当前代码路径中实际发生的接口转换」时检查。必须用空白赋值强制暴露问题。
- 在实现类型的同一文件末尾添加：
var _ MyInterface = (*MyType)(nil)——必须是指针类型，除非接口所有方法接收者都是值类型 - 跨包类型（如第三方 SDK 的 struct）无法修改源码时，在你的调用包里写：
var _ MyInterface = &thirdparty.Type{}，编译失败即说明不兼容 - 禁止写成
var _ MyInterface = MyType{}：若接口方法需指针接收者，值类型赋值会编译失败，但错误提示模糊（"cannot use MyType literal as MyInterface value"），易被忽略 - CI 脚本中加
go build ./...即可触发全部断言；无需额外工具，零依赖
用 buf check breaking 拦截 Protobuf wire-level 不兼容
gRPC 接口升级翻车，90% 出在 Protobuf 层。wire 兼容性不看 Go struct 标签，只认 tag 编号和 wire type。改类型（int32→int64）、删字段、复用 tag，都会让老客户端解析失败，且错误发生在二进制解码层，日志里只显示 "proto decode error"。
- 所有
.proto文件必须加// @version v1.2注释，配合buf generate输出带版本信息的 descriptor - CI 中执行
buf check breaking --against .git#branch=main，自动比对当前分支与主干的 descriptor 差异，拦截破坏性修改 - 新增字段必须设
optional（proto3）或repeated，tag 编号不能复用已reserved的编号 - 枚举值只能追加，已删除的编号绝对不可重用；否则老客户端收到未知 enum 值会 panic（不是忽略）
真正的兼容性检查不是单点工具能覆盖的：go list 看符号存不存在，packages 看签名能不能调，空白赋值看接口实不实现，buf 看 wire 数据能不能解。四者缺一不可，且必须集成进 CI——任何一项漏掉，都可能让不兼容变更悄悄上线。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
