Go ast.FilterFile 怎样按条件筛选文件中的声明

如果你已经通过 go/parser 得到了一个 *ast.File，又只想保留符合条件的顶层声明，优先使用 ast.FilterFile。它会原地裁剪文件 AST：过滤顶层声明中的名字和相关字段，空声明会被移除，并返回过滤后是否还存在顶层声明。

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

最容易忽略的两个边界是：Import 声明总会被移除，File.Comments 列表不会因为筛选而清空。因此它适合生成“公开 API 摘要”或源码索引中间结果，不适合当作完整源码副本。

FilterFile 先筛选什么

FilterFile(src, f) 的第一个参数是要被修改的 *ast.File，第二个参数是过滤函数。过滤函数接收当前名字和它对应的反射值，返回 true 表示保留。顶层函数名、变量名、类型名，以及结构体字段、接口方法名等都可能进入这个判断；函数参数列表不在这个名字过滤范围内。

这意味着过滤函数应该只依赖稳定的名字规则，例如导出性、命名前缀或项目自己的白名单。不要在回调里修改 AST 节点本身，否则阅读代码时很难区分“过滤”与“重写”的责任。

先把 Go 源码解析成 AST

下面的示例准备一个同时包含导出、未导出声明和结构体字段的文件。parser.ParseFile 负责建立 AST，token.FileSet 负责保存源位置。代码中的中文注释只解释关键参数和错误处理，不把每一行都重复翻译。

package main

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

func main() {
    src := `package sample

import "strings"

type Public struct {
    Keep string
    hidden int
}

type private struct{}

func Keep() string { return strings.TrimSpace(" ok ") }
func hidden() {}
`

    fset := token.NewFileSet() // 文件位置统一挂在同一个 FileSet 上。
    file, err := parser.ParseFile(fset, "sample.go", src, parser.ParseComments)
    if err != nil {
        // 解析失败时没有可安全过滤的 AST，直接结束当前处理。
        panic(err)
    }

    fmt.Println(file.Name.Name, len(file.Decls))
    _ = ast.FilterFile
    _ = reflect.ValueOf
}

解析阶段先不要调用过滤。保留原始 *ast.File，可以在调试时对比过滤前后的声明数量，也能在筛选规则改变时重新生成结果。

用 ast.IsExported 保留公开名字

如果目标是制作公开 API 摘要，可以直接把 ast.IsExported 作为名字判断。它只判断名字首字母是否为大写；结构体字段和接口方法也会遵循这个规则。

// 只保留导出名字；reflect.Value 参数用于满足 ast.Filter 类型签名。
keepExported := func(name string, _ reflect.Value) bool {
    return ast.IsExported(name)
}

hasDecl := ast.FilterFile(file, keepExported)
if !hasDecl {
    // 返回 false 表示过滤后没有顶层声明可继续处理。
    fmt.Println("没有可保留的顶层声明")
}

这里的关键不是“遍历后手动删除”，而是把保留条件交给 FilterFile。函数会从 AST 中移除不通过条件的名字；当一个声明已经没有内容时，该声明也会被移除。调用完成后，file 就已经是裁剪后的对象。

返回值怎样参与后续处理

FilterFile 的返回值是一个很实用的短路信号：true 代表仍有顶层声明，false 代表文件已经被裁剪到没有顶层声明。它不是“是否发生过修改”，也不是“语法是否有效”。

if ast.FilterFile(file, keepExported) {
    // 仍有声明时，可以继续做格式化、索引或文档提取。
    if err := ast.Print(fset, file); err != nil {
        // 输出阶段的错误与筛选结果分开处理。
        panic(err)
    }
} else {
    // 没有顶层声明时，按业务需要跳过空结果。
    fmt.Println("过滤结果为空")
}

如果要输出成 Go 源码，通常应交给 go/format 或 go/printer，并根据你的目的补回需要的导入。上面的 ast.Print 更适合观察树结构，不等价于源码格式化。

导入和注释是两个特殊边界

官方文档明确规定，Import 声明总会被 FilterFile 移除，File.Comments 列表则不会被修改。也就是说，筛选后的 AST 仍可能带着原注释，但不能假设原始导入列表还在。

因此可以按用途分成两条路径：

• 做 API 文档、符号索引或结构分析：直接消费裁剪后的声明，导入缺失通常不是问题。
• 要重新生成可编译源码：把过滤结果当作中间 AST，重新整理导入和依赖，不要把它当成完整文件。

自定义 Filter 时避免三个误区

误区一：把它当成复制函数

FilterFile 会直接修改传入的 AST。需要保留原始树时，最稳妥的方式是重新解析源码，或者在进入过滤前建立明确的副本策略；不要在过滤后再期待原对象恢复。

误区二：用反射值判断名字却忽略 nil

过滤器的第二个参数用于描述当前字段值。如果自定义规则确实要检查它，先判断 reflect.Value 是否有效，再按类型读取；仅按名字过滤时可以像上面的示例一样忽略它。

误区三：把空结果当作解析失败

返回 false 只说明没有保留的顶层声明。解析是否成功应由 parser.ParseFile 的错误决定，输出是否成功还要看后续打印或格式化步骤。

一句话总结

用 ast.FilterFile 做 Go 源码筛选时，先解析得到 *ast.File，再用一个只负责“保留还是删除名字”的 Filter 回调原地裁剪；用返回值判断是否还有顶层声明，并记住导入会被移除、注释列表会保留。这样可以把 AST 过滤和源码重写、格式化、类型检查清楚分层。

常见问题

FilterFile 会删除函数参数吗？

不会把参数列表当作普通名字列表过滤。它主要处理顶层声明以及相关字段和方法名，参数属于声明内部的参数结构。

FilterFile 会保留原来的 import 吗？

不会。Import 声明按接口约定总会被移除，重新生成可编译源码时应单独整理导入。

怎样只保留导出 API？

可以把 ast.IsExported 作为 Filter 回调的名字判断，再根据返回值决定是否继续打印或构建文档索引。