Go token.File.AddLineColumnInfo 怎样表示生成代码的位置映射

生成器把模板变成 Go 文件以后，可以在生成文件的字节偏移处登记“这里对应模板的哪一行哪一列”。token.File.AddLineColumnInfo 保存这种替代位置；查询时使用 PositionFor(p, true) 才采用它。生成文件本身和字节偏移不会因此改写。

适用场景是生成器或分析器已经掌握片段来源，需要让诊断指向模板。它表达的是位置锚点，不能自动推断任意转换前后的字符对应关系。下面直接构造一个独立的文件位置对象，展示生成器如何登记来源，不假设解析器替你建立映射。

先区分物理行表与替代位置记录

一个文件既需要记录生成内容中的换行，也可能需要记录替代文件名、行号与列号。前者回答生成文件里的位置，后者回答展示给读者的位置。SetLinesForContent 建立物理行表，AddLineColumnInfo 加入另一类记录；二者职责不同。

登记时的 offset 是从生成内容开头算起的零基字节偏移，不是模板行号，也不是 FileSet 内部的全局位置。目标 line、column 通常按一基坐标提供。处理中文时，应以字节长度定位生成内容，不能把字符数量当作偏移。

图中的两组信息共同属于文件位置对象；连线只表示数据关联。

在生成字节上登记模板位置锚点

设想两个生成声明分别来自模板的第20行和第50行。先固定生成字节，找到每段起始偏移，再按偏移升序加入锚点。本例把第一个声明开头对应到模板第20行第3列，第二个声明开头对应到第50行第1列。

package main

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

func main() {
    // 此处模拟生成器输出的两个代码片段。
    src := []byte("package generated\nvar A = 1\nvar B = 2\n")
    fset := token.NewFileSet()
    file := fset.AddFile("generated.go", -1, len(src))
    file.SetLinesForContent(src)

    // 偏移按生成文件的字节计算，锚点按递增顺序登记。
    a := strings.Index(string(src), "var A")
    b := strings.Index(string(src), "var B")
    file.AddLineColumnInfo(a, "page.tpl", 20, 3)
    file.AddLineColumnInfo(b, "page.tpl", 50, 1)

    // 同一位置保留物理坐标和用于用户诊断的映射坐标。
    p := file.Pos(a + len("var "))
    physical := file.PositionFor(p, false)
    mapped := file.PositionFor(p, true)
    fmt.Printf("physical=%s mapped=%s offset=%d\n",
        physical, mapped, mapped.Offset)
}

代码供读者放进独立程序使用，本文未执行示例。按上述输入推导，查询 A 的位置时，物理坐标属于 generated.go，映射坐标属于 page.tpl；映射列在第一个锚点的第3列基础上增加 len("var ") 个字节。打印语句同时保留两种坐标，便于观察自己的生成数据。

登记偏移必须严格大于上一次加入的替代记录，并小于文件大小，否则该条信息被忽略。相同偏移不是覆盖更新接口。生成器应先整理片段表，再依次登记；不要依赖返回错误，因为该方法没有错误返回值。

理解同一锚点覆盖的行与列

查询某个位置时，适用的是不晚于该位置的最近一条替代记录。它的影响延续到后续替代记录出现之前。若生成片段并非模板中的连续区域，应为新的来源区域另设锚点，避免把不相干的内容归到旧来源。

同一个物理行内，列号相对锚点的字节距离计算；跨过物理换行后，行号随物理行差增加，列号采用所在物理行的列位置。因而多行文本的重新缩进、插入或折叠，通常需要生成器提供更多锚点，不能只在整个文件开头登记一次。

列号为0表示未知。在该替代记录适用范围内，映射列保持未知，包括后续物理行；若希望恢复明确列号，应登记新的合适锚点。

把映射交给诊断展示而非源码切片

对用户展示报错时可以使用映射文件名与行列；读取或切割 generated.go 时仍使用生成字节偏移。不要拿映射行列反向切模板，因为该接口没有提供逆向映射和模板文本，也没有验证模板文件是否存在。

例如代码修复工具可以在日志里显示模板位置，同时把实际生成位置保存在诊断对象的另一个字段中。是否允许直接改模板，需要生成器自己的精确来源片段表决定。

如果还需要让其他进程解析生成文件后获得位置提示，应考虑在生成文本中输出合法的 line directive。对一个内存中的 token.File 调用本方法，并不会把指令写回源文件。另需避免在解析器已经登记指令的同一 File 上无序追加旧偏移。

常见问题

为什么调用之后 File.Name 没有变？

它仍表示注册的生成文件名称；替代文件名用于适用位置的映射结果。保存生成产物时继续使用明确的产物路径。

可以把文件末尾作为新锚点吗？

新记录要求偏移小于文件大小，等于大小不满足登记条件。不要把位置查询允许涉及文件末尾与替代记录的登记条件混为一谈。

能直接用它代替完整 source map 吗？

若转换只是连续行段的位置标注，它可以承担诊断映射的一部分。若需要逆查、跨文件拼接范围或字符级改写，应另外维护来源区间，再按展示需求投影为位置锚点。

官方资料：https://pkg.go.dev/go/token#File.AddLineColumnInfo；位置实现说明：https://go.dev/src/go/token/position.go。本文围绕生成器登记来源展开，不涉及 Go 版本变更公告。