Go csv.Reader 遇到列数不一致时怎么保留异常行

我第一次把 CSV 导入接到批处理任务时，最不想看到的不是错误本身，而是错误行直接消失：表头有 5 列，某一条数据只有 4 列，Read 返回了错误，代码却马上 continue，最后只剩一份“不完整但看起来成功”的结果。

先给结论：列数不一致时，csv.Reader.Read 仍可能返回已经解析出的 record，同时返回 csv.ErrFieldCount。把这条 record 单独存到异常列表，再决定是否继续读取；只有需要保留未改写的原始字节时，才需要额外设计原始输入留存。

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

先看懂 FieldsPerRecord 的三种模式

FieldsPerRecord 决定的是“读到一条记录后要不要检查列数”，不是“遇到异常后要不要停止整个文件”。它有三种常用状态：

默认值是 0，所以很多代码实际上是在“第一条记录定标”。如果首行是表头，后续数据列数变化就会触发 ErrFieldCount；如果没有固定格式要求，可以显式设置为负数，再自己判断 len(record)。

捕获 ErrFieldCount，异常行也能留下

严格模式并不等于异常记录不可见。下面的读取循环把错误分成三类：普通记录直接保存，列数错误保存到 badRows 后继续，其他解析错误则交给调用方决定是否停止。

package main

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

type BadRow struct {
    Index  int
    Fields []string
    Err    error
}

func collectRows(input string) ([][]string, []BadRow, error) {
    r := csv.NewReader(strings.NewReader(input))
    r.FieldsPerRecord = 3 // 固定三列，异常时仍让 Read 返回已解析字段

    var goodRows [][]string
    var badRows []BadRow
    for index := 0; ; index++ {
        record, err := r.Read()
        if errors.Is(err, csv.ErrFieldCount) {
            // ErrFieldCount 不等于 record 丢失，把异常字段复制后单独存档。
            badRows = append(badRows, BadRow{Index: index, Fields: append([]string(nil), record...), Err: err})
            continue
        }
        if errors.Is(err, io.EOF) {
            // 文件读完后返回已经收集的正常记录和异常记录。
            return goodRows, badRows, nil
        }
        if err != nil {
            // 引号未闭合等结构错误不能伪装成一条可用数据。
            return nil, badRows, fmt.Errorf("读取第 %d 条记录失败: %w", index+1, err)
        }
        goodRows = append(goodRows, record)
    }
}

这里最关键的是判断顺序：先判断 ErrFieldCount，因为这时 record 可能已经包含了本次读取到的字段；只有其他错误才直接返回。生产代码还应给异常记录附上输入文件、批次号和业务主键，避免后续只能看到一行孤立数组。

如果字段数可变，先读取再自行分流

有些供应商文件允许尾部列缺省，也有些文件会不断追加扩展列。这时可以关闭内置列数校验，让业务代码明确决定哪些记录能入库：

func routeVariableRows(input string) error {
    r := csv.NewReader(strings.NewReader(input))
    r.FieldsPerRecord = -1 // 允许每条记录拥有不同列数

    for rowNo := 1; ; rowNo++ {
        record, err := r.Read()
        if errors.Is(err, io.EOF) {
            // 文件读完后结束分流。
            return nil
        }
        if err != nil {
            if errors.Is(err, csv.ErrUnexpectedEOF) {
                // 引号未闭合时输入结构不完整，不能把半条记录当成正常数据。
                return fmt.Errorf("第 %d 条记录未闭合: %w", rowNo, err)
            }
            return err
        }

        if len(record) != 3 {
            // 业务层定义异常边界，并保留解析后的字段供人工或重试任务使用。
            fmt.Printf("异常记录 %d: %v\\n", rowNo, record)
            continue
        }
        // 只有满足业务列数的记录才进入正式写入路径。
        fmt.Printf("正常记录 %d: %v\\n", rowNo, record)
    }
}

这段示例把“语法能否解析”和“业务是否接受”拆开了。需要注意，FieldsPerRecord = -1 后通常不会再由 Reader 报列数错误，因此主要判断会落在 len(record) 上。

InputOffset 能定位位置，但不等于原始异常行

CSV 支持带引号字段和字段内换行，所以一条逻辑记录不一定对应一行文本。InputOffset 适合记录下一次读取位置或帮助定位输入范围，但它不能把已经解析后的 []string 还原成原始字节。

如果异常记录只需要供人工查看，保存 record、错误类型、记录序号和 InputOffset 就够了；如果合规或重放任务要求保留完全原样的 CSV 片段，则应在读取前复制输入流，或设计能按偏移读取原始数据的存储层，不要把 strings.Join(record, ",") 当作原文。

正式导入时怎样决定继续还是拒绝

我通常把策略写成一张很小的决策表：

这样做的好处是，异常记录不会悄悄混进正式数据，也不会因为一条坏记录而让整份文件的诊断信息丢掉。是否继续读取，应该由导入策略决定，而不是由 ErrFieldCount 这个错误名替你做决定。

最后记住三条边界

• FieldsPerRecord > 0 是固定列数校验，= 0 让第一条记录定标， 则交给业务层判断。
• 遇到 ErrFieldCount 时先检查返回的 record，它可以成为异常存档，而不是必须丢弃的返回值。
• record 是解析后的字段集合；要保存完全原始的 CSV 字节，必须另做输入留存设计。

相关问题：

• 为什么第一条记录正常，第二条就报 ErrFieldCount？ 因为默认的 0 会用第一条记录设置后续期望列数。
• 把 FieldsPerRecord 设为负数是不是更安全？ 不是。它只是关闭 Reader 的列数校验，业务代码仍要明确接受哪些字段组合。
• 异常行能不能直接重新拼成 CSV？ 可以生成新的诊断文本，但它不一定等于原始输入，尤其是引号、空白和字段内换行存在时。