Go typeutil.Map 怎样使用类型对象作为键

在做 Go 静态分析、代码索引或类型聚合时，经常要把 go/types 产出的 types.Type 作为键。此时不要把类型对象直接塞进普通 map[types.Type]any，也不要用指针地址判断两个类型是否相同。typeutil.Map 已经把类型的等价关系封装好了：用 Set 写入、用 At 读取，并能把类型相同但对象指针不同的结果聚合到同一项。

官方地址：https://pkg.go.dev/golang.org/x/tools/go/types/typeutil#Map

最小用法是声明一个 typeutil.Map，把类型检查结果中的 types.Type 传给 Set 和 At。真正的关键不在 API 数量，而在于它按 Go 类型的等价规则处理键，而不是按类型对象的指针地址处理键。

先明确 typeutil.Map 解决的键问题

types.Type 是接口，具体实现通常是指针。两个不同的类型对象可能表示同一个 Go 类型，所以直接比较接口背后的指针并不能表达“类型相同”。官方文档把 typeutil.Map 定义为从 types.Type 到任意值的哈希映射，并明确说明它使用类型等价关系来处理这个问题。

例如源码中分别声明两个 []string 变量，类型检查阶段可能得到两个不同的对象；从业务角度看，它们都应归到 []string 这一组。typeutil.Map 适合做这种“类型作为身份、任意值作为聚合结果”的索引。

从类型检查结果取得类型对象

实际使用时，键通常来自 go/types 的类型检查结果。下面的示例创建一段内存源码，检查包级对象，然后取出每个对象的 Type()。示例只演示数据关系，不需要把类型名称手工转换成字符串。

package main

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

func checkedPackage() (*types.Package, error) {
	const source = `package sample

var Names []string
var Aliases []string
func Load(id int) (string, error)
func Find(id int) (string, error)
`

	// 解析源码只负责生成 AST，不会自动给对象补上类型信息。
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "sample.go", source, 0)
	if err != nil {
		return nil, err
	}

	// Check 之后才能从包作用域对象上取得可用于 typeutil.Map 的 types.Type。
	return new(types.Config).Check("sample", fset, []*ast.File{file}, nil)
}

func main() {
	pkg, err := checkedPackage()
	if err != nil {
		panic(err)
	}
	for _, name := range pkg.Scope().Names() {
		obj := pkg.Scope().Lookup(name)
		fmt.Printf("%s: %s\n", name, obj.Type())
	}
}

这里要区分两个阶段：parser.ParseFile 只产生语法树，types.Config.Check 才建立对象和类型之间的关系。后续传给 typeutil.Map 的键，就是 pkg.Scope().Lookup(name).Type() 返回的接口值。

用 Set 和 At 建立类型到值的映射

把类型对象交给 Set 后，值可以是字符串、结构体、切片或其他任意对象。下面把包级对象名称按类型归组：同为 []string 的名称会共享一个切片，同为 func(int) (string, error) 的函数也会落在同一项。

真正可运行的核心写法如下，直接使用 *types.Scope，并把读取和写回放在同一个循环里：

func groupNames(scope *types.Scope) map[string][]string {
	var namesByType typeutil.Map

	for _, name := range scope.Names() {
		// Type 是键；切片是该类型对应的聚合值。
		typ := scope.Lookup(name).Type()
		names, _ := namesByType.At(typ).([]string)
		names = append(names, name)
		namesByType.Set(typ, names)
	}

	result := make(map[string][]string)
	namesByType.Iterate(func(typ types.Type, value any) {
		// String 只作为展示键，不能反过来替代 types.Type 身份。
		result[typ.String()] = append([]string(nil), value.([]string)...)
	})
	return result
}

如果业务需要在同一类型上累计多个字段，可以把 []string 换成自定义结构体。Set 会返回该键之前保存的值，适合在更新时记录旧值；At 找不到条目时返回 nil，因此读取聚合值时要做类型断言检查。

处理遍历、替换和并发边界

typeutil.Map 的零值可以直接使用，甚至空的 *Map 也被文档视为有效空映射。Iterate 的遍历顺序未定义，所以需要稳定输出时，应在回调中收集数据，再按字符串或业务字段排序。

官方文档还给出了一个重要边界：只读操作，例如 At 和 Len，可以安全并发调用；这不等于写入操作可以和读取操作无锁并发。若多个 goroutine 会调用 Set、Delete 或在遍历期间修改映射，应在外层加锁，或为每个阶段建立独立的映射。

type TypeIndex struct {
	mu sync.RWMutex
	m  typeutil.Map
}

func (idx *TypeIndex) Put(typ types.Type, value any) {
	idx.mu.Lock()
	defer idx.mu.Unlock() // 写入完成后释放锁，避免把锁带出方法。
	idx.m.Set(typ, value)
}

func (idx *TypeIndex) Get(typ types.Type) any {
	idx.mu.RLock()
	defer idx.mu.RUnlock() // 读锁只保护本次查找，不把返回值的后续使用纳入锁内。
	return idx.m.At(typ)
}

如果索引只在类型检查完成后构建、之后只读，那么可以利用只读并发语义；如果映射承载的是可变切片或结构体，还要单独考虑值本身的并发安全。

几个容易踩到的误区

什么时候该选 typeutil.Map

当键来自 go/types、你关心的是类型等价而不是名称文本，并且值需要按类型聚合时，typeutil.Map 是直接的选择。典型场景包括静态分析中的类型统计、同类型声明归组、方法集缓存的外围索引和代码生成前的类型元数据收集。

如果键只是用户输入的字符串、稳定的 ID 或业务枚举，仍然使用普通 map 更清楚；如果你需要跨进程持久化，也应先把类型转换成经过设计的稳定标识，而不是直接序列化 types.Type 对象。

相关问题

• typeutil.Map 的 At 找不到键时返回什么？返回 nil，读取聚合切片或结构体时应检查断言结果。
• Iterate 能否在回调里删除条目？可以遵循 Go map 的相应边界，但插入条目是否在本轮被访问未定义。
• 为什么不直接使用 Hasher？SetHasher 当前没有效果，官方文档建议新代码不要使用这组遗留优化接口。