Go ast.FilterFile 过滤声明时为什么会删除导入

如果你用 Go AST 做文档提取、导出视图或声明裁剪，调用 ast.FilterFile 后发现 file.Imports 变空，通常不是过滤器写错了。FilterFile 的官方语义就是：按过滤器裁剪顶层声明中的名称，同时始终移除导入声明；它还会原地修改传入的 *ast.File，但不会同步删除 File.Comments。

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

先看现象：过滤器没有保留导入的入口

最容易产生误解的地方是 FilterFile 接受一个 Filter 函数。读者会自然地认为：只要过滤器不处理导入名，导入就应该留下。但官方文档把导入声明单独列为固定规则：导入声明总会被移除，过滤器只参与顶层声明中的名称筛选。

因此，下面三件事要分开记：

• FilterFile 过滤的是声明中的名称，不是一个通用的 AST 节点保留回调。
• 导入声明不会进入“是否通过过滤器”的保留决策，调用后会从文件的声明和导入集合中消失。
• File.Comments 列表不因声明被裁剪而自动清空，后续打印或分析时仍要单独判断注释归属。

把一份源文件拆成三个观察面

为了定位误解，可以准备一个包含导入、结构体字段和函数的源文本。下面的示例只展示 API 边界，重点是观察 ast.File 的三个集合：顶层声明、导入声明和注释列表。示例没有把输出当作运行截图；实际工具应在自己的处理链路中记录这些集合的变化。

package main

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

func main() {
    source := `package demo

import "net/http"

// Config 保存服务配置。
type Config struct {
    Public string
    private int
}

func Visible() {}
func hidden() {}
`

    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", source, parser.ParseComments)
    if err != nil {
        // 解析错误必须交给上层，否则后面的 AST 集合没有意义。
        panic(err)
    }

    // 过滤器只保留指定名称；FilterFile 仍会固定移除导入声明。
    hasDecl := ast.FilterFile(file, func(name string) bool {
        return name == "Config" || name == "Public" || name == "Visible"
    })

    // 这里观察集合边界，不把注释数量误当成导入是否保留的依据。
    fmt.Println(hasDecl, len(file.Decls), len(file.Imports), len(file.Comments))
}

这个例子里的过滤器允许 Config、Public 和 Visible 通过，因此相关声明名称有机会留下；private 和 hidden 不通过。无论过滤器是否提到 net/http，导入声明都不属于保留范围。函数返回的布尔值表示过滤后是否还存在顶层声明，而不是“是否还剩导入”。

真正的裁剪边界：字段会参与，参数不会参与

FilterFile 的名称过滤范围比很多人预期的更深。它会处理顶层声明里的名称，包括结构体字段和接口方法名；但参数列表中的参数名不在这条裁剪范围内。也就是说，写一个只保留导出名的过滤器时，导出类型的未导出字段仍可能被裁掉，而函数参数不会因为参数名未通过就被删除。

为什么它会原地改变文件，而不是返回新文件

FilterFile 的返回值是一个布尔结果，不是新的 *ast.File。传入的文件树会被就地裁剪，调用前保存的 file 指针仍然指向同一棵已经改变的树。因此，如果后续阶段还要打印完整源码、读取原始导入或进行第二种过滤，不能先无保护地调用它。

更稳妥的做法有三种：

1. 在过滤前先从 file.Imports 记录需要的导入信息，再把裁剪后的树交给后续阶段。
2. 把“保留完整 AST”和“生成裁剪视图”拆成两棵树，必要时从同一份源文本重新解析。
3. 如果目标只是筛选名称，不需要改变原树，可以遍历并收集匹配节点，而不是直接调用会修改树的 API。

func filterView(source string) (*ast.File, []string, error) {
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "input.go", source, parser.ParseComments)
    if err != nil {
        // 返回解析错误，避免调用方拿到半成品 AST。
        return nil, nil, err
    }

    // 在原地裁剪前复制导入路径，后面仍可用于展示或重新组装。
    imports := make([]string, 0, len(file.Imports))
    for _, spec := range file.Imports {
        imports = append(imports, spec.Path.Value)
    }

    // 只生成名称视图；完整导入信息已经被单独保存。
    ast.FilterFile(file, func(name string) bool {
        return ast.IsExported(name)
    })
    return file, imports, nil
}

这段代码的关键不是“把导入重新塞回 AST”，而是承认两个结果有不同用途：裁剪后的 *ast.File 用于导出视图，复制出的路径列表用于目录、摘要或后续重组。若要继续输出合法且完整的 Go 源码，还要根据目标格式重新处理导入和注释，不能只依赖已经裁剪的文件树。

调用前后怎么判断结果是否符合预期

排查时可以按下面顺序看，不需要把“导入被删除”当成异常：

1. 先确认调用的是 ast.FilterFile，而不是只遍历节点的 ast.Inspect。
2. 确认过滤器只表达名称保留规则，没有把导入路径当成普通声明名处理。
3. 用返回值判断过滤后是否还存在顶层声明，不要用 len(file.Imports) 判断过滤是否成功。
4. 如果后续依赖注释，单独检查 file.Comments 和节点的 Doc、Comment 字段。
5. 如果同一棵树还要用于完整源码输出，改成提前记录导入或重新解析，而不是重复调用过滤器。

相关问题

FilterFile 能不能只删除未导出顶层函数？

不能把它理解成只针对函数。它会处理顶层声明中的多种名称，也可能继续影响结构体字段和接口方法；如果只想收集函数，应使用遍历收集策略。

导入被删除后，File.Comments 会一起消失吗？

不会。官方文档明确说明 File.Comments 列表不被改变，但注释是否仍对应一个存在的节点，需要调用方自己判断。

FilterFile 的返回值代表什么？

它表示过滤后是否还有顶层声明，不表示导入是否保留，也不表示注释和节点的关联已经完成整理。

怎样保留完整导入又生成导出视图？

在调用前记录导入信息，或从同一源文本重新解析一棵用于裁剪的 AST。这样完整树和导出视图各自承担单一职责。