Go ast.FileExports 怎样只保留导出的语法树节点

如果你在写 Go 文档生成器、接口摘要工具或源码索引器，常见需求不是保留完整实现，而是从语法树里留下“别人能调用什么”。go/ast.FileExports正好处理这件事：它会在原来的ast.File上就地裁剪，只保留导出的声明，并继续移除导出类型内部的非导出字段和方法。

官方文档：https://pkg.go.dev/go/ast#FileExports

FileExports适合生成公开 API 形状的 AST 摘要，但它不是深拷贝，也不是类型检查器。调用前要接受“原树会被修改”，调用后还要注意函数体、注释列表以及返回值的边界。

解析源码并观察 FileExports 的职责

完整流程可以拆成四步：用parser.ParseFile把源码解析为*ast.File，调用ast.FileExports原地裁剪，再用format.Node或go/printer把剩下的节点输出。FileExports接收的是指针，因此它直接修改传入的 AST；如果后面还要使用完整树，应在调用前自行保留另一份输入或重新解析。

package main

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

func main() {
	// 这个源码同时包含公开和私有声明，用来观察裁剪前后的差异。
	src := `package sample

const PublicLimit = 10
const privateLimit = 1

type PublicConfig struct {
	Name string
	secret string
}

func PublicRun() { println("implementation") }
func privateRun() {}
`

	// FileSet 保存 AST 的位置信息，ParseFile 返回可继续处理的语法树。
	fset := token.NewFileSet()
	f, err := parser.ParseFile(fset, "sample.go", src, parser.SkipObjectResolution)
	if err != nil {
		// 解析失败时不能继续裁剪，否则后续输出没有可靠输入。
		panic(err)
	}

	// FileExports 会直接修改 f；返回值表示裁剪后是否还有导出声明。
	hasExports := ast.FileExports(f)
	if !hasExports {
		fmt.Println("没有导出声明")
		return
	}

	// format.Node 根据 fset 和裁剪后的 AST 生成可读的 Go 源码。
	var out bytes.Buffer
	if err := format.Node(&out, fset, f); err != nil {
		// 输出阶段也可能失败，调用方应保留错误而不是发布半截摘要。
		panic(err)
	}
	fmt.Print(out.String())
}

这段程序的关键不在于打印本身，而在于数据流：FileExports改变的是f.Decls及其子节点，format.Node只是把当前树重新排版。返回false时表示没有导出声明留下来，调用方可以跳过空的公开 API 文件。

裁剪顶层非导出声明

Go 的导出规则以标识符首字母是否为大写为基础。调用FileExports后，顶层未导出的常量、变量、类型和函数会被移除；导出的声明保留，但其内部仍会继续按导出规则裁剪。

上面的输入经过处理后，结果可以理解为下面的公开 API 轮廓：

package sample

const PublicLimit = 10

type PublicConfig struct {
	Name string
}

func PublicRun()

示例中的privateLimit和privateRun不会进入结果，PublicConfig.secret也会被删除。PublicRun的名字和签名仍然有价值，但函数实现不是公开 API 形状的一部分，因此函数体会被清掉。

要注意“只剩导出节点”并不等于“输出一定能直接编译”。摘要保留的是文档或索引需要的结构，有些实现细节、引用关系和上下文已经被刻意省略。若你的下游任务是类型检查、依赖分析或代码生成，应把它当作 AST 预处理步骤，而不是完整源文件替代品。

处理导出类型内部的字段与方法

最容易漏掉的边界在导出类型内部。FileExports不仅过滤顶层声明，还会剥离导出类型的非导出字段和方法。对于导出的函数，函数体也会清空；对于接口或结构体，公开成员仍可形成可读的 API 轮廓。

package sample

import "fmt"

type PublicService struct {
	Name   string
	secret int
}

// PublicMethod 的签名对调用方有用，但实现细节不属于 API 摘要。
func (s *PublicService) PublicMethod(input string) error {
	// 这里的业务步骤会在 FileExports 后被移除。
	if input == "" {
		return fmt.Errorf("empty input")
	}
	return nil
}

func (s *PublicService) privateMethod() {}

经过裁剪后，概念上的结果是：

type PublicService struct {
	Name string
}

func (s *PublicService) PublicMethod(input string) error

这里的代码块是结果示意，省略了不再需要的导入和实现。实际工程中，若要把结果写成完整文件，应根据输出目标补齐包级上下文，并在发布前由自己的构建流程决定是否需要类型检查。

格式化裁剪后的 AST 并保留必要注释

如果只是把 AST 交给下一个 Go 工具，可以直接继续操作；如果要生成可阅读的摘要文件，通常使用go/format。它负责根据节点和位置信息排版，不会把被删掉的实现重新补回来。

package main

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

func exportSummary(src []byte) ([]byte, error) {
	// 解析注释，便于摘要工具决定哪些文档注释需要保留。
	fset := token.NewFileSet()
	f, err := parser.ParseFile(fset, "input.go", src, parser.ParseComments|parser.SkipObjectResolution)
	if err != nil {
		return nil, fmt.Errorf("parse source: %w", err)
	}

	// 这是破坏性变换；调用者不要再把 f 当作完整源码树使用。
	if !ast.FileExports(f) {
		return []byte("package summary\n"), nil
	}

	var buf bytes.Buffer
	// format.Node 只负责输出当前 AST；错误要向上传递，避免返回不完整结果。
	if err := format.Node(&buf, fset, f); err != nil {
		return nil, fmt.Errorf("format exported AST: %w", err)
	}
	return buf.Bytes(), nil
}

官方文档特别提醒，File.Comments列表不会因为FileExports裁剪节点而自动同步。简单摘要可以直接使用节点上挂着的文档注释；如果你做了多轮删除、移动或重排，建议用ast.NewCommentMap重新建立注释与节点的关联，再过滤不再属于结果树的注释。

还有一个实际限制：FileExports是原地操作。如果同一份源码既要生成完整 AST 索引，又要生成公开 API 摘要，不要先后在同一个*ast.File上调用两个流程；可以分别解析两次，或者在进入裁剪阶段前建立自己的数据模型。

选择 FileExports、FilterFile 还是类型检查

FileExports的规则固定、目标明确，适合快速得到“导出 API 轮廓”。如果你只想保留名称符合某个自定义条件的声明，可以使用ast.FilterFile，传入自己的过滤函数；它还会在顶层声明为空时移除声明，并且始终移除导入声明。

可以把选择逻辑压缩成一句话：要“公开形状”就用FileExports，要“自定义名称过滤”就用FilterFile，要“理解代码含义”就进入go/types。不要因为输出里出现了函数签名，就把它误认为已经完成了类型检查。

相关问题

FileExports 会返回一棵新的 AST 吗？

不会。它接收*ast.File并原地裁剪，返回值是bool，表示裁剪后是否还有导出声明。需要完整树时应提前复制自己的数据或重新解析源码。

导出函数的函数体会保留吗？

不会把实现体作为公开 API 摘要保留。导出函数的名称和签名有用，但函数体属于实现细节；导出类型内部的非导出字段和方法也会被删除。

FileExports 会自动清理 File.Comments 吗？

不会。官方文档明确说明评论列表不变。简单读取文档注释通常够用，复杂的节点删除或移动应配合ast.CommentMap重新过滤注释。

什么时候应该改用 FilterFile？

当“导出”不是你的唯一规则时。例如只保留名称带某个前缀、只保留特定声明类型，或需要自定义字段过滤，就应该使用FilterFile并自己提供过滤函数。