Go 类型检查器 types2 与 go/types 的源码组织、测试约定与调试技巧

本文围绕 Go 编译器仓库中类型检查器的内部指南展开：先讲清 cmd/compile/internal/types2（编译器内置检查器）与 go/types（标准库检查器）这对"孪生"检查器的组织关系与代码生成机制，再覆盖注解式测试体系、go test -run Manual 手工调试流程，以及 Checker、operand、Typ 等核心概念和表达式类型检查的编码约定。读完后你能在修改任一检查器源码前快速定位"应该改哪里、怎么验证、如何调试"。

整体组织：两个几乎一致的类型检查器

指南原文位于 types2/README.md，src/go/types/README.md 只有一行跳转链接，把读者直接指向它，因此 types2 的 README 实际上是两套实现共同的"第一份必读文档"。它开宗明义：

• cmd/compile/internal/types2（简称 types2）：内部实现，被 go build 编译器使用；
• go/types：标准库类型检查器，其 API 必须保持严格的向后兼容。

两者的 API 高度对齐，但 go/types 需要保留一些已被 types2 移除的弃用函数。它们最本质的区别在于操作的语法树不同：

• types2 操作 cmd/compile/internal/syntax 定义的语法树；
• go/types 操作 go/ast 定义的语法树。

指南强调"两个源码库要保持高度同步，任何修改都必须同时落到两边"，并给出一条明确的开发顺序建议：通常应该先改 types2 源码，再移植 go/types 中无法生成的文件。这背后的机制是：许多 go/types 文件可以直接从 types2 对应源码自动生成，生成器由 go/types 目录下的 generate_test.go 实现，可通过 go generate 调用；生成文件顶部有清晰的注释标记，不应手工修改。

代码生成器：generate_test.go 如何保证两边同步

generate_test.go 中的 TestGenerate 就是这份同步机制的载体。它的核心流程可以从源码中直接确认：

1. 解析 types2 侧源码（srcDir = "/src/cmd/compile/internal/types2/"）；
2. 将包名中的 types2 替换为 types（file.Name.Name = strings.ReplaceAll(...)）；
3. 按 filemap 表对 AST 执行文件专属改写动作；
4. 格式化后生成带 // Code generated by "go test -run=Generate -write=all"; DO NOT EDIT. 头部的文件；
5. 与磁盘上 go/types 的对应文件做 diff——未设置 -write 时，若不一致则报"file on disk ... is stale"，设置 -write 时则实际写盘。

filemap 是一张 文件名 -> 改写动作 的映射表（见 generate_test.go 的 filemap 定义），它精确说明了"哪些 go/types 文件是从 types2 生成的、需要做哪些源码转换"。几个典型条目：

• assignments.go："cmd/compile/internal/syntax"->"go/ast" 的导入替换，syntax.Name->ast.Ident、ident.Value->ident.Name 的选择器改名，以及 poser->positioner 的标识符改名——这正对应了两种语法树位置表示的差异（types2 用 syntax.Pos/poser，go/types 用 token.Pos/token.Position）；
• operand.go：把 syntax.Pos->token.Pos、syntax.IntLit->token.INT 等语法树字面量类型全部改写为 go/token 对应物；
• universe.go 的动作 fixGlobalTypVarDecl 把全局 Typ 变量从数组改写成切片，源码注释说明了原因："in types2 we use an array for efficiency, in go/types it's a slice and we cannot change that"（types2 用数组追求效率，go/types 因 API 兼容不能改成切片）；
• 值为 nil 的条目（如 array.go、map.go、slice.go、typeset.go 等）表示文件可以"原样搬运"，只需改包名。

指南还说明：新增可生成文件，只需在 generate_test.go 的表中添加一条对应条目（必要时附注所需的源码转换）。这也意味着"这个文件能不能自动生成"是有据可查的——查 filemap 即可。

测试体系：注解源码文件 + 共享 testdata

指南的 Tests 一节描述了检查器测试的组织方式：

• 共享测试集：src/internal/types/testdata/（go/types 与 types2 共用），当前仓库中该目录包含 check/、examples/、fixedbugs/、spec/ 四个子目录；
• 本地测试：types2 下的 testdata/local/，仅用于罕见情形；当前仓库中即 types2/testdata/local/。

测试文件是 .go 源码，用注解注释描述预期错误：

func f(x int) {
    _ = x + "hello" // ERROR `cannot use "hello" (untyped string constant) as int value in binary operation`
}

规则是：对于每个 /* ERROR "msg" */（或 // ERROR "msg" 行注释形式）注释，类型检查该文件时预期在紧邻注释之前的那个语法 token 位置报告错误。两种注释的匹配语义不同：

• ERROR："msg" 字符串必须是检查器报告错误信息的子串；
• ERRORx："msg" 字符串必须是匹配报告错误的正则表达式。

另外指南约定了一条 issue 修复规范：每修复一个 issue #NNNN，应在 src/internal/types/testdata/fixedbugs/issueNNNN.go 中添加对应回归测试。当前仓库的 fixedbugs/ 目录正是这套约定的落地。

调试：manual.go 模板与 -halt / -v / -verify

指南的 Debugging 一节给出了一个非常实用的"一次性调试"工作流，其基础设施在当前仓库中可以逐一对应：

• 模板文件：types2/testdata/manual.go。它的当前内容就是一个空包，头部注释写着 "This file is tested when running go test -run Manual ... Use for one-off debugging."
• 用法：把你关注的代码填进 manual.go，然后在 types2 目录下运行 go test -run Manual，测试框架就会对该文件做类型检查。
• 三个配套调试标志：
  • -halt：在报告第一个错误处 panic 并打印堆栈；
  • -v：产生类型检查追踪输出（trace）；
  • -verify：验证 manual.go 中 ERROR 注解的正确性——也就是说你可以把 manual.go 临时当做一个注解测试文件来断言报错信息。

从 check.go 中的 Checker 结构 可以看到这些调试能力并非外挂，而是检查器状态的一部分：结构体尾部就有 // debugging 段，包含 posStack []syntax.Pos（"stack of source positions seen; used for panic tracing"，服务于 -halt 的 panic 追踪）和 indent（服务于 -v 的缩进追踪）。

常用核心概念：Checker、operand、Typ

指南用一小节列出了三个高频类型及其所在文件，结合源码可以看得更具体。

Checker（check.go）

Checker 维护类型检查一个包所需的全部状态，也是检查器方法的典型接收者。从 Checker 的完整定义 可以看到其状态大致分三层：

• 由 NewChecker 初始化、贯穿检查器生命周期的包级信息：conf *Config、pkg *Package、对象到声明信息的 objMap 等；
• 由 Files 初始化、仅在 check.Files 执行期间有效的文件级状态：files []*syntax.File、imports、delayed []action（延迟动作段，FIFO 处理）等；
• 仅在检查某个特定对象期间有效的环境（嵌入的 environment）与调试字段。

这一分层解释了指南中"typically the receiver type for typechecker methods"的说法：几乎所有类型检查方法都以 *Checker 为接收者，状态生命周期由 NewChecker 与 Files 两个入口划界。

operand（operand.go）

operand.go 中的 operand 描述一个表达式的类型与值（若有），operandMode 描述表达式的类别（常量、变量等）。它是表达式类型检查的首要返回值；若表达式类型检查失败，结果 operand 的 mode 为 invalid。这与下一节的编码约定相互印证。

Typ（universe.go）

universe.go 中的 Typ 数组提供对所有预声明基本类型的访问，Typ[Invalid] 用于表示非法类型。如前所述，fixGlobalTypVarDecl 让 go/types 侧的 Typ 成为切片而 types2 侧保持数组——这是"API 兼容压倒一切"的一个具体例子。

内部编码约定

谓词命名

predicates.go 收录常用谓词，命名统一采用 isX 形式，如 isInteger。

表达式类型检查的方法形态

指南给出了一个关键模板：对每一类表达式，通常存在一个 Checker 方法负责其类型检查（例如 Checker.unary 检查一元表达式），基本形态为：

func (check *Checker) f(x *operand, e syntax.Expr, /* additional arguments, if any */)

语义要点：

• 表达式 e 的检查结果通过 operand x 返回（x 有时同时充当传入参数）；
• 若检查出错，函数 f 会报告错误并尽最大努力继续检查，但可能返回 invalid 的 operand（x.mode == invalid）；
• 调用方可能需要显式检查 operand 是否 invalid。

这条"报告错误 + 尽力继续 + 以 invalid 为信号"的约定，正是注解测试（ERROR/ERRORx）能够稳定工作的基础：检查器不会因为第一处错误就中断，错误位置与消息都可被断言。

小结：修改类型检查器前的检查清单

把指南的约定浓缩成一份可操作清单：

1. 修改前先读 types2/README.md；
2. 判断目标文件是否在 generate_test.go 的 filemap 中——在表中则优先改 types2 后用生成器同步 go/types；不在表中则两边手工同步修改；
3. 在 src/internal/types/testdata/check/ 下添加或更新注解测试（ERROR/ERRORx），修复 issue 时补 fixedbugs/issueNNNN.go 回归测试；
4. 本地快速验证用 go test -run Manual 加 manual.go 模板，配合 -halt（首个错误处断栈）、-v（检查过程追踪）、-verify（校验 ERROR 注解）；
5. 遵循既有约定：结果通过 *operand 返回、错误时 mode 为 invalid、谓词命名 isX。

这套"双实现 + 代码生成 + 注解测试 + 手工调试模板"的组合，让编译器内部检查器（可激进演进）与标准库检查器（必须兼容）在共享绝大部分逻辑的同时各自满足约束，是理解 Go 类型检查器源码演进方式的一把钥匙。