反射缓存按 Type 还是类型名称做键更可靠

在同一个 Go 进程里，反射缓存优先用 reflect.Type 直接做键，比类型名称可靠。官方文档明确说明：reflect.Type 值可比较，可以作为 map 键；两个 Type 相等，表示它们代表同一类型。相反，Type.String() 可能使用缩短后的包名，并不保证在所有类型之间唯一。

Go reflect 官方文档：https://pkg.go.dev/reflect

进程内缓存用 reflect.Type 表达类型身份；日志可以打印名称；跨进程持久化则另设稳定的业务模式键。不要让一种字符串同时承担三种职责。

影响面：同名结构体拿到了另一份字段计划

这个问题通常藏得很深。最初缓存能够命中，性能数据也很好看，但某个新包接入后，编码器突然读错字段，或者校验器报告了根本不存在的标签。继续追查会发现，两个不同导入路径的包恰好使用了相同包名和类型名，缓存又按 t.String() 保存，于是后注册的类型复用了先注册类型的元数据。

func cacheKey(t reflect.Type) string {
	// 反例：String 适合诊断展示，但官方文档不保证它在类型之间唯一。
	return t.String()
}

这种错误比普通缓存未命中更危险。未命中只会多做一次反射；错误命中却会返回“看似结构正确、实际属于另一个类型”的计划。若缓存内容是字段索引、序列化函数或校验规则，后续可能出现错误取值甚至反射 panic。

时间线：名称键为什么开始时看不出问题

项目早期只有少量内部结构体，String() 打印出来的内容直观，测试也没有同名包。后来代码拆成多个模块，包路径变长，但团队仍倾向于使用相同的简短包名，例如 model、types、entity。此时名称键的碰撞空间迅速扩大，问题才从理论风险变成真实故障。

还有一类延迟触发来自匿名和复合类型。Name() 只对定义类型返回包内名称；指针、切片、匿名结构体等非定义类型会返回空字符串。若代码在名称为空时只做一个默认值，多个完全不同的复合类型会直接落到同一缓存槽。

根因：名称是展示文本，不是完整类型身份

reflect.Type 提供了几种看起来都能“描述类型”的信息，但用途不同：

把 PkgPath() 与 Name() 拼起来，对定义类型比单独使用名称稳妥，但它仍不是所有类型的通用键。指针、切片、映射、匿名结构体和函数类型需要递归描述组成部分；一旦自己实现这套规则，就等于重新实现一部分类型身份系统。

修复：进程内缓存直接使用 reflect.Type

最小修复就是把 map 的键类型改为 reflect.Type。下面的缓存保存结构体字段计划；构建函数只会在真正未命中时运行：

type FieldPlan struct {
	Indexes []int
}

type PlanCache struct {
	mu   sync.RWMutex
	data map[reflect.Type]*FieldPlan
}

func (c *PlanCache) LoadOrBuild(
	t reflect.Type,
	build func(reflect.Type) (*FieldPlan, error),
) (*FieldPlan, error) {
	if t == nil {
		return nil, fmt.Errorf("不能为 nil 类型构建字段计划")
	}

	c.mu.RLock()
	plan, ok := c.data[t]
	c.mu.RUnlock()
	if ok {
		return plan, nil
	}

	// 未命中时先构建，再在写锁内复查，避免并发覆盖已完成结果。
	built, err := build(t)
	if err != nil {
		return nil, err
	}

	c.mu.Lock()
	defer c.mu.Unlock()
	if plan, ok = c.data[t]; ok {
		return plan, nil
	}
	if c.data == nil {
		c.data = make(map[reflect.Type]*FieldPlan)
	}
	c.data[t] = built
	return built, nil
}

这里的关键不是锁写法，而是 map[reflect.Type]。定义类型、匿名结构体、切片、指针以及不同泛型实例都会按 Go 的类型身份规则自然区分，不需要手工拼字符串。类型别名则与它指向的类型保持同一身份，这也符合语言规范。

修复：先定义缓存语义，再决定是否解引用

“用 Type 做键”仍有一个必须明确的选择：T 和 *T 要不要共享缓存？答案取决于缓存内容，而不是取决于哪种写法更省空间。

如果缓存只描述结构体字段，例如字段标签、索引路径和 JSON 名称，那么可以先把多层指针解到元素类型，再缓存字段计划。这样 User 与 *User 可以共享结果：

func structType(t reflect.Type) (reflect.Type, error) {
	if t == nil {
		return nil, fmt.Errorf("类型不能为空")
	}
	// 字段元数据与指针层数无关，因此显式解引用。
	for t.Kind() == reflect.Pointer {
		t = t.Elem()
	}
	if t.Kind() != reflect.Struct {
		return nil, fmt.Errorf("要求结构体类型，实际为 %s", t)
	}
	return t, nil
}

但如果缓存描述方法集合、接口实现关系或可调用函数，就不能随便解引用。Go 的方法集合区分值类型和指针类型，*T 可能拥有 T 没有的方法。此时必须保留原始 reflect.Type，让两个缓存条目独立存在。

跨进程场景不要序列化 reflect.Type

reflect.Type 适合作为当前进程内的内存键，但它不是要写入 Redis、数据库或磁盘的业务 ID。跨进程缓存必须考虑程序版本、字段变更、泛型参数以及失效策略。更可靠的做法是由业务明确提供模式名称和版本，例如 customer-profile:v3，并把它与当前 reflect.Type 的构建结果绑定。

type SchemaKey struct {
	Name    string
	Version uint32
}

type CacheEntry struct {
	// Type 只在当前进程内用于二次确认，Key 才是外部稳定标识。
	Type reflect.Type
	Key  SchemaKey
	Plan *FieldPlan
}

外部模式键不是自动生成得越长越好，而是要能跟随兼容性策略升级。字段含义变化时递增版本，旧条目自然失效；进程内仍用 reflect.Type 防止错误类型复用同一计划。两层键承担不同职责，维护起来反而更简单。

防复发：测试要覆盖碰撞与归一化

只测一次命中和一次未命中不够。至少要覆盖下面几组边界：

• 两个不同包中的同名定义类型不能共用条目；
• 匿名结构体即使字段很相似，也必须遵循精确类型身份；
• 不同泛型实例如 Box[int] 与 Box[string] 要分开；
• 字段缓存应验证 T 与 *T 是否按预期共享；
• 方法缓存应验证指针和值类型是否按预期分离；
• nil 类型不能进入缓存构建器；
• 外部模式键版本变化后，旧条目不能继续命中。

几个常见追问

PkgPath 加 Name 能不能代替 reflect.Type？

只处理定义类型时可以作为可读标识，但它覆盖不了所有复合类型。进程内既然可以直接用 reflect.Type，通常没有必要自己拼接。

sync.Map 的键可以直接放 reflect.Type 吗？

可以。reflect.Type 值可比较，既能用于普通 map，也能作为 sync.Map 的键。是否使用 sync.Map 应由访问模式决定，而不是由键类型决定。

为什么不统一把指针都 Elem 掉？

因为字段布局与方法集合的语义不同。字段元数据通常可以归一化，方法和接口能力却可能依赖指针接收者。归一化必须写在缓存契约里，不能作为通用习惯。

Type.String 还有什么用途？

它非常适合日志、错误信息和调试输出，只是不该被误当成保证唯一的身份。缓存报错时同时输出 String()、PkgPath() 和业务模式键，往往更容易定位问题。

这次复盘后的结论很简单：在一个进程里，Go 已经用 reflect.Type 提供了完整类型身份，就不要退回到信息更少的字符串。先确定缓存到底描述字段、方法还是外部模式，再决定是否归一化和是否需要稳定版本键，反射缓存才能同时获得正确性与可维护性。