Go AST 文档工具怎样给无名返回值生成位置编号

我在给 Go 函数签名做文档时，最先踩到的坑不是解析失败，而是返回值编号悄悄偏移：把 FieldList.List 的下标直接写成“第几个返回值”，遇到无名返回值或一条声明里写了多个名字，生成的文档就会和读者看到的签名对不上。

稳定做法是把“字段节点”与“返回值槽位”分开。Field.Names 为空时，把当前字段按一个无名槽位处理；有多个名字时，按名字数量展开。编号由独立游标维护，类型文本和源码行号则从同一个 Field 读取。

升级范围：从 List 下标迁移到语义槽位

go/ast 中，FieldList 表示一组被括号、花括号或方括号包住的字段，核心数据在 List []*ast.Field。函数签名的参数和结果也使用这套结构。

这里有两个容易混在一起的数量：

• 节点数量：len(fieldList.List)，表示 AST 中有多少个 Field 节点。
• 槽位数量：fieldList.NumFields()，表示参数或结构体字段实际代表多少个位置。无名字段算 1 个；同一字段里有多个名字时按名字数量计算。

所以 func() (int, error) 通常有两个 Field 节点，也有两个返回值槽位；而 func() (a, b int) 可以由一个 Field 节点表示，却对应两个具名槽位。文档工具要展示“第几个返回值”，应该面向第二个数量。

变更表：几个 API 各自负责什么

旧代码风险：len(List) 会漏掉无名结果的位置

旧写法通常长这样：遍历 results.List，用循环下标拼出 result[0]、result[1]。它在每个 Field 恰好代表一个返回值时看起来没问题，但以下签名会暴露问题：

func load() (name, version string, error)
func decode() (int, error)
func locate() (path string, line, column int)

第一和第三个签名包含“一个字段节点代表多个名字”的情况，第二个签名则包含多个无名字段。只递增 List 下标，会让人看到的槽位数和文档编号不一致。另一个细节是：无名参数或返回值的 Names 为 nil，但 Field.Type 仍然是有效的类型表达式，不能把它当作缺失字段。

新写法：用一个游标展开具名与无名结果

我现在会把“人类可读编号”与“程序槽位”同时保存。示例中使用从 1 开始的 result[1]，因为文档读者更容易理解；Slot 仍从 0 开始，便于后续数组索引或和其他 AST 工具对接。

package main

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

// ResultDoc 是文档层使用的一个返回值记录。
type ResultDoc struct {
	Slot     int    // 程序内部使用的零基槽位
	Label    string // 面向读者的 result[1] 或具名结果名
	TypeText string // 从 Field.Type 格式化出来的类型文本
	Line     int    // Field.Type 在源文件中的行号
}

// exprText 把 AST 表达式还原成可放进文档的 Go 类型文本。
func exprText(fset *token.FileSet, expr ast.Expr) (string, error) {
	if expr == nil {
		return "", fmt.Errorf("字段没有类型表达式")
	}
	var buf bytes.Buffer
	// format.Node 只负责格式化当前表达式，不需要重新解析整个文件。
	if err := format.Node(&buf, fset, expr); err != nil {
		return "", err
	}
	return buf.String(), nil
}

// resultDocs 按语义槽位展开函数结果，避免把 FieldList.List 下标当编号。
func resultDocs(fset *token.FileSet, results *ast.FieldList) ([]ResultDoc, error) {
	if results == nil {
		return nil, nil // 没有结果列表时，函数没有返回值
	}
	docs := make([]ResultDoc, 0, results.NumFields())
	slot := 0
	for _, field := range results.List {
		text, err := exprText(fset, field.Type)
		if err != nil {
			return nil, err
		}
		line := fset.Position(field.Pos()).Line
		if len(field.Names) == 0 {
			// 无名结果没有 Ident，但仍然占据一个独立槽位。
			docs = append(docs, ResultDoc{Slot: slot, Label: fmt.Sprintf("result[%d]", slot+1), TypeText: text, Line: line})
			slot++
			continue
		}
		for _, name := range field.Names {
			// 一个 Field 可能包含多个名字，每个名字都要推进槽位。
			docs = append(docs, ResultDoc{Slot: slot, Label: name.Name, TypeText: text, Line: line})
			slot++
		}
	}
	return docs, nil
}

func main() {
	const source = `package sample
func decode() (int, error) { return 0, nil }`
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "sample.go", source, 0)
	if err != nil {
		panic(err)
	}
	_ = file // 文档工具可在这里定位目标 FuncDecl 的 Type.Results
}

关键不是把所有情况塞进一个复杂判断，而是始终维护 slot：无名字段加 1；具名字段按 Names 中的每个名字各加 1。这样 (name, version string, error) 和 (int, error) 都能得到连续的结果槽位。

回归检查：别只测两个无名返回值

我会把以下组合放进文档工具的回归样例中。这里只检查 AST 结构和生成记录，不需要为了配图运行本地代码。

另外要单独测试位置来源：Field.Pos() 只是 AST 节点的起始位置，应该交给 FileSet.Position 转换后再写入行号。对于无名结果，起始位置通常落在类型表达式上；这正好适合作为文档中的“返回值声明位置”，但它不是槽位编号本身。

迁移清单：把编号逻辑收进文档层

1. 读取函数的 Type.Results，先处理 nil，避免没有返回值的函数触发空指针。
2. 用 NumFields() 预估记录容量，但用 Field.Names 决定实际展开数量。
3. 用独立 slot 递增，不使用 range 的 List 下标做最终编号。
4. 无名结果生成稳定的 result[n] 标签，具名结果保留源码中的名字。
5. 类型用 format.Node 从表达式生成，位置用 FileSet.Position 转换。
6. 回归覆盖空结果、全无名、全具名、混合结果和成组具名结果。

这次迁移给我的最大收获是：AST 的一个节点不一定等于用户理解中的一个项目。只要文档工具把“语法结构”和“语义槽位”分成两层，给无名返回值编号就不再依赖特殊字符串判断，也不会因为签名写法变化而让后续编号整体错位。

常见问题

len(FieldList.List) 还能用吗？

可以用来回答“有多少个 AST 字段节点”，但不能单独用来回答“有多少个参数或返回值位置”。后一个问题优先使用 NumFields() 并结合 Names 展开。

无名返回值为什么不是缺少名字的错误节点？

因为无名参数或返回值本来就是合法的 Go 语法。Names 为 nil 只说明没有对应的标识符，Type 仍然描述该槽位的类型。

编号应该从 0 还是从 1 开始？

内部数组索引建议保留零基 Slot；面向文档读者的标签可以从 1 开始。关键是把两者明确分成两个字段，不要让一个数字同时承担两种语义。