Go ast.FieldList.NumFields 怎样统计合并声明的参数数量

我第一次给 Go AST 做参数索引时，先看了 len(fieldList.List)，结果在遇到 a, b int 这类合并声明后，计数少了一个。真正应该调用的是 ast.FieldList.NumFields()：它会遍历每个 Field，有几个名字就计几个；Names 为空的匿名参数或字段按一个计数，空的 FieldList 返回 0。

官方文档：https://pkg.go.dev/go/ast#FieldList。下面把它放进“解析、提取、计数、失败处理”的小工作流里，重点看一个 Field 为什么可能代表多个参数。

先分清 List 项和实际字段数量

FieldList 表示被括号、花括号或方括号包围的一组 Field。List 保存的是语法字段项，而不是最终参数个数。例如函数声明 func merge(a, b int, text string) 中，a 和 b 共用一个类型表达式，它们可以放在同一个 Field 的 Names 中。

因此，len(params.List) 只能回答“AST 里有几项声明”，而 params.NumFields() 才回答“这些声明代表几个参数”。官方实现的核心规则可以概括为：

func (f *ast.FieldList) NumFields() int {
	// nil 列表没有参数或字段，直接返回零。
	count := 0
	if f == nil {
		return count
	}
	for _, field := range f.List {
		// 合并声明按名字数量展开；没有名字的字段按一个计算。
		n := len(field.Names)
		if n == 0 {
			n = 1
		}
		count += n
	}
	return count
}

这个算法解释了三个容易混淆的结果：a, b int 的名字数量是 2；匿名参数 int 没有名字但仍算 1；一个空的 FieldList 不会因为列表对象存在就被算成 1。

把 NumFields 放进 AST 提取工作流

实际做索引时，我会把计数阶段放在解析结果已经定位到具体函数之后：先得到 *ast.File，再找到 *ast.FuncDecl，从 FuncDecl.Type.Params 读取参数列表。这样字段来源清楚，后面还可以回到每个 Field.Names 解释计数差异。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
)

func countFunctionParams(src string) (int, int, error) {
	// 只解析内存中的源码，ParseFile 返回文件级 AST。
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "sample.go", src, 0)
	if err != nil {
		return 0, 0, err
	}

	for _, decl := range file.Decls {
		fn, ok := decl.(*ast.FuncDecl)
		if !ok || fn.Type.Params == nil {
			continue
		}
		// List 是语法项数量，NumFields 是实际参数数量。
		return len(fn.Type.Params.List), fn.Type.Params.NumFields(), nil
	}
	return 0, 0, fmt.Errorf("未找到带参数的函数")
}

func main() {
	// a、b 共用一个 Field，text 和 rest 各占一个 Field。
	src := `package demo
func merge(a, b int, text string, rest ...byte) {}`
	listItems, fields, err := countFunctionParams(src)
	if err != nil {
		fmt.Println(err)
		return
	}
	// 这里展示两个口径，便于调试提取器的计数策略。
	fmt.Println(listItems, fields)
}

在这个例子里，参数声明项和实际参数数目不是同一个概念：a、b 合并在一个字段项中，但 NumFields 会把它们展开计算。可变参数的省略号只改变类型表达式的形状，不会额外增加一个参数。

几个字段形态，按同一条规则处理

有多个名字的字段：a, b int 的 Names 长度为 2，所以贡献 2。不要只按 Field.Type 的数量推算参数。

无名字的参数：func(int, string) 中每个字段的 Names 都为空，但每个字段仍然代表一个位置参数，因此各贡献 1。

结构体字段或接口方法：FieldList 不只服务于函数参数；结构体字段、接口方法以及类型参数列表也使用相同的 AST 容器。你要统计哪一类，取决于你把哪个字段列表交给 NumFields，方法本身不会替你区分业务语义。

方法接收者：接收者也可能是一个 FieldList。如果需求是“函数参数总数”，不要把接收者列表和 FuncType.Params 相加；如果需求是“方法声明的所有绑定字段”，则应在结果模型里单独命名，避免后续调用者误解。

失败处理：别把三个数量问题混在一起

我在提取器里通常保留三个字段：list_items 表示 len(FieldList.List)，declared_names 表示展开后的名字总数，num_fields 表示 API 的结果。这样遇到“为什么页面显示参数少一个”时，可以快速判断是合并声明、匿名参数还是读取了错误的列表。

还要注意两个边界。第一，nil 的 FieldList 调用 NumFields 得到 0，适合在函数没有参数时直接读取，但不能说明你已经找到目标函数。第二，NumFields 统计的是 AST 中的参数或字段，不是源码字符串里的逗号数，也不是类型检查器推导出的业务参数。

func summarize(list *ast.FieldList) (items, fields int) {
	// 先保护 nil，再分别保存两个统计口径。
	if list == nil {
		return 0, 0
	}
	return len(list.List), list.NumFields()
}

常见问题

len(FieldList.List) 和 NumFields() 为什么不同？ 前者数语法字段项，后者会把一个字段里的多个名字展开；a, b int 正是最常见的差异来源。

匿名参数为什么也算一个？ 因为 Field.Names 为空只表示没有显式名字，并不表示没有一个参数位置。

NumFields 能判断参数类型是否正确吗？ 不能。它只负责计数；类型、位置和声明语义仍需要读取 Field.Type、位置信息或后续类型分析结果。

最后可以记成一句话：FieldList.List 反映 AST 的分组方式，FieldList.NumFields() 反映这些分组展开后的参数或字段数量。做 Go AST 索引时，把两种口径同时保留，合并声明和匿名字段就不会再悄悄少算。