Go csv.InputOffset 为什么不是当前字段的字节位置

csv.Reader.InputOffset 不是“当前字段偏移量”。它返回输入流当前读取位置：最近一次读取记录的结束位置，同时也是下一条记录的开始位置。这个设计适合记录级进度和断点续读；要定位最近记录中的某个字段，应使用 FieldPos。

我第一次用它时也把 offset 当成字段位置，结果每次都落在整条记录后面。理解成“已消费到哪里”就顺了：InputOffset 描述 Reader 的记录边界，不描述解析器当前正在看哪个字段。

InputOffset 指向记录边界，不指向字段

官方定义很明确：这个字节偏移量位于最近读取行的末尾和下一行的开头。CSV 里的带引号字段可以包含换行，因此这里更准确的概念是“记录边界”，不能简单等同于屏幕上的物理行号。

reader := csv.NewReader(src)

record, err := reader.Read()
if err != nil {
    return err // 只有完整读取成功后才把位置当成可提交边界
}

nextRecordOffset := reader.InputOffset() // 指向 record 结束后、下一条记录开始前
fmt.Printf("本条字段数=%d，下条记录偏移=%d\n", len(record), nextRecordOffset)

即使当前记录有五个字段，InputOffset 也只返回一个记录级位置。它不会告诉你第三个字段从哪里开始，更不会随着你访问 record[2] 而改变。

它真正适合做进度检查点

大文件导入中，记录边界比字段位置更实用。每成功处理一条记录，可以保存 InputOffset，失败恢复时从这个边界重新创建 Reader。真正需要注意的是提交顺序：先完成业务写入，再保存偏移；否则进度领先于数据提交，重启后可能跳过未落库的记录。

for {
    record, err := reader.Read()
    if errors.Is(err, io.EOF) {
        break // 全部记录处理完成
    }
    if err != nil {
        return err // 解析失败时不推进检查点
    }

    if err := store(record); err != nil {
        return err // 业务保存失败，保留上一个已提交位置
    }

    checkpoint := reader.InputOffset() // store 成功后再记录下一条的起点
    if err := saveCheckpoint(checkpoint); err != nil {
        return err // 检查点持久化失败时明确上报
    }
}

如果 store 和 saveCheckpoint 分属不同存储系统，还要接受“至少一次”处理的现实：检查点保存失败时，恢复后可能重放上一条记录。业务写入最好具备幂等键，而不是假设 offset 本身能提供分布式事务。

恢复时从记录边界重建 Reader

源文件支持 io.Seeker 时，可以把成功提交的偏移保存下来，再从该位置恢复。偏移必须来自完整成功记录之后，不能拿解析到一半的位置冒充记录边界。

func resumeCSV(file *os.File, offset int64) (*csv.Reader, error) {
    if _, err := file.Seek(offset, io.SeekStart); err != nil {
        return nil, fmt.Errorf("定位 CSV 检查点失败：%w", err) // 恢复前确认 Seek 成功
    }

    reader := csv.NewReader(file)
    reader.FieldsPerRecord = 5 // 重建 Reader 后恢复任务所需的解析约束
    return reader, nil
}

如果数据来自不可 Seek 的网络流，就不能只靠 offset 回退源头；需要上游支持 Range、对象存储分段读取，或把输入先落到可定位的介质。InputOffset 能提供坐标，但不会自动让输入源具备随机访问能力。

三个位置 API 各自解决什么问题

我现在会先问自己：要找的是“下一条记录从哪里开始”，还是“这一条里的某个字段从哪里开始”。前者用 InputOffset，后者用 FieldPos。如果 Read 本身因为 CSV 语法失败，则检查 *csv.ParseError。

相关问题

InputOffset 的单位是字符还是字节？

是输入流字节偏移。不要把它当成 Unicode 字符数量，也不要直接映射成编辑器显示列。

调用 InputOffset 会移动 Reader 吗？

不会。它读取 Reader 当前维护的位置，不会替你执行 Seek，也不会消费下一条记录。

为什么保存 offset 后仍可能重复处理一条？

通常是业务写入和检查点保存无法原子提交。写入成功、检查点失败时，恢复会从旧位置重放；使用业务幂等键或同一事务内保存数据与进度可以控制重复。

InputOffset 看起来不像当前字段位置，是因为它本来就不是为字段定位设计的。把它放回记录级检查点这个场景，再用 FieldPos 和 ParseError 补齐字段与语法坐标，三类位置就不会混淆。