Go token.FileSet.PositionFor 怎么解析行列位置

在 Go AST 分析、静态检查或源码索引里，节点通常只带一个紧凑的 token.Pos。它不是可以直接打印的“第几行第几列”，而是 FileSet 中的统一位置编号。要得到可读的文件名、字节偏移、行号和列号，应调用 fset.PositionFor(pos, adjusted)。

最容易混淆的是第二个参数：adjusted=false 返回物理源码位置，忽略会改变位置的 //line 指令；adjusted=true 会应用这些指令。普通场景下 fset.Position(pos) 等价于 PositionFor(pos, true)。

PositionFor 返回的不是单个行号

token.Position 包含四个有用字段：Filename 是文件名，Offset 是从文件开头开始的字节偏移，Line 是从 1 开始的行号，Column 是从 1 开始的列号。这里的列不是 Unicode 字符数，而是字节计数，所以包含多字节 UTF-8 字符时，不要拿它直接当作字符串的 rune 下标。

FileSet 为每个文件分配不重叠的整数区间：int(pos) = base + offset。因此多个文件可以共享一个集合，AST 节点只需携带 Pos，转换时由集合找到它所属的文件。

从 AST 节点解析出文件名、行号和列号

实际使用时，把创建 FileSet 和解析源码放在同一条链路中。节点的 Pos() 只提供紧凑位置，真正展示给用户时再转换：

package main

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

func main() {
	// 用同一个 FileSet 接收解析器产生的位置。
	fset := token.NewFileSet()
	const src = `package demo

//line virtual.go:40:3
var answer = 42
`

	file, err := parser.ParseFile(fset, "physical.go", src, 0)
	if err != nil {
		// 解析失败时没有可靠的 AST 位置，先返回错误。
		fmt.Println(err)
		return
	}

	for _, decl := range file.Decls {
		pos := decl.Pos()
		// true 应用 //line 映射，false 保留物理源码位置。
		logical := fset.PositionFor(pos, true)
		physical := fset.PositionFor(pos, false)
		fmt.Printf("logical=%s physical=%s\\n", logical, physical)
	}
}

这段代码的关键不是遍历声明，而是保持 pos、fset 和转换调用属于同一解析上下文。若把节点位置交给另一个 FileSet，结果就没有可解释的文件区间对应关系。

adjusted 参数决定是否采用 //line 映射

//line filename:line:column 常见于生成代码、模板展开或编译器测试。它可以让逻辑位置指向生成前的源文件。使用 PositionFor(pos, true) 时，返回的 Filename、Line 和 Column 可能与物理文本不同；传入 false 则忽略这类位置调整。

越界、NoPos 和多字节列号的处理边界

传入的 p 应该属于当前文件或是 token.NoPos。NoPos 对应无效的零值 Position，不能把它当作第一行第一列。对于超出文件范围的位置，PositionFor 会按 File.Offset 的规则调整到边界；这能避免无意义的负偏移，但不能替代调用方对位置来源的检查。

如果只想知道某个位置属于哪个文件，可以先调用 fset.File(pos)；需要可复制的错误信息时，再格式化完整的 Position。对于中文源码，记住 Column 是字节列，若业务界面要求按字符移动光标，应另行把文件内容转换为 rune 索引。

常见问题

FileSet.Position 和 PositionFor 有什么区别？

FileSet.Position(pos) 固定采用 adjusted=true。只有需要明确忽略或控制 //line 映射时，才直接调用 PositionFor。

为什么 PositionFor 得到的文件名和打开的文件不一样？

优先检查第二个参数和源码中的 //line 指令。传入 true 时文件名可能是逻辑源文件；传入 false 才能看到物理文件坐标。

Column 能直接作为字符串下标吗？

不能。它从 1 开始且按字节计数；Go 字符串下标按字节从 0 开始，Unicode 字符显示宽度也不等于字节数。

把 PositionFor 当成“坐标转换层”即可：先保证 Pos 来自正确的 FileSet，再根据诊断目标选择 adjusted，最后分别处理字节偏移和可读行列，这样多文件 AST 和生成代码场景都不容易混淆。