Go types.NewTypeParam 怎样给类型参数绑定约束

在用 go/types 做静态分析、代码生成或测试夹具时，经常需要手工拼出一个泛型类型参数。types.NewTypeParam 的关键不在“传入一个名字就结束”，而在于约束类型必须处在合适的完成状态：可以直接传入已经完整定义的约束，也可以先传入 nil，等接口约束准备好后再调用 SetConstraint。

最稳妥的顺序是：先创建 TypeName，再用 NewTypeParam(name, nil) 创建参数；把约束接口的底层类型集合准备完整后调用 SetConstraint，最后再把参数交给 Named.SetTypeParams 等泛型声明对象使用。

本文的示例围绕这个顺序展开。它只讨论 go/types 的类型建模对象，不把运行时反射类型当成泛型约束。

先把问题拆成两个对象：参数名与约束

NewTypeParam 的第一个参数是 *types.TypeName，第二个参数是约束 types.Type。因此，参数名和约束并不是同一个对象：TypeName 表示“这个参数叫什么”，TypeParam 才表示泛型声明里的参数类型。

如果约束已经完整，可以直接作为第二个参数传入；如果约束还要组合方法、嵌入类型或联合项，就先传 nil，避免在约束尚未完成时提前使用参数。

package main

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

func main() {
    pkg := types.NewPackage("example.com/constraints", "constraints")

    // TypeName 只负责保存类型参数的名字，类型本身暂时留空。
    name := types.NewTypeName(token.NoPos, pkg, "E", nil)

    // 约束稍后才会完成，所以先用 nil 创建 TypeParam。
    param := types.NewTypeParam(name, nil)
    fmt.Println(param.Obj().Name()) // E
}

这里的 nil 不是“没有约束就可以随便使用”的意思，而是把约束绑定动作延后。官方文档明确允许这样做，但后续必须在使用参数前调用 SetConstraint。

先完成接口约束，再调用 SetConstraint

最小可用的约束可以从空接口开始。使用 NewInterfaceType 创建接口后，要显式调用 Complete，让接口的类型集合完成计算。非空约束也遵循同样规则：方法或嵌入类型准备好后，再完成接口。

// 完整代码片段：把已经完成的接口约束绑定到 TypeParam。
constraint := types.NewInterfaceType(nil, nil)
constraint.Complete()

// SetConstraint 接收已经完成的约束，之后才能安全读取参数状态。
param.SetConstraint(constraint)

fmt.Println(param.Constraint() == constraint) // true
fmt.Println(param.Underlying() == constraint) // true

Constraint() 返回参数声明使用的约束；Underlying() 返回该约束的底层类型。对 TypeParam 来说，底层类型总是接口，因此这两个读取入口在空接口示例里会指向同一个约束对象。

容易混淆的一点是：Complete 完成的是接口约束，SetConstraint 完成的是参数与约束之间的绑定。两者承担的职责不同，不能省略其中任意一个来“碰运气”。

绑定后怎样确认参数已经进入泛型声明

单独创建 TypeParam 还不等于它已经属于某个泛型类型。要把它放进命名类型的参数列表，需要调用 Named.SetTypeParams。这个过程也解释了为什么 Index() 在刚创建时可能返回 -1：参数尚未绑定到参数列表。

// 创建一个命名类型，底层类型先使用空结构体作为示例。
typeName := types.NewTypeName(token.NoPos, pkg, "Box", nil)
named := types.NewNamed(typeName, types.NewStruct(nil, nil), nil)

// 把同一个 TypeParam 放入命名类型的参数列表。
named.SetTypeParams([]*types.TypeParam{param})

fmt.Println(named.TypeParams().Len()) // 1
fmt.Println(param.Index())            // 0
fmt.Println(named.TypeParams().At(0) == param) // true

观察结果时可以分成三层：Named.TypeParams 说明声明容器持有哪些参数；TypeParam.Index 说明当前参数在列表中的位置；Constraint 与 Underlying 说明这个参数允许的类型集合视图。

看到异常时，优先排查这四个顺序问题

第一，直接把未完成接口传给 NewTypeParam。 如果接口还没有完成底层类型集合，应该改用 nil 延迟绑定，或者先调用 Complete。

第二，SetConstraint 调用太晚。 绑定完成前，不要把参数当作已经可用的类型去读取约束或参与更复杂的类型构造；只有形成其他类型这一类有限场景可以提前存在。

第三，把同一个参数列表重复交给多个命名类型。 NewTypeParam 创建出的参数只能按一个声明关系绑定。若一个参数需要表达另一份独立声明，应重新创建对应的 TypeName 和 TypeParam，不要复用后再调用 SetTypeParams。

第四，把 Index 当成创建序号。 它表示参数在已绑定列表中的位置；尚未进入类型参数列表时返回 -1，不能用它判断 NewTypeParam 被调用的先后。

小结：用“先完成约束，再绑定声明”记住 API

这条 API 链可以压缩成一句话：NewTypeName 负责名字，NewTypeParam 负责参数对象，NewInterfaceType(...).Complete() 负责准备约束，SetConstraint 负责绑定，Named.SetTypeParams 负责把参数放进泛型声明。

• 约束已经完整：可以直接传给 NewTypeParam。
• 约束需要后续组合：先传 nil，完成接口后调用 SetConstraint。
• 要确认声明关系：读取 TypeParams、Index、Constraint 和 Underlying。

相关问题

NewTypeParam 的 constraint 可以一直传 nil 吗？
可以先传 nil，但在把参数用于普通类型操作或泛型声明读取前，应按顺序调用 SetConstraint。

为什么 Complete 和 SetConstraint 都要调用？
Complete 处理接口约束自身的类型集合，SetConstraint 处理 TypeParam 对约束的绑定，它们不是同一个阶段。

Underlying 为什么总是接口？
TypeParam 的底层类型取自约束的底层类型，而类型参数约束的底层表示是接口类型。