Go CSV 怎么用 InputOffset 记录每条记录的文件字节位置

处理大 CSV 导入时，我更愿意把“第几条记录”与“原始文件的哪个字节区间”同时写入日志。Go 的 encoding/csv.Reader 已经提供了这个位置锚点：每次 Read 后调用 InputOffset()，得到的是当前输入流偏移，也就是最近读取记录的结束位置和下一条记录的起始位置。

官方文档：https://pkg.go.dev/encoding/csv#Reader.InputOffset

最实用的做法是保存上一次偏移作为本条记录的起点，再把本次 InputOffset() 保存为终点。这样得到的是字节区间，不是字符列号，也不需要自己按逗号或换行猜位置。

InputOffset 到底指向哪里

InputOffset 返回 int64 字节偏移。假设 Reader 已经成功读完记录 A，当前偏移就在 A 的末尾；从文件区间的角度看，这个数字也正好是记录 B 的起点。

这里的“位置”是输入字节流位置，不能直接当成下面几种值：

• 不是 Unicode 字符数。中文、表情等字符的 UTF-8 编码可能占多个字节。
• 不是字段列号。需要定位字段时，应结合 FieldPos，它返回的是行和字节列。
• 不是物理行号。CSV 的引号字段允许包含换行，一个逻辑记录可能跨越多个物理行。

逐条读取时记录每条 CSV 的起止偏移

把偏移放在 Read 循环里最清晰：进入本轮时的 start 是上一轮结束位置，成功读取后再取得 end。end - start 就是这一条逻辑 CSV 记录在输入流中占用的字节范围。

package main

import (
    "encoding/csv"
    "fmt"
    "io"
    "strings"
)

func main() {
    input := "id,name\n1,Ada\n2,Grace\n"
    reader := csv.NewReader(strings.NewReader(input))

    var start int64
    for recordNo := 1; ; recordNo++ {
        record, err := reader.Read()
        if err == io.EOF {
            break // 没有剩余记录时正常结束读取。
        }
        if err != nil {
            fmt.Printf("record=%d start=%d parse_error=%v\n", recordNo, start, err)
            break // 解析错误时保留起点，便于日志定位问题记录。
        }

        end := reader.InputOffset()
        fmt.Printf("record=%d start=%d end=%d bytes=%d data=%v\n",
            recordNo, start, end, end-start, record)
        start = end // 下一条逻辑记录从本次结束偏移开始。
    }
}

这段写法有两个关键点。第一，start 初始为零，代表输入流开头；第二，只有在 Read 成功后才把 start 更新为新的结束位置。遇到解析错误时不应把错误位置悄悄推进，否则后续重试或人工取样会失去原始区间。

如果程序需要断点记录，可以把 recordNo、start、end 和业务主键一起写入导入日志。下次恢复时，字节偏移可以作为原始文件中的定位线索，但是否能直接 Seek 到该位置，还取决于底层输入是否实现了 io.Seeker。

把偏移保存成记录区间，而不是只记一个数字

单独保存当前偏移只能回答“读到哪里了”，保存 [start,end) 区间则能回答“这一条记录占用了哪一段输入”。半开区间的好处是相邻记录天然衔接：上一条的 end 等于下一条的 start。

可以把日志字段设计成这样：

对于超大文件，这类区间日志比把整行原文复制到错误日志更省空间；对于需要合规审计的导入任务，区间也能帮助后续从原始文件抽取上下文。

多行字段和换行符会怎样影响偏移

CSV 的逻辑记录不一定等于一行文本。引号字段内部可以包含换行，所以一条记录可能从某个物理行开始，在几行之后才结束。InputOffset 仍然按输入字节流推进，只有 Read 返回这条完整逻辑记录后，才适合把当前偏移当成它的终点。

package main

import (
    "encoding/csv"
    "fmt"
    "strings"
)

func main() {
    input := "id,comment\n1,\"第一行\n第二行\"\n2,结束\n"
    reader := csv.NewReader(strings.NewReader(input))

    var start int64
    for {
        record, err := reader.Read()
        if err != nil {
            break // 真实导入代码应区分 io.EOF 与 ParseError。
        }
        end := reader.InputOffset()
        fmt.Printf("range=[%d,%d) fields=%v\n", start, end, record)
        start = end // 下一条逻辑记录从完整多行记录之后开始。
    }
}

另外，官方 Reader 会把输入中的 \r\n 规范化为 \n，但偏移仍然描述输入流的位置。因此跨平台导入时，不要用“返回字符串的长度”反推出原始文件的字节范围；原始数据的换行编码、字段转义和 Reader 的解析都可能使两者不同。

偏移适合做什么，不适合做什么

• 适合：导入进度、失败记录定位、断点日志、从原始文件抽取上下文、估算已读取输入量。
• 不适合：替代字段校验、代替 FieldPos 的列定位、直接代表业务行号，或在不可 Seek 的网络流上假设可以随时回退。

如果输入来自文件并且需要断点恢复，可以让上层同时保留文件标识、文件大小或版本、记录序号和字节偏移。只保存偏移而不绑定原始文件版本，换文件后可能会把同一个数字解释成完全不同的内容。

常见问题

InputOffset 是当前记录的开头还是结尾？

在 Read 返回一条记录后，它是最近读取记录的结束位置，同时也是下一条记录的起始位置。要得到当前记录起点，保存上一次成功读取后的偏移。

为什么 end-start 和字符串长度不同？

偏移按输入字节计算，而字符串长度可能按字节或字符理解；此外 CSV 引号、转义和换行归一化都会让解析后的字段内容不再等于原始字节片段。

解析错误时能不能照样调用 InputOffset？

可以把它作为诊断信息的一部分，但不要把错误返回当成一条成功记录。日志中保留上一条成功终点、错误信息和错误类型，是否推进断点要由恢复策略决定。

小结

InputOffset 的核心价值是把 CSV 的逻辑记录连接回原始输入字节流。逐条读取时用上一次偏移作为起点、用本次成功读取后的偏移作为终点，就能稳定记录 [start,end) 区间。遇到多行字段、CRLF、解析错误和断点恢复时，始终把它当作字节位置使用，不要把它误认为字符列号或物理行号。