Go 手工构造 types.Interface 后怎样完成方法集计算

在写 Go 静态分析器、代码生成器或类型索引时，可以不用解析完整的源码文件，直接用 go/types 手工拼出一个接口类型。容易被忽略的是：NewInterfaceType 返回的对象虽然已经装入了方法和嵌入类型，但方法集计算仍有明确的完成时机。

官方文档：https://pkg.go.dev/go/types#Interface

正确顺序是：准备显式方法和嵌入类型，等待嵌入类型全部定义，再调用 Complete()，最后读取 NumMethods()、Method() 或构造 MethodSet。完成后的接口才适合并发读取。

先判断接口对象处在哪个阶段

手工构造的 types.Interface 可以看成两层数据：

• 输入层：显式声明的方法，以及通过嵌入放进来的其他类型。
• 计算层：把这些输入合并、去重并形成最终可查询的方法集和类型集合。

NewInterfaceType 负责创建输入层对象；Complete 负责把类型集合计算出来。不要因为构造函数已经返回指针，就把它当成“方法集已经最终确定”。

触发信号：查询方法集时结果不完整

如果工具代码刚创建接口就调用 NumMethods、Method 或依赖接口类型集合的判断，问题通常不在查询循环，而在完成时机。特别是接口包含嵌入类型时，嵌入对象还可能处在“已经创建、但自身尚未完成”的阶段。

排查时先记录三件事：接口是否由 NewInterfaceType 创建，嵌入类型是否全部准备好，调用查询 API 前是否显式执行过 Complete。这比单纯打印方法数量更容易定位阶段错误。

处理步骤一：构造显式方法和嵌入类型

下面的示例用 types.NewFunc 和 types.NewSignatureType 手工生成方法，再构造一个带嵌入接口的接口类型。示例没有依赖真实源码文件，适合放在生成器或测试夹具中。

package main

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

func noArgMethod(name string) *types.Func {
    // 用 int 返回值让方法签名在输出中更容易区分。
    result := types.NewVar(token.NoPos, nil, "result", types.Typ[types.Int])
    signature := types.NewSignatureType(
        nil,
        nil,
        nil,
        types.NewTuple(),
        types.NewTuple(result),
        false,
    )
    // 接收者留空，由 NewInterfaceType 按接口方法规则补齐。
    return types.NewFunc(token.NoPos, nil, name, signature)
}

func main() {
    readable := types.NewInterfaceType(
        []*types.Func{noArgMethod("Read")},
        nil,
    )

    // 外层接口会嵌入 readable，因此先保证内层接口已完成。
    readable.Complete()
    combined := types.NewInterfaceType(
        []*types.Func{noArgMethod("Close")},
        []types.Type{readable},
    )

    // 这里还不能查询 combined 的最终方法集，下一步再完成它。
    fmt.Println(combined.NumExplicitMethods())
}

这里的 NumExplicitMethods 只统计接口直接声明的方法，示例输出为 1。它不等于包含嵌入方法后的总数；总数应在完成后通过 NumMethods 获取。

处理步骤二：在嵌入类型完成后调用 Complete

Complete 的调用点应该紧跟“所有嵌入类型已准备好”这个事件，而不是随意放在第一次查询之后。它会计算接口的类型集合，并返回接口自身，因此可以写成链式初始化，但在复杂构造器里更推荐保留清晰的独立语句。

func completeAndList(iface *types.Interface) {
    // Complete 必须发生在方法集查询和并发读取之前。
    iface.Complete()

    for i := 0; i 

对上面的 combined 调用该函数后，方法集会同时包含 Close 和嵌入接口提供的 Read。NumExplicitMethods 与 NumMethods 的差异正好能帮助工具区分“当前接口直接写了什么”和“最终接口具有什么方法”。

处理步骤三：把完成时机固定在构造边界

如果接口对象会被多个 goroutine 读取，建议让构造函数承担完整生命周期，而不是把 Complete 暴露给每个调用者。这样既能避免有人忘记完成，也能把并发读取的前提收敛到一个位置。

func buildCombinedInterface() *types.Interface {
    // 先完成所有嵌入接口，保证外层计算有稳定输入。
    embedded := types.NewInterfaceType(
        []*types.Func{noArgMethod("Read")},
        nil,
    )
    embedded.Complete()

    result := types.NewInterfaceType(
        []*types.Func{noArgMethod("Close")},
        []types.Type{embedded},
    )
    // 只把已经完成的对象交给后续查询和并发消费者。
    return result.Complete()
}

这里返回的是完成后的接口。后续代码可以直接读取方法集，不需要再猜测是否漏掉了初始化步骤。若构造过程需要继续添加方法或嵌入关系，应在所有修改结束后再完成，并避免把同一个对象提前发布给其他 goroutine。

快速判断：哪些 API 可以放在 Complete 之后

回滚路径：构造失败时不要继续发布对象

手工构造接口最需要防护的输入错误是重复方法。官方 API 约定接口不得包含重复方法，否则在完成过程中会触发 panic。因此，生成器如果能在自己的输入层发现同名同签名方法，应提前返回错误；如果无法提前判断，也不要在 panic 后把半成品接口放入共享缓存。

一个安全的边界是：构造、完成、查询都在单个函数内完成；函数成功才返回 *types.Interface，失败则返回错误或让上层决定如何记录输入问题。不要为了“拿到部分方法”而继续消费未完成对象。

告警确认与复盘：记录输入和完成状态

类型分析工具出现方法数量变化时，日志中至少应保留显式方法数、嵌入类型数、最终方法数和构造阶段。这样可以区分三类问题：

• 显式方法数正确、最终方法数偏少：优先检查嵌入类型是否已完成。
• 最终方法数突然重复或完成时 panic：检查输入是否把同一个方法加入了两次。
• 单线程正常、并发运行结果不稳定：检查接口是否在 Complete 前就被发布。

不要只记录 String() 的最终文本。方法来源、嵌入层次和完成时机才是以后复盘时能还原问题的关键信息。

结论

手工构造 types.Interface 时，NewInterfaceType 只是准备输入，Complete 才是把输入变成可稳定查询的方法集的边界。正确顺序可以压缩成四步：构造显式方法、完成所有嵌入类型、完成外层接口、读取最终方法集。

如果代码需要并发分析，最好只返回已经 Complete 的接口对象；如果输入来自自动生成流程，则把重复方法检查和构造失败记录放在同一个边界内。

常见追问

Complete 调用一次后还需要重复调用吗？

正常构造流程中，在所有嵌入类型和方法都准备好后调用一次即可。重复调用不会替代后续对输入结构的重新设计；如果还要修改构造输入，应重新安排构造和完成边界。

NumExplicitMethods 和 NumMethods 为什么不一样？

前者只统计当前接口直接声明的方法，后者统计完成类型集合后的最终方法集，包含嵌入关系带来的方法。

可以先把未完成接口放进其他类型里吗？

官方契约允许在完成前用接口去形成其他类型，但不应把它当成可自由查询、可并发读取的最终接口。最稳妥的做法仍是完成后再交给方法分析和共享缓存。

资料来源

https://pkg.go.dev/go/types#Interface

https://go.dev/src/go/types/interface.go