Go 长驻分析工具怎样从 FileSet 移除不再使用的文件

我在做长驻源码分析工具时，最容易被忽略的不是解析速度，而是 token.FileSet 会持续记住遇到过的文件。工具每轮扫描一批新文件，旧代码只调用 AddFile，运行几个小时后，文件位置表和相关对象会一起变成常驻内存。

Go 1.20 起，FileSet.RemoveFile 可以移除一个已经不再使用的 *token.File。它的关键语义是：移除后，该文件对应的 token.Pos 区间不再属于这个 FileSet；它不是“清空并复用位置编号”，也不会让 FileSet.Base() 倒退。

正确做法是把文件处理拆成“解析并消费、保存必要诊断、释放 AST 与位置引用、RemoveFile”四个阶段。只要后续还要把某个 token.Pos 转回文件名和行列，就不能提前移除。

先看清 FileSet 为什么会一直变大

FileSet.AddFile 会为文件建立连续的位置区间，下一次可用的 base 至少是 base + size + 1。文件从集合中移除后，这个历史位置空间仍然单调向前增长；被回收的是集合中的文件索引和行偏移表，不是让旧位置重新分配给新文件。

因此，适合回收的是“已经完成本轮分析、后续不会再查询位置”的文件。解析出来的 AST、诊断对象、缓存的 token.Pos，甚至闭包里捕获的 *token.File 都要先处理或丢弃。否则你可能得到一个看起来还保存着位置、但 fset.Position(pos) 已经返回零值的诊断。

把旧处理路径迁移成可回收生命周期

迁移时不要把 RemoveFile 放在 ParseFile 后面立即调用。先完成本轮所有需要位置的工作，再集中生成可以脱离位置对象的结果，例如文件名、行号、列号和错误文本。

package analyzer

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

// analyzeOne 只返回已经格式化的诊断，避免结果继续依赖 token.Pos。
func analyzeOne(fset *token.FileSet, filename string, src []byte) ([]string, *token.File, error) {
    // 解析阶段把 AST 和位置表绑定到同一个 FileSet。
    file, err := parser.ParseFile(fset, filename, src, parser.ParseComments)
    if err != nil {
        return nil, nil, err
    }
    tokFile := fset.File(file.Pos())
    if tokFile == nil {
        return nil, nil, fmt.Errorf("找不到文件位置表: %s", filename)
    }

    var reports []string
    // 消费位置之前，把它转换成独立的文本结果。
    ast.Inspect(file, func(n ast.Node) bool {
        if n == nil {
            return true
        }
        pos := fset.Position(n.Pos())
        if pos.IsValid() && pos.Line == 1 {
            reports = append(reports, fmt.Sprintf("%s:%d:%d", pos.Filename, pos.Line, pos.Column))
        }
        return true
    })

    // AST 后续不再使用；调用方应在返回后释放本轮引用，再移除 tokFile。
    return reports, tokFile, nil
}

// analyzeStream 展示一个长驻工具的逐文件回收边界。
func analyzeStream(inputs map[string][]byte) ([]string, error) {
    fset := token.NewFileSet()
    var all []string
    for filename, src := range inputs {
        reports, tokFile, err := analyzeOne(fset, filename, src)
        if err != nil {
            return nil, err
        }
        all = append(all, reports...)

        // 位置已经被转换成字符串，当前文件不再参与后续查询。
        fset.RemoveFile(tokFile)
    }
    return all, nil
}

示例的重点不是用 Base()-1 作为通用定位技巧，而是说明回收动作必须拿到本轮实际的 *token.File。生产代码应在解析时保存返回的文件句柄，或通过明确的文件生命周期结构传递它；不要依赖位置猜测来找“最近文件”。

迁移前后，哪些行为真正发生了变化

我更推荐把回收逻辑放在一个小的生命周期对象里，而不是让业务函数到处直接调用 RemoveFile。这样迁移审查时可以逐项确认：位置是否已经物化为文本、AST 是否仍被缓存、异步任务是否还会回调。

不要在这几种场景中过早 RemoveFile

第一，诊断队列还只保存 token.Pos，没有保存文件名和行列。第二，后续阶段还要用同一个 AST 做类型检查、格式化或重写。第三，异步 worker 仍可能收到这个文件的任务。第四，工具需要把多个文件的 Pos 放在同一个 FileSet 中比较，并且比较工作尚未结束。

还要留意一个容易误解的点：移除不存在于集合的文件不会报错；移除后对原位置区间做查询会得到找不到文件的结果。这个“安静失败”适合幂等清理，但不适合拿来掩盖生命周期错误。对关键路径，应该在内部状态中标记文件是否已经释放。

如果工具只是一次性读取少量文件，建立一个新的 FileSet 通常比设计复杂回收更简单。RemoveFile 真正有价值的场景，是持续接收不受上限约束的文件流、批量语言服务或长时间运行的源码索引器。

迁移后的回归清单

1. 每个文件都能找到唯一的 *token.File 生命周期记录。
2. 所有要展示给用户的诊断，在移除前已经转换为稳定文本。
3. AST、注释和位置对象没有被长期缓存，或明确标注为未释放。
4. 异步任务完成后才执行清理，并且清理动作可以重复调用。
5. 新增文件继续使用 fset.Base() 或负 base 规则，不依赖旧位置编号回收。

相关问题：

• RemoveFile 会重置 FileSet.Base 吗？不会，下一文件的 base 仍然向前推进。
• 移除后还能用旧 token.Pos 吗？可以保存数值，但不能再依赖这个 FileSet 把它解析成位置。
• FileSet 适合做全局永久缓存吗？如果文件流无界，应该配合文件生命周期回收，或按任务拆分 FileSet。