Go csv.Reader 怎样用 FieldPos 和 InputOffset 定位坏行

Go 读取 CSV 时，如果只把 Read 返回的错误字符串写进日志，通常只能知道“解析失败”，却不知道原始文件的哪一行、哪一列出了问题。更实用的做法是：继续保留 Read 返回的部分记录和错误，用 FieldPos 读取最近一条记录中字段的起始行列，再用 InputOffset 记录当前输入流的字节边界。

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

先把 Read 的部分记录和错误留下来

csv.Reader.Read 每次处理一条记录。正常结束时返回 io.EOF；字段数量不符合约束时会返回记录和 ErrFieldCount；字段内容本身无法解析时，则可能返回已经读到的部分字段以及一个 ParseError。因此诊断代码不能只写成 if err != nil { return err }，否则后面的定位信息没有机会被记录。

package main

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

func readCSV() error {
    input := "id,name,amount\n1,Ada,10\n2,\"broken,20\n"
    reader := csv.NewReader(strings.NewReader(input))

    for {
        record, err := reader.Read()
        if err == io.EOF {
            // EOF 表示没有更多记录，不是 CSV 解析失败。
            return nil
        }
        if err != nil {
            // 先保留已读到的字段，后面可用它们做 FieldPos 诊断。
            fmt.Printf("partial_record=%q offset=%d err=%v\\n", record, reader.InputOffset(), err)

            var parseErr *csv.ParseError
            if errors.As(err, &parseErr) {
                // ParseError 提供记录起始行、错误行、按字节的列和底层错误。
                fmt.Printf("start_line=%d line=%d column=%d cause=%v\\n",
                    parseErr.StartLine, parseErr.Line, parseErr.Column, parseErr.Err)
            }
            return err
        }

        // 正常记录在这里交给后续业务处理。
        fmt.Printf("record=%q offset=%d\\n", record, reader.InputOffset())
    }
}

这里的 InputOffset 在成功读取和失败读取后都可以被记录，但它表达的是 Reader 已经消费到的输入边界。它不是“错误字符的绝对位置”，也不应被直接当成 ParseError.Column 使用。

用 FieldPos 找到最近记录中字段的起始位置

FieldPos(field) 返回最近一次 Read 返回的记录中，第 field 个字段起始处的行号和列号。索引从 0 开始，返回的行列从 1 开始；列号按 UTF-8 输入中的字节计算，而不是按用户看到的 Unicode 字符数计算。

func printFieldPositions(reader *csv.Reader, record []string) {
    for index := range record {
        // 只对当前 Read 返回的有效字段索引调用 FieldPos。
        line, column := reader.FieldPos(index)
        fmt.Printf("field=%d value=%q line=%d column=%d\\n",
            index, record[index], line, column)
    }
}

如果一条记录中已经成功解析出 id 和 name，但第三个字段附近出现语法错误，可以先遍历返回的部分记录，再把每个已读字段的起点写进诊断日志。图中的字段映射强调的是“记录字段 → 起始位置”，不是把错误字符串重新解析成列号。

用 InputOffset 记录原始流的行边界

InputOffset 返回当前 Reader 位置的输入字节偏移。官方定义可以理解为：最近一行已经结束，下一行即将从这个位置开始。对文件导入来说，它适合写入错误日志、断点记录或原始数据切片索引；但如果记录中包含带换行符的引号字段，逻辑上的一条 CSV 记录可能跨越多行，不能把“CSV 记录数”简单等同于物理行数。

func readWithOffset(reader *csv.Reader) error {
    for {
        record, err := reader.Read()
        offset := reader.InputOffset()

        if err == io.EOF {
            // 读取结束时 offset 是流尾部位置。
            return nil
        }
        if err != nil {
            // offset 用于标记 Reader 已消费到的输入边界。
            fmt.Printf("offset=%d partial=%q err=%v\\n", offset, record, err)
            return err
        }

        // 成功记录的偏移可作为后续排错或进度日志字段。
        fmt.Printf("offset=%d record=%q\\n", offset, record)
    }
}

如果业务需要从原文件中取出“出错附近的原始字节”，应保存原始文件的可寻址副本，再结合已知的前一个偏移和当前偏移切片。不要拿解析后的字段值重新拼接 CSV，因为引号、逗号和换行的原始形式可能已经被 Reader 规范化。

把 ParseError、FieldPos 和偏移组合成诊断记录

生产日志里建议把定位字段拆开保存，而不是只保留一段拼接后的错误文本。一个简单的诊断函数可以覆盖三类情况：解析语法错误、字段数量错误和其他输入错误。

type csvDiagnostic struct {
    Offset    int64
    StartLine int
    Line      int
    Column    int
    Field     int
    Cause     string
}

func diagnose(reader *csv.Reader, record []string, err error) csvDiagnostic {
    result := csvDiagnostic{
        Offset: reader.InputOffset(),
        Field:  -1,
        Cause:  err.Error(),
    }

    var parseErr *csv.ParseError
    if errors.As(err, &parseErr) {
        // ParseError 的 Column 已经是按字节计算的 1 起始列号。
        result.StartLine = parseErr.StartLine
        result.Line = parseErr.Line
        result.Column = parseErr.Column
    }

    if len(record) > 0 {
        // 最后一个已读字段通常最接近出错点，但只是定位提示。
        result.Field = len(record) - 1
        line, column := reader.FieldPos(result.Field)
        if result.Line == 0 {
            result.Line = line
            result.Column = column
        }
    }
    return result
}

这里没有把“最后一个已读字段”冒充成“错误字段”。对于语法错误，ParseError.Line 和 ParseError.Column 才是错误位置；FieldPos 只描述已经返回记录中的字段起点。两者同时记录，才能区分“已成功解析到哪里”和“解析器在哪里停下”。

多字节字符、跨行字段和越界调用要单独处理

第一，列号是字节列。如果字段前面有中文或其他多字节字符，日志中的列号和用 []rune 计算的字符位置可能不同；需要把它转换为用户界面位置时，必须明确转换规则，不要直接拿来当字符串的 rune 下标。

第二，CSV 允许引号字段包含逗号和换行。ParseError.StartLine、Line 和 Column 是物理输入位置，InputOffset 是字节边界；“第几条记录”和“第几行”不是同一个维度。

第三，FieldPos 的索引越界会 panic。无论索引来自固定列配置还是错误推断，都应先检查 0 。如果 Read 直接返回了空记录和错误，就不要为了“补一个位置”强行调用 FieldPos(0)。

func safeFieldPos(reader *csv.Reader, record []string, index int) (int, int, bool) {
    // 先检查范围，避免 FieldPos 的越界 panic 直接中断导入任务。
    if index = len(record) {
        return 0, 0, false
    }
    line, column := reader.FieldPos(index)
    return line, column, true
}

一份可落地的 CSV 错误定位清单

• 每次 Read 都区分 io.EOF、csv.ErrFieldCount 和 *csv.ParseError。
• 错误发生时保留返回的部分记录和 InputOffset，不要只记录 err.Error()。
• 需要字段级提示时，只对当前 Read 返回记录中的合法索引调用 FieldPos。
• 在日志中分别记录逻辑记录、物理行、字节列和输入字节偏移，避免把它们混成一个“行号”。
• 若需要回看原始内容，保留原始字节流或文件句柄对应的可寻址副本，不用解析后的字段重新拼接。

常见问题

FieldPos 的列号是字符数还是字节数？

是字节数，而且从 1 开始。输入中存在中文、表情或其他多字节 UTF-8 字符时，它可能与用户看到的字符序号不同。

InputOffset 能直接告诉我坏字符的偏移吗？

不能。它表示 Reader 当前输入位置，也就是最近读取行的结束和下一行的开始。坏字符的精确行列应优先看 ParseError。

Read 出错后还能调用 FieldPos 吗？

只能针对最近一次 Read 返回的记录，并且索引必须落在返回切片范围内。若记录为空或索引越界，应跳过调用。

为什么不用 ReadAll 一次性读取后再定位？

逐条 Read 才能在错误发生的现场保留部分记录、偏移和错误对象；ReadAll 更适合确定不需要逐条诊断的批量读取。