Go go/ast 怎样把语法节点映射回源文件位置

我在写 Go 源码分析工具时，最容易混淆的一件事，是把 ast.Node.Pos() 返回的 token.Pos 当成了行号。它其实只是当前 token.FileSet 中的抽象偏移；要得到文件名、行号和列号，还要交给同一个 FileSet 做位置转换。

实用写法是：解析文件时保存 token.FileSet，遍历节点时取 node.Pos()，再调用 fset.Position(node.Pos())。如果需要忽略 //line 指令的调整，则改用 fset.PositionFor(pos, false)。

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

先把 Pos 转成 token.Position

go/ast 的节点只暴露位置接口，不负责把位置格式化成文件名和行列。Pos() 返回的是 token.Pos，End() 返回节点结束位置。两者都必须和创建它们时使用的同一个 token.FileSet 配合。

package main

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

func main() {
    source := `package demo

func add(left, right int) int {
    total := left + right
    return total
}`

    // FileSet 必须贯穿解析和位置转换，不能在遍历时临时新建。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", source, 0)
    if err != nil {
        panic(err)
    }

    ast.Inspect(file, func(node ast.Node) bool {
        ident, ok := node.(*ast.Ident)
        if !ok || ident.Name != "total" {
            return true
        }

        // Pos 只是 FileSet 内的抽象位置，Position 才会补齐文件名和行列。
        position := fset.Position(ident.Pos())
        fmt.Printf("%s:%d:%d %s\\n", position.Filename, position.Line, position.Column, ident.Name)
        return true
    })
}

这里的关键顺序只有两步：节点提供 token.Pos，FileSet.Position 将它映射为 token.Position。后者包含 Filename、Offset、Line 和 Column，因此适合直接拼成诊断消息或编辑器跳转位置。

FileSet.Position 和 File.Position 分别做什么

大多数场景只需要 fset.Position(pos)。它会在 FileSet 中找到包含该位置的 token.File，再把文件内的偏移换成可读位置。想把这个过程拆开理解，可以显式取出文件对象：

func describePosition(fset *token.FileSet, pos token.Pos) (token.Position, bool) {
    // 先确认抽象位置属于哪个文件，便于处理 NoPos 或错误来源。
    file := fset.File(pos)
    if file == nil {
        return token.Position{}, false
    }

    // File.Position 使用默认的 adjusted=true 规则生成展示位置。
    return file.Position(pos), true
}

FileSet.Position 是面向调用者的快捷入口；FileSet.File 让你看到位置归属的文件；token.File.Position 则在单个文件的边界内完成行列换算。三者并不是三套坐标，而是同一套 token.Pos 坐标的不同访问层次。

这对多文件 AST 工具很重要。比如一次解析包时，多个源文件可以共用一个 FileSet；每个文件会有自己的文件名和基准位置。只要不把不同 FileSet 创建的 token.Pos 混在一起，最终的 Filename 就能跟着位置回到正确的源文件。

需要物理位置时使用 PositionFor

默认的 Position 会按调整规则返回展示位置。源码中出现 //line 指令时，展示给用户的文件名、行号或列号可能被指令改写；这对生成器和诊断工具很有用，但不一定等于当前文件的物理坐标。

func positions(fset *token.FileSet, pos token.Pos) (token.Position, token.Position) {
    // adjusted=true 适合遵循源码中的 //line 指令给用户报错。
    adjusted := fset.PositionFor(pos, true)

    // adjusted=false 保留当前源文件的物理文件名和行列坐标。
    physical := fset.PositionFor(pos, false)
    return adjusted, physical
}

可以把选择规则记成一句话：编译器式诊断通常关心调整后的展示位置，源码重写、格式化或字节级索引通常关心物理位置。不要在一个工具里一会儿使用 Position，一会儿使用 PositionFor(pos, false)，却不在输出结构中说明坐标口径。

用 Pos 和 End 标记节点范围

只打印起点适合日志，但错误高亮、重构和代码操作往往还需要结束点。AST 节点的 End() 表示节点范围的末端位置，通常可以和 Pos() 一起转换为起止区间。

func nodeRange(fset *token.FileSet, node ast.Node) (token.Position, token.Position, bool) {
    if node == nil {
        return token.Position{}, token.Position{}, false
    }

    // 起点和终点必须使用同一个 FileSet，才能保持坐标口径一致。
    start := fset.Position(node.Pos())
    end := fset.Position(node.End())
    return start, end, true
}

实现高亮时还要注意：End() 更像范围的右边界，不是“最后一个字符所在列”的重复表达。若后续要截取原文，通常还会使用 Position.Offset 与原始字节切片配合，而不是只用行列再反推字节位置。

几个容易让位置错位的边界

最后记住这条位置转换链

我现在给 AST 工具加位置输出时，会把坐标链显式写在代码旁边：ast.Node.Pos() 得到 token.Pos，FileSet.File(pos) 负责确认文件归属，FileSet.Position(pos) 或 PositionFor 负责得到文件名、行号、列号和偏移。需要范围时再补上 End()。

这套分层的好处是，节点遍历不需要知道文件如何编号，位置展示也不需要猜节点类型。只要统一保存 FileSet，并明确是否遵循 //line 调整，源码分析工具的跳转和诊断就不容易出现“看起来只差一行”的错位。

常见问题

ast.Node.Pos() 能直接得到行号吗？

不能。它返回 token.Pos，需要交给创建 AST 时使用的 token.FileSet，例如调用 fset.Position(node.Pos())。

什么时候应该用 PositionFor(pos, false)？

当你需要源文件的物理坐标，例如源码重写、格式化、字节切片索引或与原始文件偏移对齐时使用。面向用户的诊断通常更适合默认的 adjusted 位置。

为什么不直接用行号和列号截取源码？

行列是展示坐标，列还涉及 UTF-8 字节语义；截取源码更稳妥的做法是使用 token.Position.Offset 配合原始字节，再把行列用于提示和定位。