Go 联合约束项换顺序后怎样比较类型是否等价

我在给 Go 泛型约束做缓存键时，遇到过一个很容易误判的情况：同一组联合约束只是把项换了位置，String() 打出来的文本变了，缓存却被当成了两个类型。后来我把“展示文本”和“类型身份”拆开，结论很明确：如果要判断两个 go/types.Union 是否等价，应使用 types.Identical；不要把联合项的顺序直接当成类型身份。

官方地址：https://pkg.go.dev/go/types#Union

联合项换顺序后，String() 可能不同，但只要两组项描述的是同一个类型集合，types.Identical 就按语义判断它们等价。需要记录日志或生成可读文本时，再单独处理顺序。

先保护“类型身份”，再处理展示文本

这里有两个不同的资产。第一个是类型身份：它决定两个约束是否能复用分析结果、是否应该命中同一个缓存。第二个是展示文本：它服务于日志、诊断和人工阅读。把两者混为一谈，就是这类代码最常见的风险。

Go 语言规范把联合项定义为类型集合的并集；项的书写位置不是集合本身。go/types 的 Union API 则把语法项暴露出来，供工具读取和展示。比较时应让比较函数负责语义，让字符串负责可读性。

为什么换顺序仍然可能等价

联合约束可以把具体类型项或带 ~ 的项放在一起。例如下面两组项的排列不同，但它们表达的集合相同：

// 两组 Union 只改变语法项顺序，语义都覆盖 ~int 和 string。
left := types.NewUnion([]*types.Term{
	types.NewTerm(true, types.Typ[types.Int]),    // 覆盖底层类型为 int 的类型
	types.NewTerm(false, types.Typ[types.String]), // 只覆盖 string
})

right := types.NewUnion([]*types.Term{
	types.NewTerm(false, types.Typ[types.String]), // 把 string 放到前面
	types.NewTerm(true, types.Typ[types.Int]),     // 把 ~int 放到后面
})

Union 的项列表是语法表示，types.Identical 比较的却不是两个列表的下标。Go 官方实现会把联合项转换成类型集合，再通过集合关系判断两边是否相同，因此换序不会自动造成类型不等价。

真正的判定入口是 types.Identical

对工具代码来说，最小的比较函数可以只有一行。它的好处是把类型系统的细节交给 go/types，调用方不用自己实现“逐项查找、处理 ~、判断集合包含关系”的重复逻辑。

// sameUnion 只负责语义等价，不把展示顺序混进判定。
func sameUnion(left, right *types.Union) bool {
	return types.Identical(left, right)
}

// compareAndDescribe 同时返回语义结论和便于日志阅读的原始文本。
func compareAndDescribe(left, right *types.Union) (bool, string, string) {
	return sameUnion(left, right), left.String(), right.String()
}

这里故意保留两个返回字符串。日志里可以看到“原顺序”和“换顺序”的差别，但缓存命中、重复定义消除或结构比较应使用第一个布尔值。不要为了让日志看起来一致，就把字符串排序后再反过来替代 Identical。

需要注意的是，types.Identical 的文档要求参与比较的类型属于一致的符号集合。工具在加载多个包时，应复用同一个 importer 和包符号环境；否则即使名称和文本一样，命名类型也可能不是同一个声明来源。

遇到 ~ 时，比较 Tilde 和 Type 的组合

我第一次写诊断输出时只读取了 Term.Type()，结果把 int 和 ~int 打成了相同的“类型名”。这会把约束范围扩大或缩小，是比顺序误判更危险的错误。

// describeTerm 同时保留是否带 ~ 和具体类型，避免丢失约束范围。
func describeTerm(term *types.Term) string {
	if term == nil {
		return ""
	}

	name := types.TypeString(term.Type(), nil)
	if term.Tilde() {
		// ~ 表示匹配底层类型相同的一组类型，不等于只匹配 name。
		return "~" + name
	}
	return name
}

// describeUnion 只用于日志或诊断，不把它的结果当作类型身份。
func describeUnion(union *types.Union) []string {
	items := make([]string, 0, union.Len())
	for i := 0; i 

这段读取逻辑只回答“第几个项长什么样”。它不能替代等价比较，因为类型集合可能有规范化关系，而字符串只是当前对象的可读写法。对比时用 types.Identical，记录时再调用 describeUnion。

日志和缓存键要分开设计

如果目标是日志，保留输入顺序通常更有帮助：开发者能看出源码或解析器原本给出了什么。如果目标是缓存键，则需要一个稳定、明确的语义策略。最稳妥的选择是直接把类型对象放在比较层，用 types.Identical 决定是否复用；不要先把 String() 拼接成键，再假定字符串相等就代表类型相等。

// unionCacheEntry 将语义比较和展示信息分开保存。
type unionCacheEntry struct {
	union *types.Union // 语义对象，命中判断交给 types.Identical
	text  string       // 展示文本，保留解析时的项顺序
}

// findEquivalent 不依赖 String() 的排列顺序寻找等价 Union。
func findEquivalent(entries []unionCacheEntry, target *types.Union) (string, bool) {
	for _, entry := range entries {
		if types.Identical(entry.union, target) {
			return entry.text, true
		}
	}
	return "", false
}

如果系统必须把结果持久化为跨进程键，应先明确符号环境、别名和命名类型的生命周期，再设计自己的规范化格式。文章这里不把“对每个项排序”包装成通用答案，因为它只能解决展示顺序，不能自动覆盖所有类型集合语义。

几个容易踩到的风险边界

• 空 Union：types.NewUnion 不接受空项列表；联合约束的空形态不是合法的语法输入，工具应在构造前处理缺失数据。
• 重叠项：Go 泛型接口的非接口项需要满足类型集合两两不相交。像 ~int | MyInt 这样的组合会触碰重叠限制，不能拿“换序等价”掩盖原始定义无效。
• 展示顺序：String() 适合诊断，不能作为等价判定；如果日志需要稳定排序，也应明确标注那是展示键。
• 符号一致性：跨包比较时，导入器和包对象必须来自一致的符号集合；仅比较同名字符串会漏掉声明来源差异。
• 约束使用范围：包含一般类型项的接口只能作为类型约束或嵌套约束使用，不能把它当作普通值类型来声明变量。

复查清单：我现在会这样检查

1. 等价性判断是否统一调用 types.Identical，而不是比较 String() 或逐项下标。
2. 诊断输出是否同时保留 Term.Tilde() 和 Term.Type()，没有把 ~T 简化成 T。
3. 缓存是否把语义对象与可读文本分开，避免换序导致重复缓存，或排序导致日志失去来源信息。
4. 构造 Union 前是否处理空项、无效项和重叠项，比较前是否保持一致的包和 importer 环境。

这次排查给我的经验是：类型工具里的“长得一样”“打印一样”和“语义相同”是三件事。联合约束换顺序时，先用 types.Identical 保护类型身份，再用 Term 和 String() 服务日志，代码会更稳定，也更容易解释。

相关问题

Union 的 Term(i) 顺序会被 go/types 自动排序吗？ 不应把它当成排序 API；它用于读取联合项，展示通常保留构造或解析时的顺序。

只比较每个 Term.Type() 可以吗？ 不可以，还要处理 Term.Tilde()；~T 和 T 的类型集合含义不同。

两个接口的联合约束都能用 Identical 比较吗？ 应先区分比较对象是 Union 还是 Interface，并保证类型来自一致的符号集合；接口的类型集合还可能包含方法和嵌入关系。