Go types.Signature 怎样导出参数与返回值的类型清单

做 Go 静态分析时，拿到一个 *types.Signature 只是开始。真正要写入索引或文档的，通常是参数名、参数类型、返回值类型、接收者和是否可变参数。最稳妥的做法是把 Params() 与 Results() 当成两个 *types.Tuple，用 Len() 和 At(i) 逐项导出，再把每个 *types.Var 的 Name() 与 Type() 转成文本。

官方地址：https://pkg.go.dev/go/types#Signature

结论：参数清单来自 sig.Params()，返回值清单来自 sig.Results()；两个 Tuple 都可能为 nil，匿名参数的 Name 也可能是空字符串。

先把 Signature 的信息边界分清

types.Signature 表示非内置函数或方法类型。函数通常没有接收者，方法可以通过 Recv() 取得接收者；接收者并不属于 Params 列表，也不参与签名身份比较。Variadic() 只告诉你签名是否为可变参数，不能替代对最后一个参数类型的读取。

因此导出结构时建议至少分成四块：接收者、参数、返回值、签名属性。参数和结果的顺序由 Tuple 保留，不能用名称排序，否则会改变调用约定。

用 Tuple.At 逐项展开参数和返回值

最小可复用函数可以接收一个 Tuple，遍历每个变量并输出结构化记录。Tuple.Len() 对 nil 接收者是安全的，但为了让“没有结果”和“有一个匿名结果”在数据层保持可区分，仍然可以显式判断 Tuple 是否为 nil。

// signatureItems 把一个参数组或返回值组展开成稳定的清单。
type signatureItem struct {
    Name string
    Type string
}

func signatureItems(tuple *types.Tuple) []signatureItem {
    if tuple == nil {
        return nil // nil 表示签名没有这一组参数或结果。
    }

    items := make([]signatureItem, 0, tuple.Len())
    for i := 0; i < tuple.Len(); i++ {
        variable := tuple.At(i)
        items = append(items, signatureItem{
            Name: variable.Name(), // 匿名参数的名称可能为空。
            Type: types.TypeString(variable.Type(), nil), // 保留可读的类型表达式。
        })
    }
    return items
}

这里的关键不是把类型转成某个具体实现，而是保留 types.Type 接口带来的统一入口。TypeString 会把切片、函数、命名类型等类型转换为适合展示的文本；如果需要包名限定策略，可以传入自定义 Qualifier。

把接收者、可变参数和泛型属性一并导出

只读取 Params 和 Results，容易把方法写成普通函数，也会丢掉可变参数和泛型信息。下面的结果结构把这几个属性放在签名级别，参数项仍然保持源码顺序。

// exportedSignature 是给索引或文档生成器使用的简化模型。
type exportedSignature struct {
    Receiver string
    Params   []signatureItem
    Results  []signatureItem
    Variadic bool
    TypeParams int
}

func exportSignature(sig *types.Signature) exportedSignature {
    result := exportedSignature{
        Params:   signatureItems(sig.Params()),
        Results:  signatureItems(sig.Results()),
        Variadic: sig.Variadic(), // 只记录属性，最后一个参数仍保留原类型。
    }
    if recv := sig.Recv(); recv != nil {
        result.Receiver = types.TypeString(recv.Type(), nil) // 函数没有接收者。
    }
    if params := sig.TypeParams(); params != nil {
        result.TypeParams = params.Len() // 泛型参数数量单独保存。
    }
    return result
}

如果只面向旧版本 Go 的非泛型代码，TypeParams() 仍可以作为兼容读取点；如果要创建签名，官方文档已把旧的 NewSignature 标为 deprecated，应优先考虑 NewSignatureType。

推荐的导出流程和速查表

实际接入 AST 类型检查结果时，可以按下面的固定顺序组织：先确认对象确实是 *types.Signature，再读取接收者；随后分别展开参数和结果；最后保存可变参数、泛型参数数量以及 sig.String() 作为人类可读的兜底文本。不要把字符串解析当作主要方案，因为字符串适合展示，不适合稳定地恢复每一项的边界。

最容易混淆的几个边界

• 把接收者当成第一个参数：方法的接收者通过 Recv() 读取，不要手动塞入 Params。
• 把 nil Tuple 当成空字符串：数据模型应保留“没有这一组”的状态，展示层再决定是否显示空列表。
• 按名称排序参数：同名、匿名或重载式文档场景都可能让排序失去调用顺序，应使用 Tuple 原序。
• 只输出 sig.String：它适合摘要和日志；要生成字段级清单，仍应逐项访问 Var。

相关问题

匿名参数如何导出？

保留空的 Name，不要自行生成会被误认为源码名称的占位符；如果界面需要展示，可在展示层使用“参数 1”这类标签。

返回值只有一个时还需要 Tuple 吗？

需要。统一按 Tuple 遍历可以同时覆盖无返回值、单返回值和多返回值，避免为单项结果维护另一套逻辑。

如何获得完整函数签名文本？

可以调用 sig.String() 作为摘要，但它不应替代 Params、Results 和属性字段的结构化导出。