Go types.Package.Scope 怎样列出包导出 API

如果你已经用 go/types 完成了一个包的类型检查，想把这个包对外提供的类型、常量、变量和函数列出来，最短路径是：先取 pkg.Scope()，再用 Names() 得到名称，用 Lookup() 取回对象，最后检查对象的 Exported() 和 Type()。

这里的关键是“包级”。Package.Scope() 保存的是包级声明，不是每个文件的局部作用域，也不是结构体的方法集。下面按一个小型 API 清单场景，把这套写法拆成可以直接放进分析工具的配方。

Package.Scope 到包级对象的最小配方

Package.Scope() 返回包级作用域，里面的对象类型主要包括 TypeName、Const、Var 和 Func。如果包对象还不完整，Scope 也可能是不完整的；因此自动生成 API 文档时，应把 pkg.Complete() 一并作为输入状态记录下来。

假设你已经从类型检查器拿到了 pkg *types.Package，最小入口就是这一行：

// pkg 是类型检查结果中的包对象，不是手工拼出的空 Package。
scope := pkg.Scope()

// Names 返回当前作用域中的名称，并且已经按名称排序。
names := scope.Names()
fmt.Println("package:", pkg.Path(), "complete:", pkg.Complete())
fmt.Println("names:", names)

Names() 的排序很有用：输出不会随着源文件声明顺序变化而变化，适合生成文档、做快照或比较两个包的 API 名单。但它只返回名字，不会直接告诉你每个名字是函数、类型还是常量。

用 Names 和 Lookup 拼出导出 API 清单

一个可复用的做法是遍历名称，再对每个名称调用 Lookup。Lookup 找不到对象时返回 nil，所以保留这个判断可以让代码对不完整或人工构造的 Scope 更稳妥。

// ExportedAPI 把包级导出对象转换成稳定的展示数据。
type ExportedAPI struct {
	Name string
	Kind string
	Type string
}

func ListExportedAPI(pkg *types.Package) []ExportedAPI {
	if pkg == nil {
		// nil 包对象没有可列出的业务 API，避免继续解引用。
		return nil
	}

	scope := pkg.Scope()
	result := make([]ExportedAPI, 0, scope.Len())
	for _, name := range scope.Names() {
		// Names 已排序，因此 result 的顺序天然稳定。
		obj := scope.Lookup(name)
		if obj == nil || !obj.Exported() {
			// 小写名称或缺失对象不属于对外 API。
			continue
		}

		result = append(result, ExportedAPI{
			Name: obj.Name(),
			Kind: reflect.TypeOf(obj).String(),
			Type: types.TypeString(obj.Type(), nil),
		})
	}
	return result
}

这段代码需要导入 fmt、reflect 和 go/types。reflect.TypeOf(obj).String() 只是为了在示例中显示对象实现类型；如果你的输出协议不需要这个字段，可以把 Kind 去掉，保留 Name 与 Type。

为什么要同时使用 Exported、Name 和 Type

Names() 只负责列举作用域中的名字；它不会替你完成 Go 语言的导出判断。导出判断应该交给对象的 Exported() 方法，它依据标识符是否以大写字母开头判断，而不是依据你当前运行工具的包路径。

取到对象后，三个字段的用途可以这样分工：

不要把 obj.String() 当成稳定的机器协议。它更适合调试或人读的日志；如果要存储 API 索引，建议单独保存名称、对象类别和类型字符串，并自行定义版本化格式。

前端配方式变体：只查一个导出名称

如果页面只需要判断某个 API 是否存在，没有必要先遍历全部名称。直接调用 Lookup 即可；这样也能把“是否存在”和“是否导出”放在一个清晰的判断中。

func FindExported(pkg *types.Package, name string) (types.Object, bool) {
	if pkg == nil {
		// 空包对象没有可查询的作用域。
		return nil, false
	}

	obj := pkg.Scope().Lookup(name)
	if obj == nil || !obj.Exported() {
		// 未声明、未导出都按“不可作为公开 API 使用”处理。
		return nil, false
	}
	return obj, true
}

这个变体适合文档站的单项查询、补全提示或 API 兼容性比较。若要批量生成目录，仍然优先选择 Names()，因为它给出的排序由 go/types 负责，不需要在业务层重复排序。

几个容易踩到的边界

• Scope 不是所有可见成员。 它表示包级声明；结构体字段和方法需要通过类型信息、方法集或选择器相关 API 另行分析。
• Scope 不等于文件 Scope。 多个源文件的包级声明会汇总到同一个包 Scope 中，不能用文件遍历次数推断 API 数量。
• 不完整包要标记状态。 官方文档说明，包完整时 Scope 至少包含全部导出对象；不完整包不应该被当成完整 API 清单。
• 不要用声明顺序当稳定顺序。 使用 Names() 的排序结果，再根据名称查对象。
• nil 接收者有特殊语义。 官方文档规定，nil 的 Package.Scope() 返回 Universe Scope；业务代码仍建议显式检查 nil，避免把预声明标识符误当成目标包 API。

一张速查表

所以，标题问题的最终配方可以压缩成：pkg.Scope().Names() 负责稳定枚举，scope.Lookup(name) 负责取回对象，obj.Exported() 负责公开性判断，obj.Type() 负责类型展示。把 pkg.Complete() 一并记录，生成的 API 清单才不会把“不完整”误报成“没有”。

相关问题

Scope.Names 会返回未导出的名称吗？

会。它返回当前作用域中的全部元素名称，导出过滤要在取回对象后使用 Exported() 完成。

怎样读取一个函数的参数和返回值？

先通过 Lookup 得到对象，再把 obj.Type() 断言或处理为 *types.Signature，然后读取参数和结果元组。

Package.Scope 能列出结构体方法吗？

不能直接列出。Package.Scope 保存包级声明；结构体方法属于类型的方法信息，应围绕具体命名类型和方法集单独查询。

为什么 API 清单有时比源文件里的导出声明少？

优先检查 pkg.Complete()、导入器返回的数据是否完整，以及你是否把文件级或构建条件下的声明混在了比较范围里。不要先假设是 Names() 丢了数据。