Go token.FileSet 怎样通过 Read 与 Write 保存位置映射

如果你的 Go 工具已经把源码解析成了 token.Pos，进程重启后想继续把它还原为文件名、行号和列号，token.FileSet 自带的 Write 与 Read 就是合适的持久化边界。它们保存的是文件区间、文件大小、行偏移表以及位置指令等元数据，不保存源文件字节，也不替你保存 AST。

迁移时最重要的变化是：不要自己复制 FileSet 的内部字段，也不要把恢复后的集合当成源文件备份。让外部编码器接住 Write 给出的值，再在一个新的 FileSet 上调用 Read，最后用同一套 Position 查询接口恢复位置。

一句话结论：Write 序列化位置映射，Read 恢复位置映射；源文件内容和 AST 需要另外保存，恢复目标最好是空的 FileSet。

适用场景：源码索引器、静态分析缓存、增量诊断和需要跨进程传递位置元数据的工具。

先分清 FileSet 保存的是什么

FileSet 把每个文件映射到一个不重叠的整数区间。文件加入集合时有 base 和 size，文件内的字节偏移通过 base + offset 形成 Pos。查询时，FileSet 先找到所属的 File，再根据行偏移表换算成 Position。

因此，保存后的数据能够回答“某个 Pos 对应哪个文件、哪一行、哪一列”，但回答不了“该文件当前的源码是什么”。如果源码已经变化，旧的字节偏移仍可能指向旧内容中的位置，缓存必须和源码版本或内容摘要一起管理。

从手工复制字段迁移到 Write

旧代码常见的做法是遍历文件，再手工保存文件名、起始位置和行表。这会把标准库的内部结构暴露到业务层，还容易漏掉位置指令。更稳妥的写法是把编码器作为回调传给 Write：

package main

import (
	"bytes"
	"encoding/gob"
	"fmt"
	"go/token"
)

func saveFileSet(fset *token.FileSet) ([]byte, error) {
	var buf bytes.Buffer
	// Write 负责整理位置元数据，gob 只负责把回调收到的值编码。
	err := fset.Write(func(value any) error {
		return gob.NewEncoder(&buf).Encode(value)
	})
	if err != nil {
		return nil, fmt.Errorf("保存 FileSet: %w", err)
	}
	return buf.Bytes(), nil
}

回调接收到的值是标准库内部整理出的可编码结构。调用方只需要选择编码格式和存储介质，不需要依赖内部类型名称。生产代码中可以把 buf.Bytes() 写入文件、对象存储或缓存，并给它绑定源码版本。

用 Read 在新集合中恢复映射

恢复端把同一份字节交给解码器，再把解码目标传给 Read：

func loadFileSet(data []byte) (*token.FileSet, error) {
	fset := token.NewFileSet()
	// Read 会把解码出的文件区间和行表加入这个新集合。
	err := fset.Read(func(value any) error {
		return gob.NewDecoder(bytes.NewReader(data)).Decode(value)
	})
	if err != nil {
		return nil, fmt.Errorf("恢复 FileSet: %w", err)
	}
	return fset, nil
}

func locate(fset *token.FileSet, p token.Pos) token.Position {
	// Position 将 Pos 还原成文件名、字节偏移、行号和列号。
	return fset.Position(p)
}

这里特意使用新的 FileSet。官方实现的 Read 会把反序列化出的文件加入接收集合，并设置集合的基础位置；它不是“读取后自动清空旧集合”的替换操作。把旧文件继续留在集合中，可能造成区间重叠或让查询落到意外的文件上。

迁移后要检查的三个边界

另外，编码器或解码器返回错误时，应立即把错误传回调用方；不要在错误后继续使用半恢复状态。若应用同时保存 AST、源码和 FileSet，应把三者放在同一个版本标识下，避免位置表来自旧源码而 AST 来自新源码。

一份可执行的迁移清单

1. 把业务层手工复制 FileSet 字段的代码替换为 Write 回调。
2. 明确编码格式和存储介质，并为缓存记录源码版本或内容摘要。
3. 恢复时创建 token.NewFileSet()，不要把数据读进正在使用的集合。
4. 恢复后用已知的 Pos 调用 Position，检查文件名、字节偏移、行列关系。
5. 遇到编码错误、源码变更或区间不匹配时丢弃缓存并重新建立映射。

相关问题

Write 会保存源码文本吗？

不会。它保存位置元数据；源码文本应由应用单独保存或重新读取。

Read 能否直接复用已有 FileSet？

技术上接收者必须非空指针，但工程上应使用新的集合，因为 Read 是加入反序列化文件，不是清空后替换。

位置恢复后还能解析 AST 吗？

不能仅靠 FileSet 恢复 AST。FileSet 只负责位置映射，AST 和源码需要独立的序列化方案。