Go 泛型类型集合约束设计可复用 API

做一个可复用的泛型 API，真正难的不是把函数改成带方括号的形式，而是把“允许哪些类型、函数要对它们做什么”说清楚。Go 的类型约束接口本质上描述一个类型集合：| 表示并集，~ 表示底层类型匹配。约束越贴近实际运算，调用方得到的类型安全越稳定。

先把 API 操作翻译成约束

假设公共包要提供一个数值累加函数。函数内部只做加法并返回同一种类型，那么约束需要表达“支持加法的数值集合”，而不是直接写成 any。下面的集合覆盖内置整数、浮点数，以及它们的命名类型：

// Number 只允许可用于加法的数值底层类型。
type Number interface {
	~int | ~int64 | ~float64
}

// Sum 保持输入元素类型，并返回相同的类型。
func Sum[T Number](values []T) T {
	var total T // 零值可作为所有允许类型的累加起点
	for _, value := range values {
		total += value // 约束保证 T 支持加法
	}
	return total
}

type Price int64

prices := []Price{120, 80}
total := Sum(prices) // total 的类型仍然是 Price

这里的 ~ 很关键。若写成 int | int64 | float64，自定义的 Price 不在集合中；写成 ~int64 后，底层类型是 int64 的命名类型也能复用 API。与此同时，不能因为“以后可能用到”就把字符串、复数或结构体都加入集合，约束中的每个成员都应该能接受当前实现的运算。

用类型集合收窄可复用的查询键

另一个常见 API 是按业务 ID 从 map 中取值。map 键必须可比较，因此与其把键写成 any 再把问题留给调用方，不如直接声明这个包支持字符串 ID 和整数 ID：

// ID 只接受两种稳定的业务标识，并兼容它们的命名类型。
type ID interface {
	~string | ~int64
}

// GetByID 保留值类型 V，并把缺失键交给 ok 表达。
func GetByID[K ID, V any](items map[K]V, id K) (V, bool) {
	value, ok := items[id] // K 的类型集合保证可以作为 map 键
	return value, ok
}

type UserID int64
users := map[UserID]string{7: "Lin"}
name, ok := GetByID(users, UserID(7))

K 与 V 的职责要分开：键需要集合约束，值只需要被原样传回，所以 V any 足够。返回零值和 bool 也比把“找不到”编码成某个特殊字符串更稳妥。调用时通常可以省略类型参数，编译器会从 map 和 id 推断出它们。

复用前检查三个边界

第一，看约束是否覆盖了实现中的每个操作。类型集合只负责筛选候选类型，函数体仍然只能使用所有候选类型共同支持的能力。第二，看 ~ 是否真的符合 API 语义：它会放行命名类型，如果业务必须拒绝自定义类型，就不要无条件使用它。第三，看联合项是否重叠；例如 ~int | MyInt 会产生重复覆盖，设计时应保留一个表达。

方法约束也要单独判断。类型集合适合描述“哪些底层类型可以参与某种操作”，方法接口适合描述“调用方必须提供什么行为”。两者交集过窄时，错误会在实例化时出现；这通常比运行时类型断言更早、更容易定位。

常见问题

为什么不直接把类型参数写成 any？

因为 any 不保证加法、比较或作为 map 键所需的能力。过宽的约束会把错误推迟到类型断言或反射代码。

~int64 和 int64 有什么区别？

前者包含底层类型为 int64 的命名类型，后者只匹配预先写出的那个类型。是否允许命名类型，应由 API 的复用目标决定。

多个联合项能不能随意添加？

不能。新增类型必须能完成函数体中的全部操作，而且不能造成类型集合重叠；否则约束会变得含糊或直接无法通过编译。

把约束当成 API 的输入契约来设计，通常比先写一个“万能泛型函数”更耐用：类型集合负责范围，函数体负责操作，调用方则获得可推断、可复用且边界清楚的接口。