Go 泛型约束里的 ~ 类型集合怎么影响 API 兼容性：从约束设计到调用方迁移

同一个函数如果只接受 int，调用方自定义的 UserID 往往会在编译阶段被挡住；把约束改成 ~int 后，底层类型是 int 的命名类型也能进入 API。这个小小的波浪号不是“任何整数”的别名，它改变的是类型集合边界，也会影响库升级时哪些代码还能继续编译。

先看一个会卡住调用方的泛型函数

假设包里有一个把整数切片转成索引映射的工具。第一版为了写得直观，约束直接使用 int：

package indexset

func Unique[T int](values []T) []T {
    seen := make(map[T]struct{}, len(values))
    out := make([]T, 0, len(values))
    for _, value := range values {
        if _, ok := seen[value]; ok {
            continue
        }
        seen[value] = struct{}{}
        out = append(out, value)
    }
    return out
}

type UserID int

var ids = Unique([]UserID{7, 7, 9}) // 约束不匹配

UserID 的底层类型确实是 int，但它仍然是一个独立的命名类型。这里的错误不是运行期类型转换失败，而是类型推导后发现 UserID 不在 int 这个单元素集合里。

参数约束真正表达的是什么

把约束改成下面这样，表达的就不再是“参数必须叫 int”，而是“参数的底层类型必须是 int”：

type IntegerID interface {
    ~int
}

func Unique[T IntegerID](values []T) []T {
    seen := make(map[T]struct{}, len(values))
    out := make([]T, 0, len(values))
    for _, value := range values {
        if _, ok := seen[value]; ok {
            continue
        }
        seen[value] = struct{}{}
        out = append(out, value)
    }
    return out
}

ids := Unique([]UserID{7, 7, 9}) // 可以推导 T 为 UserID

返回值仍然是 []UserID，这点很重要。约束只负责描述允许进入函数的类型，不能顺手把领域类型擦掉。调用方后面还要把这些 ID 交给权限、缓存或数据库层时，保留命名类型会让错误传参更早暴露。

从调用方需求倒推约束，而不是先堆联合元素

API 设计时可以把选择拆成三问：调用方是否需要保留命名类型？函数是否只使用比较、映射键等底层能力？未来是否可能接纳另一种底层类型？答案不同，约束写法也不同。

这里别急着把约束写成很长的联合。集合越宽，公共 API 的承诺越大；如果函数实际只做键比较，~int 可能已经够用，加入 ~int64 反而会让未来的返回值和溢出语义变得含糊。

兼容性检查要覆盖三类类型

命名类型与类型别名不是一回事

type UserID int 创建了新的命名类型，能体现领域语义；type UserID = int 则只是别名。前者需要 ~int 才能匹配，后者在很多场景下和 int 直接等价。升级泛型库时，测试里两种声明都放一个，才不会只测到容易通过的路径。

联合约束里的运算必须对所有元素成立

下面的约束允许两类底层整数，但不要因为它们都能作为 map key，就默认业务计算可以混写：

type SignedID interface {
    ~int | ~int64
}

func Count[T SignedID](value T) int {
    // 可以把 value 当作 map 的键；跨 int 与 int64 的算术仍要谨慎。
    return 1
}

公共函数最好把一个动作说清楚：是去重、查找、排序，还是数值计算。动作越接近领域规则，越应该缩窄约束并在命名上保留语义，而不是用“泛型”作为万能入口。

把约束升级当成一次可回滚的 API 改动

如果这是一个被多个模块依赖的包，改动后至少保留三组编译测试：

• 原来的 int 调用继续编译，确认没有误删既有能力。
• 新的命名类型调用成功，并断言返回值仍是该命名类型的切片。
• 不应被接受的类型仍然失败，例如底层为 string 的订单号不能因为约束写宽而混入。

type OrderID string
// Unique([]OrderID{"A-1"}) 应该继续被约束拒绝

type UserID int
got := Unique([]UserID{7, 7, 9})
var _ []UserID = got

发布前可以把这组测试放在包的兼容性目录里，和普通业务测试一起跑。它们的价值不在于覆盖大量数据，而在于把“哪些类型属于这个 API”固定下来，避免后续有人为了临时需求把联合集合继续加大。

常见问题

~int 能接受 int64 吗？

不能。~int 只覆盖底层类型为 int 的类型，int64 以及底层为 int64 的命名类型都不在这个集合中。

类型别名和命名类型在这里有什么区别？

命名类型有自己的类型身份，别名只是另一个名字。测试泛型 API 时，最好同时写 type A int 和 type B = int，这样能看清约束真正放宽了什么。

把约束写宽会让 API 更兼容吗？

它会扩大可接受的调用范围，但也扩大长期承诺。只有当函数逻辑对整个类型集合都成立，并且返回值语义仍然清楚时，才值得放宽。

为什么不直接在调用处转换成 int？

转换可以解决一次调用，却会让领域类型在边界处消失。若库函数本来不需要丢弃类型信息，让泛型参数保留调用方类型通常更稳。

收束：先守住类型语义，再谈泛型复用

~ 的价值在于准确描述“底层类型相同、类型身份不同”的调用方。设计公共 Go API 时，先写出最小可用约束，再用命名类型、别名和错误类型做编译回归；确认操作对整个类型集合成立后，才把边界扩宽。这样一次小改动既能接住新的调用方，也不会把领域语义变成一串裸整数。