Go 类型分析怎样一次遍历 Tuple 生成返回值文档

对 Signature.Results() 返回的 *types.Tuple 做一轮按位置遍历，在循环内同时读取 Var.Name() 和 Var.Type()，再用 types.TypeString 格式化类型，就能生成有序的返回值文档记录。不要先拆出名称列表、再拆类型列表后按名字拼接：未命名返回值没有可用的名称键。

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

把返回位置整理成文档记录

假设团队的文档任务需要把 Read 的两个返回位置列出来，问题不是获取调用产生的值，而是把声明中的返回列表变成可渲染记录。适合的中间结构是 ReturnDoc：Position 保存阅读序号，Name 保留声明名称，TypeText 保存展示用类型文本。

直接按 Tuple 的位置生成切片，可以保留原本的返回顺序。类型相同、名称为空或多个位置含义相近，都不应触发去重。文档中的第一项对应调用时的第一项返回值，而不是按名称排序后的第一项。

一次遍历同时收集序号、名称与类型

package main

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

type ReturnDoc struct {
    Position int
    Name     string
    TypeText string
}

func describeReturns(t *types.Tuple, qf types.Qualifier) []ReturnDoc {
    // nil Tuple 的 Len 为零；提前分配记录空间
    n := t.Len()
    docs := make([]ReturnDoc, 0, n)
    for i := 0; i 

类型模型里的 Tuple 包含按顺序排列的 Var。文档模型里的 ReturnDoc 把 Position、Name 与 TypeText 放在一条记录中，避免三组数组因过滤条件不同而错位。

例子使用 count int 与 ok bool，按代码语义预期生成两条同序记录；它不是本机实际运行结果。Position 使用 i+1 便于人阅读，At 仍使用从零开始的下标。循环只访问合法范围，空列表不会进入循环。

这轮收集对返回位置的访问次数随项数线性增长，但类型字符串格式化也有自己的成本，不能据此声称整个源码分析过程只有这一个循环或固定耗时。预分配是减少中间扩容的选择，不是已经测得的性能收益。

从已检查的包里取得函数签名

示例中的 Package 提供包 Scope，其中找到的 Func 关联 Signature。签名的 Results 才是收集器的输入，得到的文档切片随后交给文本、JSON或HTML模板。这些是对象关联，不是图片里的运行流水线。

调用者已有完成检查的包时，复用它即可，不要为了每个函数重新解析并检查整个包。示例源码没有 import，因此没有配置导入器；真实工程包含依赖时，应在工程已有的包加载与类型检查流程中取得目标包，不能直接把这个单文件小例子当成完整模块加载器。

如果面向当前包生成简短类型名，可提供 Qualifier：当前包返回空前缀，外部包返回统一选择的名称或路径。路径更明确，包名更简短；同名外部包需要额外消歧。不要在每条记录里临时采用不同的显示规则。

接入文档任务时处理失败和空结果

文档任务可以在源码变更后触发，并把错误返回给调度方。这个只读收集器不需要运行被分析业务代码；输出写入目录的权限与源码访问权限分别安排。若对外生成HTML，要由模板正常转义 Name 和 TypeText，别把包含尖括号的类型文本直接当成标记拼接。

能否按变量名合并相同类型？不宜。返回位置是对外约定的一部分，合并会改变读者看到的项数。模板可缩短重复描述，但中间记录应保持逐项完整。

是不是必须使用新版迭代器接口？不是。本例使用 Len 与 At，直接表达位置关系，也便于需要稳定支持范围的工具采用。选择其他遍历写法时仍要保留位置和顺序。

Tuple 接口参考：https://pkg.go.dev/go/types#Tuple；实现中的空元组与下标处理：https://go.dev/src/go/types/tuple.go。类型记录只描述返回声明，业务含义的文字说明仍需作者或项目文档补充。