Go 联合约束项重叠时怎样读取类型检查错误

我之前调试带联合约束的泛型代码时，好几次遇到约束项重叠触发类型检查报错，默认打印的错误信息只提示有冲突，连具体位置、哪两个约束重了都不显示，折腾了很久才找到正确的读取错误的方式。碰到这类问题，你不用硬翻AST源码找线索，通过go/types标准库暴露的扩展接口，就能完整拿到重叠约束对应的源码位置、冲突的接口方法详情。

我第一次用 go/types 分析泛型约束时，最容易误判的一点是：看到联合约束报错，就马上去找 types.Union 的 Term。其实这两件事在不同层次。Config.Check 和 Config.Error 负责告诉你源码哪里不合法，Union 的方法只负责读取已经形成的联合结构。

遇到 int 与 ~int 这种覆盖范围重叠的联合项，实用做法是先让检查器产生诊断，再从 types.Error 读取位置和消息；只有检查对象本身有效并且确实拿到了联合类型，才去遍历它的项。

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

我会先把“重叠”与“读取 Union”分开

泛型约束里的联合项描述的是类型集合。int 只表示精确的预声明类型，而 ~int 表示底层类型为 int 的类型集合，因此前者已经落在后者里面。把两者放在同一个联合约束中，集合描述就出现了重叠，源码检查阶段会拒绝它。

这里有一个很重要的排障顺序：

先用 Config.Check 取得首个类型检查错误

如果你的工具只需要给用户一个最先出现的问题，零值 types.Config 就够用。下面的代码把一段源码解析成 AST，再交给检查器。示例里的联合约束故意包含重叠项，重点是读取错误，不是构造一个可通过检查的约束。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
	"go/types"
)

func main() {
	const source = `package demo

type Number interface {
	int | ~int
}`

	// FileSet 负责把类型检查器的位置转换成文件名、行号和列号。
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "constraint.go", source, 0)
	if err != nil {
		fmt.Println("解析失败:", err)
		return
	}

	// 没有设置 Config.Error 时，Check 返回遇到的首个类型检查错误。
	conf := types.Config{}
	_, err = conf.Check("demo", fset, []*ast.File{file}, nil)
	if err != nil {
		fmt.Println("类型检查失败:", err)
	}
}

上面的片段要补上 go/ast 导入，因为 Check 接收的是 []*ast.File。完整可复制版本如下；我把导入写全，避免把 API 关系藏在省略号里。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
	"go/types"
)

func main() {
	const source = `package demo

type Number interface {
	int | ~int
}`

	// 位置集合与 AST 共用，错误中的 Pos 才能还原到源码坐标。
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "constraint.go", source, 0)
	if err != nil {
		fmt.Println("解析失败:", err)
		return
	}

	// Check 返回包对象和首个错误；包可能是不完整的，不能把它当成完全通过。
	conf := types.Config{}
	_, err = conf.Check("demo", fset, []*ast.File{file}, nil)
	if err != nil {
		fmt.Println("类型检查失败:", err)
	}
}

types.Config.Check 的返回错误本身已经实现了 error 接口。打印 err.Error() 可以快速看到类似“文件名:行:列: overlapping terms ...”的诊断，但如果要做编辑器标注、JSON 返回或按行聚合，下一步应该把它还原成 types.Error。

用 types.Error 读取文件、行列和消息

types.Error 不是只有一段字符串。它带有产生位置的 Fset 和 Pos，还有错误正文 Msg 与是否为 soft error 的 Soft。位置转换交给 Fset.Position，不要自己把 token 偏移量当成行号。

func printTypeError(err error) {
	// 官方类型检查错误通常以 types.Error 作为动态类型返回。
	typeErr, ok := err.(types.Error)
	if !ok {
		fmt.Println("普通错误:", err)
		return
	}

	// Position 会把 Pos 解析成文件名、行、列和偏移量。
	pos := typeErr.Fset.Position(typeErr.Pos)
	fmt.Printf("%s:%d:%d: %s\\n", pos.Filename, pos.Line, pos.Column, typeErr.Msg)
	if typeErr.Soft {
		fmt.Println("这是 soft error，检查器仍可能保留部分结果")
	}
}

如果你的工具要兼容可能包装错误的调用链，可以使用 errors.As 找 types.Error；但不要为了“看起来更通用”而吞掉类型不匹配。无法识别的错误仍应保留原文返回给调用方。

func errorSummary(err error) string {
	var typeErr types.Error
	if errors.As(err, &typeErr) {
		// 位置字段适合转成编辑器诊断，Msg 适合展示给用户。
		pos := typeErr.Fset.Position(typeErr.Pos)
		return fmt.Sprintf("%s:%d:%d: %s", pos.Filename, pos.Line, pos.Column, typeErr.Msg)
	}
	return err.Error()
}

真正的代码需要在导入区加入 errors。这里的关键不是把错误字符串拆分，而是保留结构化位置：文件名可能不是固定名称，列号也不应通过字符串查找猜测。

需要全部诊断时设置 Config.Error

Check 默认在首个错误处返回。如果是批量分析、编辑器提示或测试工具，通常希望一次收集多条错误，这时给 Config.Error 设置回调。官方 API 说明该回调会收到类型检查期间发现的每条错误；其中后续错误的消息可能以制表符开头，表示它是关联的次级诊断。

func collectDiagnostics(fset *token.FileSet, files []*ast.File) []types.Error {
	var diagnostics []types.Error
	conf := types.Config{
		Error: func(err error) {
			// 回调里的错误仍保留 types.Error 的位置与消息字段。
			if typeErr, ok := err.(types.Error); ok {
				diagnostics = append(diagnostics, typeErr)
				return
			}
			// 非标准错误也要保留，实际项目可放入统一诊断结构。
			fmt.Println("未结构化错误:", err)
		},
	}

	// 即使设置了回调，Check 仍会返回首个错误；不要重复当成第二条诊断。
	_, firstErr := conf.Check("demo", fset, files, nil)
	if firstErr != nil && len(diagnostics) == 0 {
		fmt.Println("没有收集到结构化诊断:", firstErr)
	}
	return diagnostics
}

这里的取舍很实际：Check 的返回值适合控制“这次检查是否失败”，Error 回调适合累积“用户应该看到哪些位置”。如果把两者都无条件 append，首个错误可能被记录两次。

Union.Len、Term 和 Terms 只负责读联合结构

当类型检查成功并且你从类型信息中拿到一个接口约束时，才适合把底层类型断言为 *types.Union。Len 和 Term 是兼容旧版本的索引式读取方式；较新的 Go 版本还提供 Terms 迭代器。它们回答的是“结构里有哪些项”，不是“为什么检查失败”。

func dumpUnion(t types.Type) {
	// 只有底层类型确实是 Union 时才进入联合项读取逻辑。
	union, ok := t.Underlying().(*types.Union)
	if !ok {
		fmt.Println("这不是联合类型:", t)
		return
	}

	// Len/Term 适合需要兼容较早 Go 版本的工具。
	for i := 0; i 

如果目标工具明确使用提供 Terms 的 Go 版本，也可以按迭代器写法遍历。但无论采用哪种方式，都要把这段逻辑放在“已获得类型对象”之后；重叠错误发生在检查阶段，不能期待一个未通过检查的联合约束自动变成完整、可靠的 Union。

我会按这个顺序处理真实项目

1. 先保留源码位置。解析时使用同一个 token.FileSet，把它传给 AST 和 types.Config.Check，这样错误位置不会丢。
2. 先决定诊断粒度。命令行快速失败用返回值；编辑器或批量检查用 Config.Error 收集全部条目。
3. 结构化读取错误。优先读取 types.Error 的 Fset、Pos、Msg、Soft，不要用正则拆 Error() 字符串。
4. 再读取联合项。只有拿到有效类型对象后，才使用 Union.Len、Term 或 Terms 分析约束内容。
5. 记录兼容边界。若工具需要支持旧 Go 版本，优先保留 Len 与 Term 路径；若只支持新版本，再采用 Terms 迭代器。

这样处理后，“联合项重叠”会落在类型检查诊断层，“联合里有哪些项”会落在类型结构层。两个问题都能回答，但不需要拿一个 API 去承担另一个 API 的职责。

常见追问

为什么我拿到的 Check 错误只有一条？

这是默认行为。没有设置 Config.Error 时，检查器返回首个错误；需要更多条目就设置回调并在回调里保存结构化诊断。

Union.Term 能判断联合项为什么重叠吗？

不能。它只能读取联合对象中的项；重叠是否合法属于类型检查规则，应读取 types.Error 的位置和消息。

为什么要保留 Soft 字段？

因为工具可能需要区分“仍可生成部分结果的软错误”和可能让结果不可靠的硬错误。是否继续处理，应由调用方根据工具目标决定。

Term 和 Terms 应该选哪个？

需要兼容较早 Go 版本时使用 Len 加 Term；项目版本明确较新时可以使用 Terms，但它仍然只是联合项遍历接口。

官方资料

go/types Union：https://pkg.go.dev/go/types#Union

Config.Check 与 Error：https://pkg.go.dev/go/types#Config.Check

Go 泛型接口约束规范：https://go.dev/ref/spec#General_interfaces