Go go/token.NewFileSet 怎样管理多个源码文件的位置

做 Go AST 分析时，单个文件里的节点位置并不难读，真正容易混乱的是“一个包里有多个文件”：同一个 token.Pos 只是位置值，不能直接当作某个文件的字节偏移。稳定的做法是创建一个 token.FileSet，让解析得到的多个 *ast.File 共用它，再通过 FileSet.Position 把节点位置还原成文件名、偏移、行号和列号。

记住三层关系：FileSet 管理一组文件，File 描述其中一个文件的范围，Pos 只是这个范围里的位置标识。解析多个文件时共享同一个 FileSet，跨文件位置映射才不会丢失上下文。

先区分 FileSet、File 和 Pos

token.NewFileSet() 返回一个空的 *token.FileSet。解析器把源码文件加入这个集合后，会得到对应的 *token.File；文件在集合中拥有一段不重叠的位置区间。AST 节点的 Pos() 和 End() 返回的是 token.Pos，它适合交给 FileSet 查询，不适合脱离 FileSet 单独解释。

用同一个 NewFileSet 解析多个源码文件

如果工具要分析一个包，建议先创建一次 FileSet，然后把它传给每次 parser.ParseFile。下面的例子用内存字符串模拟两个源码文件，重点是共享 fset，而不是把示例当成已经执行过的输出。

package main

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

func main() {
    // 同一个 FileSet 为两个源码文件提供统一的位置上下文。
    fset := token.NewFileSet()
    sources := map[string]string{
        "alpha.go": "package demo\nfunc Alpha() {}\n",
        "beta.go":  "package demo\nfunc Beta() {}\n",
    }

    for filename, source := range sources {
        // ParseComments 让后续工具仍能按需读取注释信息。
        file, err := parser.ParseFile(fset, filename, source, parser.ParseComments)
        if err != nil {
            // 解析错误要带上文件名，便于调用方定位输入。
            fmt.Printf("解析 %s 失败：%v\n", filename, err)
            continue
        }

        // 只示范位置映射，不在这里做类型检查或代码生成。
        ast.Inspect(file, func(node ast.Node) bool {
            if decl, ok := node.(*ast.FuncDecl); ok {
                position := fset.Position(decl.Pos())
                fmt.Printf("%s: %d:%d\n", position.Filename, position.Line, position.Column)
                return false
            }
            return true
        })
    }
}

这里的 FileSet 是跨文件共享的，但 Position 仍会返回具体文件名。这样做的好处是：调用方不用先猜这个 Pos 属于哪个文件，直接把节点位置交给集合即可。

用 Position 读取文件名、偏移和行列

fset.Position(pos) 返回 token.Position，里面最常用的是 Filename、Offset、Line 和 Column。当工具需要打印诊断信息时，优先把它格式化成“文件:行:列”，而不是输出 int(pos)；后者只有放回同一个 FileSet 才有意义。

func describeNode(fset *token.FileSet, node ast.Node) string {
    // NoPos 表示节点没有可用位置，不能继续当作普通坐标处理。
    if node == nil || !node.Pos().IsValid() {
        return "位置未知"
    }

    position := fset.Position(node.Pos())
    // Offset 从文件内容起点计数，Line 和 Column 更适合给人阅读。
    return fmt.Sprintf("%s:%d:%d (offset=%d)",
        position.Filename, position.Line, position.Column, position.Offset)
}

一个常见误区是把 token.Pos 直接减去某个文件的 Base()。这种做法只有在已经确认该位置属于这个文件时才有意义；更稳妥的是先调用 fset.File(pos) 找到文件，再使用 f.Position(pos) 或统一的 fset.Position(pos)。

需要手工注册文件时，怎样理解 AddFile

大多数解析任务不需要直接调用 AddFile，因为解析器会替你注册文件。只有在读取序列化的位置数据、拼接外部源码或构造工具内部索引时，才会手工添加文件。AddFile(filename, base, size) 的关键是文件区间不能重叠。

func registerFiles() (*token.FileSet, *token.File, *token.File) {
    fset := token.NewFileSet()

    // 传入负 base 时使用当前 FileSet.Base，size 是文件的字节长度。
    first := fset.AddFile("alpha.go", -1, 28)

    // 第二个文件从集合当前的 Base 开始，避免与第一个范围重叠。
    second := fset.AddFile("beta.go", -1, 31)

    // 返回 File 对象，后续可以用它们把文件内偏移转成 token.Pos。
    return fset, first, second
}

当 base 为负数时，FileSet 会使用当前的 Base()；加入一个大小为 size 的文件后，下一次可用基准至少会推进到“当前 base + size + 1”。如果手工传入 base，则必须保证它不小于集合当前基准，并且不能与已有文件重叠。

排查四类位置错误

• 把 Pos 当全局字节偏移：Pos 只在它所属的 FileSet 中解释，跨集合比较没有业务意义。
• 用了不同的 FileSet：解析和查询必须使用同一个集合，否则 FileSet.File 可能找不到对应文件。
• 手工范围重叠：自定义 AddFile 的 base 或 size 不正确时，位置可能落在错误文件或触发范围约束。
• 忽略 NoPos：某些 AST 节点没有有效位置，先调用 IsValid，再决定是否输出诊断。

如果只需要给用户显示错误位置，统一封装一个位置格式化函数即可；如果要做跨文件索引，则要同时保存 FileSet 和文件内容版本，避免后续源码变化后行列信息与旧 Pos 混用。

小结

token.NewFileSet 的价值不在于生成一个更大的整数空间，而在于把多个源码文件的范围、文件名和行列信息放在同一套可查询关系里。解析多个文件时共享 FileSet；输出诊断时用 Position；手工注册文件时控制 base 和 size；遇到异常位置先检查 NoPos、FileSet 是否一致以及文件范围是否重叠。

相关问题

为什么不能只保存 int(token.Pos)？

整数本身不包含文件名，也不能脱离原来的 FileSet 还原行列。应保存位置所属的 FileSet 或转换后的 token.Position。

parser.ParseFile 会自动加入 FileSet 吗？

传入 FileSet 时，解析器会在集合中登记源码文件，并让返回 AST 的位置使用这套集合。后续查询必须继续使用同一个 FileSet。

什么时候需要直接调用 AddFile？

普通源码解析通常不需要；当位置来自外部索引、序列化数据或自定义源码拼接器时，才需要手工控制文件名、基准偏移和大小。