go list -json 是兼容性检测的起点，因其直接输出模块真实导出符号（包、类型、函数、方法签名），不依赖 AST 或第三方库，避免 Go 版本升级导致解析失败，且需加 -exported 和 -deps=false 参数确保准确提取主模块符号。
为什么 go list -json 是兼容性检测的起点
Go 没有官方 ABI 兼容性检查工具，但模块版本和导出符号变化是 API 兼容性的核心依据。直接读取 go list -json 输出，能拿到当前模块所有导出的包、类型、函数名和方法签名——这是后续比对的唯一可信源。不依赖 AST 解析器或第三方库，避免因 Go 版本升级导致解析失败。
常见错误：用 go doc 或 godoc 提取文档注释来判断是否“新增/删除”，但注释不等于 API 存在性；go list -json 才反映真实编译可见符号。
- 必须加
-exported参数（Go 1.21+），否则只返回包级信息，漏掉结构体字段和方法 - 需指定
-deps=false，否则会递归列出所有依赖包，干扰主模块符号提取 - 输出是 JSON 流（每行一个 JSON 对象），需逐行解析，不能直接
json.Unmarshal整个响应
如何用 golang.org/x/tools/go/packages 提取稳定签名
仅靠 go list 不足以判断函数签名是否兼容（比如参数名改了但类型没变，不影响调用）。真正要检测的是可导出标识符的「类型签名」，包括接收者类型、参数类型、返回类型、是否带 error。这必须用 packages.Load 加载并遍历 *types.Func 和 *types.Signature。
容易踩的坑：直接用 ast.Inspect 解析源码，会误判泛型类型参数（如 T any）、类型别名（type ID string）和嵌入字段；而 types 包经过类型检查，输出的是归一化后的签名。
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 加载时设
Mode: packages.NeedName | packages.NeedTypes | packages.NeedSyntax | packages.NeedTypesInfo，缺任何一项都会丢失签名信息 - 遍历
pkg.TypesInfo.Defs而非pkg.TypesInfo.Implicits，后者包含编译器自动生成的符号（如方法集展开），不可作为 API 依据 - 对每个函数，用
sig.String()生成规范字符串（如func(string) (int, error)），再做字符串比对，比结构体深比较更鲁棒
github.com/google/go-querystring 这类库为何不能直接用于兼容性断言
很多团队试图用已知“稳定”的第三方库（如 go-querystring）做 baseline 来验证自家 SDK 是否兼容，这是危险的。这类库本身不保证导出符号稳定性，且其 struct 字段 tag（如 url:"name,omitempty"）属于运行时行为，不属于 Go 语言定义的 API 兼容范畴。
真正的兼容性断言对象只能是：可导出的包路径、类型名、函数名、方法名、接口方法签名、结构体导出字段名及类型。tag、注释、私有字段、未导出方法，全都不参与判断。
- 若用
reflect遍历 struct 字段并比对 tag，会把json:"-"和json:"id,omitempty"当作不兼容，实际不影响函数调用 - 接口兼容性只看方法签名是否可被实现，不看方法顺序；但
go list输出的接口方法是无序的，需先排序再比对 - 泛型函数（如
func Map[T, U any](...)）的签名在types.Signature.String()中含[T any]，必须保留，删掉会导致误判为不兼容
CI 中执行 go run diffapi.go v1.2.0 v1.3.0 的最小可行脚本要点
生产环境 CI 不需要完整 diff 工具链，一个 100 行以内的 diffapi.go 就够用：它从两个版本 tag 构建临时模块、分别调用 packages.Load、提取签名、按字典序排序后逐行比对，并只报告新增/删除/变更的符号路径。
关键不是功能多，而是快和稳——每次检测应控制在 3 秒内，否则阻塞 PR 流水线。这意味着必须跳过测试文件、vendor 目录、非 Go 文件，并禁用 go mod download 的网络请求（提前 go mod vendor）。
- 用
os.RemoveAll清理每次生成的tmp-*模块目录，避免残留影响下一次检测 - 比对前对两组签名做
sort.Strings，否则相同符号因遍历顺序不同被误报 - 错误退出码设为
2（而非1），让 CI 明确区分“检测失败”和“发现不兼容” - 输出格式严格为：
ADD pkg.Foo/DEL pkg.Bar/MOD pkg.Baz，方便 grep 或下游工具解析
最常被忽略的是 go.mod 中 replace 语句——如果旧版本用了 replace example.com/lib => ../lib，而新版本没写，packages.Load 会静默加载本地路径，导致 diff 结果完全失真。检测前必须确保两个版本都用 clean module proxy 拉取。
