用 unique.Handle 为不可比较结构生成稳定句柄

配置去重、规则缓存和对象索引经常遇到同一个障碍：业务对象里有 []string 或 map[string]string，因此整个结构体不可比较，既不能直接作为 map 的键，也不能直接传给要求 comparable 的 unique.Make。真正需要解决的不是“怎么绕过类型系统”，而是先把业务上的相等关系写成一个确定、无歧义的规范键，再让 unique.Handle 负责规范化与低成本比较。

场景：不可比较配置需要稳定身份

假设网关里有一份路由策略。策略名、允许的方法集合和标签共同决定身份，但切片和映射让它无法使用 ==。

package policy

type RoutePolicy struct {
	Name    string
	Methods []string
	Labels  map[string]string
}

// 这段代码无法编译：RoutePolicy 含有不可比较字段。
// var index map[RoutePolicy]int

使用指针地址也不合适。两次解析得到的对象即使内容完全相同，地址仍然不同；反过来，同一个对象被修改后地址不变，内容身份却已经改变。稳定句柄必须来自内容语义，而不是内存位置。

先固定“相同”的业务规则

编码之前先写清楚等价规则，否则再稳定的编码也只是稳定地放大歧义。本例采用以下约定：

• Name 原样参与身份，大小写不同视为不同策略。
• Methods 被视为集合，顺序不重要，因此编码前复制、排序；调用方原切片不能被修改。
• Labels 的遍历顺序不参与身份，必须按键排序后编码。
• nil 与空集合在本业务中等价，都编码为零个元素。

如果你的业务认为方法顺序有意义，就不要排序；如果必须区分 nil 和空集合，则应加入独立标记。规范键没有通用答案，它必须忠实表达当前领域的“相同”。

用长度前缀编码生成规范键

直接用逗号拼接并不安全，因为字段本身可能包含逗号。JSON 虽然方便，但还要明确映射排序、缺省字段与版本演进规则。这里采用简单的长度前缀编码：每段写成“字节长度、冒号、内容”，因此即使内容含分隔符也不会产生歧义。

package policy

import (
	"sort"
	"strconv"
	"strings"
)

// appendPart 使用长度前缀写入一段，避免分隔符碰撞。
func appendPart(b *strings.Builder, value string) {
	b.WriteString(strconv.Itoa(len(value)))
	b.WriteByte(':')
	b.WriteString(value)
}

// CanonicalKey 按固定规则为 RoutePolicy 生成确定的字符串键。
func CanonicalKey(p RoutePolicy) string {
	var b strings.Builder

	// 版本前缀用于未来升级编码规则。
	appendPart(&b, "route-policy/v1")
	appendPart(&b, p.Name)

	// 复制后排序，既保持集合语义，也不改动调用方切片。
	methods := append([]string(nil), p.Methods...)
	sort.Strings(methods)
	b.WriteString(strconv.Itoa(len(methods)))
	b.WriteByte(';')
	for _, method := range methods {
		appendPart(&b, method)
	}

	// Go 的 map 遍历顺序不稳定，先排序键再编码键值对。
	keys := make([]string, 0, len(p.Labels))
	for key := range p.Labels {
		keys = append(keys, key)
	}
	sort.Strings(keys)
	b.WriteString(strconv.Itoa(len(keys)))
	b.WriteByte(';')
	for _, key := range keys {
		appendPart(&b, key)
		appendPart(&b, p.Labels[key])
	}

	return b.String()
}

这里的关键不是字符串长什么样，而是同一语义永远产生同一键，不同的字段序列不能因为分隔符巧合而合并。长度前缀比“字段之间加一个不常见字符”更稳妥。

把规范键交给 unique.Handle

Go 1.23 引入的 unique 包可以规范化可比较值。unique.Make 的类型参数必须满足 comparable，所以我们不传原结构，而是传刚生成的字符串键。

package policy

import "unique"

// StableHandle 把业务规范键转换成可低成本比较的句柄。
func StableHandle(p RoutePolicy) unique.Handle[string] {
	return unique.Make(CanonicalKey(p))
}

// SamePolicy 按既定业务语义判断两份策略是否相同。
func SamePolicy(a, b RoutePolicy) bool {
	return StableHandle(a) == StableHandle(b)
}

两个句柄相等，当且仅当传入 unique.Make 的值相等。句柄比较便宜，而且 Make 可并发调用。需要注意的是，句柄稳定的是当前进程内的内容身份；它不是跨进程、跨版本持久化的整数 ID。

保留原始载荷，句柄只负责身份

Handle[string] 适合做索引键，不应取代完整业务对象。原始载荷仍由存储层保存，句柄只表达规范化身份，这样查询快、职责也清楚。

package policy

import (
	"sync"
	"unique"
)

type PolicyStore struct {
	mu   sync.RWMutex
	byID map[unique.Handle[string]]RoutePolicy
}

// NewPolicyStore 初始化按稳定句柄索引的存储。
func NewPolicyStore() *PolicyStore {
	return &PolicyStore{byID: make(map[unique.Handle[string]]RoutePolicy)}
}

// Put 保存原始载荷，并返回它的稳定句柄。
func (s *PolicyStore) Put(p RoutePolicy) unique.Handle[string] {
	h := StableHandle(p)
	s.mu.Lock()
	s.byID[h] = p
	s.mu.Unlock()
	return h
}

// Get 根据句柄读取业务对象；返回值仍是完整 RoutePolicy。
func (s *PolicyStore) Get(h unique.Handle[string]) (RoutePolicy, bool) {
	s.mu.RLock()
	p, ok := s.byID[h]
	s.mu.RUnlock()
	return p, ok
}

上例的锁保护业务映射；unique.Make 本身可以并发调用，但这并不会自动让你自己的 map 线程安全。还要留意浅拷贝语义：示例直接保存了含切片与映射的结构，如需防止外部修改，应在写入和读取时深拷贝这些引用字段。

处理异常输入和规则升级

生产代码通常还要在规范化前做校验。例如拒绝空名称、把 HTTP 方法统一为大写、限制标签数量，或阻止重复方法。校验失败应返回错误，而不是悄悄为非法值生成句柄。

package policy

import (
	"errors"
	"strings"
	"unique"
)

// BuildHandle 先校验和归一化，再创建稳定句柄。
func BuildHandle(p RoutePolicy) (unique.Handle[string], error) {
	p.Name = strings.TrimSpace(p.Name)
	if p.Name == "" {
		return unique.Handle[string]{}, errors.New("策略名不能为空")
	}
	if len(p.Labels) > 64 {
		return unique.Handle[string]{}, errors.New("标签数量超过限制")
	}
	return StableHandle(p), nil
}

一旦调整等价规则或编码方式，就把版本前缀从 route-policy/v1 升级为新版本，并明确旧索引的迁移策略。否则同一批数据可能同时存在两种身份规则，排查会非常困难。

生命周期与内存边界

unique 会让相同值对应的句柄共享规范表示。只要相关句柄仍然存活，规范值就需要保持可达；当所有句柄都不再可达后，运行时才有机会回收对应条目。因此，不要建立一个永不清理的全局句柄列表。索引删除时同步释放业务侧持有的句柄，才符合预期的数据生命周期。

Handle.Value() 可以取回规范值的浅拷贝，但本例通常无需反向解析字符串键。若业务频繁需要完整对象，应从 PolicyStore 获取原始载荷，而不是把规范键设计成第二套存储格式。

什么时候不值得使用

• 只比较一两次、没有重复数据或索引需求时，直接比较规范键即可。
• 需要跨进程持久化身份时，应保存带版本的规范键或使用数据库主键，不能保存句柄本身。
• 数据量很小但规范化成本很高时，应先用基准测试确认收益。
• 不能容忍任何碰撞时，不要只保存短哈希。可以把哈希用于分桶，但最终仍要核对完整规范键。

常见问题

为什么不用 JSON 后直接 unique.Make？

可以，但要先冻结序列化契约，包括字段缺省规则、映射键顺序和版本升级方式。对身份键而言，契约的确定性比编码格式更重要。

规范键很长，会不会浪费内存？

句柄能让相同规范键共享表示，适合重复率较高且比较频繁的场景。是否划算取决于键长度、重复率与生命周期，应以基准测试和内存剖析为准。

能否用 SHA-256 结果作为规范键？

可以在接受密码学碰撞风险的系统中使用完整摘要，但它会引入额外计算，也隐藏了调试信息。严格要求无碰撞时应保留完整规范键，或在摘要相同后再次核对原键。

官方语义从哪里确认？

可查阅 unique 包文档、Go 1.23 发布说明与 Go 官方 unique 介绍。核心约束是输入必须可比较，句柄相等与输入值相等对应，且句柄适合低成本比较。

这套方法的重点可以压缩成一句话：先把不可比较结构的业务等价关系变成确定的可比较键，再让 unique.Handle 管理规范身份。规则清楚、编码无歧义、生命周期受控时，稳定句柄才真正稳定。