Go go/token.FileSet.File 怎样查询源码位置

在 Go AST、格式化工具或静态分析器里，token.Pos 只是一个位置值，不能直接告诉你文件名、行号和列号。真正的查询入口是产生这些位置的同一个 token.FileSet：先用 FileSet.File(pos) 找到所属的 token.File，再用 File.Position(pos) 或 FileSet.Position(pos) 展开成可读位置。

官方文档：https://pkg.go.dev/go/token#FileSet.File

先分清三个对象的职责

token.Pos 记录的是位置，token.File 记录某个源文件在位置集合中的起点、大小和行信息，token.FileSet 则管理多个文件。它们不是可以随意替换的三种写法。

FileSet.File(pos) 的用途是定位文件记录；如果要一次得到文件名、行号、列号和偏移，可以直接调用 FileSet.Position(pos)。若已经拿到了 *token.File，则使用它的 Position(pos) 更适合表达“在这个文件里解释位置”。

让 parser 和查询共用一个 FileSet

最常见的空结果原因不是 API 写错，而是解析时创建了一个 FileSet，查询时又新建了另一个。下面的示例让解析器、AST 节点和位置查询始终共享同一对象。

package main

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

func main() {
    const source = "package demo\n\nfunc run() {}\n"

    fset := token.NewFileSet()
    // 解析时传入 fset，AST 中的 token.Pos 才能被这套 FileSet 解释。
    file, err := parser.ParseFile(fset, "demo.go", source, 0)
    if err != nil {
        fmt.Println("parse error:", err)
        return
    }

    pos := file.Decls[0].Pos()
    // FileSet.Position 会把 Pos 展开为文件名、行列和字节偏移。
    position := fset.Position(pos)
    fmt.Printf("%s:%d:%d offset=%d\\n", position.Filename, position.Line, position.Column, position.Offset)
}

这里的关键不是 Position 方法本身，而是 pos 和 fset 来自同一次解析。输出中的 Offset 从零开始，行列信息则由 token.File 保存的行表换算而来。

用 FileSet.File 判断位置是否属于某个文件

当工具需要先判断位置是否落在已登记文件中，可以先取 *token.File。命中后再读取文件名、起止范围，能把“没有位置”和“位置不属于这个文件集”区分开。

func describePosition(fset *token.FileSet, pos token.Pos) string {
    // NoPos 不代表某个文件的开头，先单独处理无效位置。
    if !pos.IsValid() {
        return "invalid position"
    }

    file := fset.File(pos)
    // FileSet.File 找不到记录时返回 nil，通常意味着 FileSet 不匹配。
    if file == nil {
        return "position is outside this file set"
    }

    p := file.Position(pos)
    return fmt.Sprintf("%s:%d:%d offset=%d", p.Filename, p.Line, p.Column, p.Offset)
}

FileSet.File 找不到记录时返回 nil。不要在返回值上直接调用 Position，否则排障工具本身会因为空指针掩盖原始问题。

File.Position、File.Offset 和 FileSet.Position 怎么选

如果代码正在遍历 AST，通常直接使用 fset.Position(node.Pos()) 就够了；如果要做范围判断、显示文件大小或检查某个位置是否属于指定文件，再显式保存 *token.File。

三个容易误判的边界

• 不要混用 FileSet：一个解析器产生的 token.Pos 交给另一套 FileSet 查询，不能得到可靠文件位置。
• 区分 NoPos：token.NoPos 的 IsValid() 为假，它不是第一个文件的合法起点。
• 注意位置范围：文件的 Base()、Size() 和 End() 决定位置范围；工具应在边界处保留 nil 或无效位置分支。

结语

记住一条链路就够了：token.Pos → FileSet.File(pos) → token.File → Position/Offset。查询文件名和行列时优先复用产生位置的原始 FileSet；需要排障时先检查 IsValid 和 nil，再把位置展开到日志。

常见问题

为什么 FileSet.File(pos) 返回 nil？通常是位置来自另一套 FileSet，或位置本身超出了当前文件集合。

File.Position 和 FileSet.Position 有什么区别？前者依赖你已经选定的文件，后者由 FileSet 先完成跨文件定位。

Offset 是字节还是字符？它表示源文件中的字节偏移，不应直接当作 Unicode 字符数量使用。