Go go/token.FileSet.PositionFor 如何还原多文件错误位置：adjusted、相对偏移与诊断输出

编译器或静态分析器报错时，真正有用的不是一个整数，而是“哪个文件、哪一行、哪一列”。在 Go 的 go/token 中，扫描器先用 File.Pos 得到文件内位置，再由 FileSet.PositionFor 把它还原成可读的 token.Position。多文件工程里如果直接把 Pos 当作字节偏移，诊断信息就很容易指错文件。

PositionFor 的关键是先让 FileSet 找到所属文件，再根据 adjusted 决定是否应用 //line 指令；普通源码诊断通常使用 true，需要物理文件位置时使用 false。

先把 Pos、文件偏移和 Position 分开

token.FileSet 管理一组文件，每个文件都有自己的 base 和 size。调用 f.Pos(offset) 时，offset 是当前文件中的字节位置；返回的 token.Pos 带有这个文件在集合中的全局区间。随后 fset.PositionFor(pos, adjusted) 才会得到包含 Filename、Offset、Line、Column 的结构。

fset := token.NewFileSet()
file := fset.AddFile("parser/input.go", -1, len(src))
pos := file.Pos(byteOffset)
physical := fset.PositionFor(pos, false)
display := fset.PositionFor(pos, true)

这里的 physical 和 display 可能相同，也可能因为源码中的 //line 注释不同。不要把 pos 转成整数后自行除以换行数：文件 base、UTF-8 字节长度和逻辑行映射都由 token.File 维护。

多文件 FileSet 如何找到正确的文件

下面的例子把两个源文件加入同一个集合，并分别取第二个文件的首字符位置。FileSet.PositionFor 会先根据 Pos 所在区间选中 config.go，再计算该文件内的行列。

fset := token.NewFileSet()
mainFile := fset.AddFile("cmd/main.go", -1, len(mainSrc))
configFile := fset.AddFile("internal/config.go", -1, len(configSrc))

mainPos := mainFile.Pos(0)
configPos := configFile.Pos(0)
fmt.Println(fset.PositionFor(mainPos, false))
fmt.Println(fset.PositionFor(configPos, false))

这条调用链可以概括为 File.Pos → FileSet.PositionFor → token.Position。诊断器应在 AST 节点或扫描结果里保存 token.Pos，最后一刻才格式化文件名和行列，这样同一个位置既能用于排序，也能按不同输出格式展示。

adjusted 如何改变 //line 诊断位置

生成代码或嵌入式 DSL 常用位置改变型 //line 注释，把物理文件中的代码映射到用户真正关心的源文件。此时同一个 Pos 通过两个参数会得到两套合法答案：adjusted=false 忽略映射，adjusted=true 采用映射后的文件名、行号或列号。

src := "package demo\n//line virtual.dsl:40\nvar x = 1\n"
file := fset.AddFile("generated.go", -1, len(src))
pos := file.Pos(strings.Index(src, "x"))

fmt.Println(fset.PositionFor(pos, false)) // generated.go 的物理位置
fmt.Println(fset.PositionFor(pos, true))  // virtual.dsl 的逻辑位置

用户-facing 编译错误通常应使用 true，因为它保留了生成器提供的逻辑来源；调试扫描器自身或做源码切片时，则应使用 false，避免把虚拟文件名误当作磁盘路径。

越界、NoPos 与诊断输出的验收

PositionFor 对 NoPos 返回零值位置；位置早于文件起点或超过文件末尾时，会按文件边界调整。可以把这些情况写成表格驱动测试，重点检查“是否有文件名”和“是否允许逻辑映射”，不要只比较格式化字符串。

输出诊断时建议保留原始位置和格式化结果。例如日志字段可以同时记录 pos、physical.Filename 和 display.Line。这样遇到生成代码映射错误时，可以区分是 AST 节点错了，还是展示层选择了不合适的 adjusted。

常见问题

Position 的 Offset 是字节还是字符？

是字节偏移。UTF-8 中文会占多个字节，不能用 Go 字符数替代。

可以直接调用 fset.Position(pos) 吗？

可以，它等价于 fset.PositionFor(pos, true)。只有需要忽略 //line 映射时才显式传入 false。

不同 FileSet 的 Pos 能比较吗？

不应比较。Pos 的区间属于创建它的 FileSet，跨集合排序或查找应改用文件名、偏移等明确字段。

把位置映射留到输出边界

多文件诊断最稳妥的做法，是让解析和分析阶段传递 token.Pos，把 PositionFor 集中放在报告层。这样物理位置、逻辑位置和机器可读输出可以共享同一个事实来源，也能通过几组 //line、越界和 NoPos 测试提前发现偏移错误。