Go 类型文档生成器怎样把可变参数切片显示为省略号

用 go/types 做 Go 类型文档生成时，一个常见现象是：源代码写的是 func Greeting(prefix string, who ...string)，但遍历 Signature.Params() 后，最后一个参数看起来只是 []string。原因不在解析丢失，而在可变参数由“最后一个切片参数”和独立的 Variadic 标志共同表达。

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

优先调用 types.WriteSignature 生成展示文本；如果必须自己拼接参数，只有在 sig.Variadic() 为 true 且当前项是最后一个参数时，才把切片元素类型写成 ...T。

先把可变参数拆成两个事实

go/types.Signature 代表函数或方法类型。Params() 返回参数元组，最后一项在类型层通常表现为切片；Variadic() 则回答这个签名是否采用可变参数语法。只看切片类型会把下面两种声明混为一谈：

func Join(parts []string) string
func Join(parts ...string) string

它们的最后参数都与字符串切片有关，但只有第二个签名的 Variadic() 为 true。因此文档生成器的判断条件不是“最后一个参数是不是 []T”，而是“签名标志为可变参数，并且当前参数位于末尾”。

默认渲染交给 WriteSignature

如果需求只是把类型展示给读者，标准库已经提供了写入器。它不带前导 func 关键字，生成器补上关键字即可；这样省略号、参数名、返回值、方法接收者和泛型参数都由同一套规则处理。

package main

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

func renderSignature(sig *types.Signature) string {
	var buf bytes.Buffer
	// WriteSignature 负责恢复省略号和签名细节；它输出时不带 func。
	types.WriteSignature(&buf, sig, nil)
	return "func" + buf.String()
}

func main() {
	// 这里用标准库构造一个文档示例：最后参数是未命名字符串切片。
	params := types.NewTuple(
		types.NewVar(0, nil, "prefix", types.Typ[types.String]),
		types.NewVar(0, nil, "who", types.NewSlice(types.Typ[types.String])),
	)
	sig := types.NewSignature(nil, params, nil, true)
	fmt.Println(renderSignature(sig))
}

func(prefix string, who ...string)

上面的结果没有函数名，这是因为 Signature 只描述函数类型。文档生成器拿到 *types.Func 时，可以把 obj.Name() 与渲染出的签名组合为 Greeting(prefix string, who ...string)；不要把函数名硬塞进 Signature 的职责里。

自定义格式时只改最后一个参数

有些站点需要自己控制参数颜色、链接或换行，这时可以遍历 Tuple。关键是先保存 Variadic()，再把省略号限定在最后一项。不能对每个切片都加 ...，也不能把普通切片参数转换成可变参数。

func renderParams(sig *types.Signature) []string {
	params := sig.Params()
	if params == nil {
		return nil
	}

	result := make([]string, 0, params.Len())
	for i := 0; i 

这段逻辑适合简单的展示层，但它不是标准库写入器的替代品。当前 Go 类型模型还允许泛型类型参数参与可变签名，且标准库文档对 NewSignatureType 的约束比“最后一个参数是普通切片”更完整。只要不需要定制 DOM 或 Markdown 节点，仍然优先使用 WriteSignature。

方法和泛型签名的边界

方法的接收者通过 Recv() 单独保存，接收者类型参数通过 RecvTypeParams() 保存；它们不会改变“可变参数是否位于 Params 末尾”的判断。泛型函数的类型参数则由 TypeParams() 返回，不能因为参数列表里出现了类型参数，就把它误判成可变参数。

如果生成器需要兼容泛型方法，建议把输出拆成三层：先由 WriteSignature 得到完整签名，再由对象层补名字和接收者，最后才做页面标记。不要先把类型字符串拆成文本再猜测哪里是省略号，否则遇到嵌套函数类型、命名切片或类型参数时很容易破坏语义。

最后用四个条件做速查

• 只想得到 Go 风格文本：调用 types.WriteSignature，并补上需要的 func 或对象名。
• 需要自定义参数节点：检查 sig.Variadic()，且只处理 Params().Len()-1。
• 普通 []T 参数：保持切片写法，不要因为它是最后一个参数就添加省略号。
• 方法或泛型：分别处理 Recv()、RecvTypeParams() 和 TypeParams()，不要从参数文本反推。

常见问题

WriteSignature 为什么没有输出函数名？

因为它接收的是函数类型 *types.Signature，职责是写签名本身。函数名属于 *types.Func 或声明对象层，组合输出时再补上即可。

能不能只判断最后一个参数是不是 *types.Slice？

不能。普通切片参数也会满足这个条件。必须同时判断 sig.Variadic()；对复杂泛型签名，优先让 WriteSignature 处理。

结论很明确：可变参数不是把切片类型“改成”省略号，而是用一个独立的变长标志改变最后参数的展示语法。把这两个事实分开保存，文档生成器就能在普通切片、方法和泛型签名之间保持稳定边界。