Go token.FileSet.Iterate 怎样导出多文件的基址范围

我在做 AST 多文件索引时，最初把 FileSet 里的 Pos 当成了“当前文件的 offset”，结果第二个文件开始，位置报告就很难读。后来我把报告拆成文件名、基址、大小和末端四列，再用 FileSet.Iterate 统一导出，问题就清楚了：FileSet 管理的是跨文件不重叠的全局位置区间，文件内字节偏移要用 Pos - Base 来理解。

先把 FileSet 的基址区间想清楚

token.FileSet 可以看成多份源码文件共用的一套位置坐标。调用 AddFile(filename, base, size) 后，文件会占用从 base 到 base+size 的区间；File.Base() 返回这个区间的起点，File.Size() 返回注册时的字节大小，File.End() 返回末端位置。

这里的“基址”只负责让不同文件的 Pos 不重叠。例如某文件的基址是 100，源码偏移是 12，那么它对应的 Pos 是 112；反过来定位文件内偏移时，应该计算 112 - 100，不能直接把 112 当作文件偏移。

为什么我选择 Iterate 导出多文件报告

如果在业务代码里另外维护一份文件切片，文件顺序、删除后的状态和实际坐标很容易发生偏差。Iterate 直接访问 FileSet 内的文件集合，并且按 Base 升序调用回调；只要报告字段来自回调收到的 *token.File，导出的顺序就和位置空间一致。

我通常把报告设计成独立的 FileRange，不要把 *token.File 指针直接暴露给下游。这样下游只消费名称和区间，后续要做 JSON、日志或索引存储时，不会被 token 包对象的生命周期绑住。

用一段小函数导出基址范围

下面的函数只做位置元数据导出。注意 File.Base() 的返回类型是 int，而报告里将它转换成 token.Pos，是为了和 End()、其它位置值放到同一语义下比较：

package main

import (
    "fmt"
    "go/token"
)

type FileRange struct {
    Name string
    Base token.Pos
    Size int
    End  token.Pos
}

func exportRanges(fset *token.FileSet) []FileRange {
    ranges := make([]FileRange, 0)

    // Iterate 按文件基址升序遍历，回调返回 false 才会提前停止。
    fset.Iterate(func(file *token.File) bool {
        // Base 是 FileSet 坐标；Size 是注册时的字节数；End 是区间末端。
        ranges = append(ranges, FileRange{
            Name: file.Name(),
            Base: token.Pos(file.Base()),
            Size: file.Size(),
            End:  file.End(),
        })
        return true
    })

    return ranges
}

func printRange(item FileRange) {
    // 文件内偏移需要减去基址，不能直接使用全局 Pos。
    fmt.Printf("%s: base=%d size=%d end=%d\\n",
        item.Name, item.Base, item.Size, item.End)
}

这个函数的价值不在于多写了一个切片，而在于把坐标转换的责任集中起来：索引器、诊断器和日志模块都读取同一份 FileRange。后续拿到某个 Pos 时，可以先用 fset.File(pos) 找到所属文件，再用 int(pos) - file.Base() 求文件内字节偏移。

规模变大后，报告应该保留哪些边界

在小项目里直接打印四列就够了；文件数量变多后，我会保留下面这张清单。它能防止“看起来都是整数”的位置值被不同模块误用。

还有两个容易遗漏的代价。第一，Iterate 的回调返回 false 就会停止遍历，做“导出全部文件”时必须始终返回 true。第二，FileSet 方法虽然支持并发调用，但报告切片仍然是当前函数自己的可变数据，若要跨 goroutine 共享，应该在函数返回后再做明确的同步或复制。

相关问题

FileSet.Iterate 的顺序等于文件名排序吗？

不等于。它按文件在 FileSet 中的 Base 升序遍历，通常反映文件加入位置空间的顺序；文件名本身可能完全不是字典序。

为什么 End() 看起来比下一个 Base 小一位？

文件区间按 [base, base+size] 表示，而 FileSet 为下一个文件提供的可用基址会在前一个区间末端之后再留出位置，所以 End() 和下一次 Base() 不是同一个概念。

只想导出前几个文件怎么办？

在回调中累计数量，达到上限后返回 false。如果目标是完整报告，则不要用这个提前停止逻辑，并把空 FileSet 视为合法的空报告。