Go token.File.Offset 怎样把源码位置转换为字节偏移

我在做 Go 源码诊断时经常遇到一个小但容易混淆的问题：AST 节点给的是 token.Pos，而错误高亮、切片截取和补丁定位需要的是文件内从 0 开始的字节偏移。这个转换不应该靠减一个“看起来差不多”的数字完成，正确入口是 token.File.Offset。

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

对属于同一个 token.File 的位置，先用 File.Pos(offset) 把文件内字节偏移编码成 token.Pos，再用 File.Offset(pos) 转回偏移。NoPos 或文件起止范围外的位置会按官方规则回退到 0 或文件大小；真正要注意的是不要把别的文件位置交给当前文件转换。

我为什么会把 Pos 和 offset 分开记录

token.Pos 是文件集合里的紧凑位置值，不是某个文件天然拥有的“第几个字节”。FileSet.AddFile 会给文件安排一个 base 和 size，文件内偏移满足 int(pos) = base + offset。因此一个 AST 位置只有和正确的 token.File 配对，才能还原成当前源码的偏移。

对我来说，生产代码里同时保留 Pos 和 offset 更稳：前者用于和 AST、FileSet 对齐，后者用于切片、诊断范围和补丁计算。日志里只存一个裸整数，很容易在跨文件处理时误读。

File.Pos 与 File.Offset 是一对互逆入口

先建立文件，再把文件内偏移编码为位置。下面的例子没有运行结果依赖，重点是展示转换契约；代码中的注释保留了输入范围和资源边界。

package main

import (
    "fmt"
    "go/token"
)

func main() {
    fset := token.NewFileSet()
    // size 是源码字节数；base 使用 FileSet.Base，避免和已有文件区间重叠。
    file := fset.AddFile("handler.go", -1, 128)

    sourceOffset := 37
    // File.Pos 把文件内的 0 基字节偏移编码到这个 File 的 Pos 区间。
    pos := file.Pos(sourceOffset)
    // File.Offset 再把同一个文件的 Pos 还原为文件内字节偏移。
    restoredOffset := file.Offset(pos)

    fmt.Printf("pos=%d offset=%d\\n", pos, restoredOffset)
}

官方文档给出的不变量是 f.Offset(f.Pos(offset)) == offset。这个不变量只对同一个文件成立；如果先从 FileSet.File(pos) 找到所属文件，再调用该文件的 Offset，跨文件诊断才不会串位。

生产代码怎样处理 AST 位置和文件边界

解析多个文件时，我会把“位置所有权”当成一道边界检查：先通过 FileSet.File 找到位置属于哪个文件；找不到文件时，把它当成无效诊断，而不是猜一个当前文件。File.Offset 对 NoPos 返回 0，位置早于文件起点也返回 0，超过文件终点则返回文件大小。

func fileOffset(fset *token.FileSet, p token.Pos) (string, int, bool) {
    // NoPos 或不属于当前 FileSet 的位置都不能生成文件诊断。
    if p == token.NoPos {
        return "", 0, false
    }
    file := fset.File(p)
    if file == nil {
        return "", 0, false
    }
    // Offset 负责按 File 的起止边界归一化到 [0, Size()]。
    return file.Name(), file.Offset(p), true
}

这里的 Column 也要留意：Go 的源码位置列是按字节计数，不是按 Unicode 字符数计数。若后续要在 UTF-8 文本中按字符索引，应该把字节偏移交给明确的解码层，不能直接把列号当作 rune 下标。

我的日志与发布前检查清单

在源码分析器、静态检查器或自动修复工具里，我会记录文件名、原始 token.Pos、归一化后的 offset 和诊断范围。这样遇到 //line 导致的展示位置变化时，仍能区分“文件内物理偏移”和“面向读者的 Position”。

• 创建 File 时确认 size 是字节数，且文件区间没有和已有文件重叠。
• 转换前检查 token.NoPos，并用 FileSet.File 验证位置所属文件。
• 需要源码切片时使用 File.Offset，需要展示文件名、行列时使用 FileSet.PositionFor。
• 多字节 UTF-8 文本不要把字节列当成字符列，补丁范围也要保持同一坐标系。

这套写法的好处是边界行为明确：无效位置不会被伪装成有效文件，越界位置也不会让调用方自己发明一套截断规则。对我来说，token.File.Offset 不只是一个转换函数，更是把 AST 坐标和源码字节坐标分开的稳定接口。

常见问题

File.Offset 返回的是字符位置吗？不是，它返回文件内字节偏移，从 0 开始；源码位置的列也按字节计数。

可以直接对任意 token.Pos 调用当前文件的 Offset 吗？不建议。先用 FileSet.File 确认位置属于哪个文件，再调用对应 File.Offset。

Position 和 Offset 应该怎么选？切源码、算补丁范围选 Offset；输出文件名、行号和列号选 Position 或 PositionFor。