Go csv.Reader 怎么导入列数不固定的记录并保留错误信息

导入 CSV 时，列数不固定并不等于每一行都应该被当成错误。Go 的 encoding/csv 已经提供了字段数策略：把 Reader.FieldsPerRecord 设为负数，可以让 Read 接收可变列记录；如果业务还要知道“这一行少了几列、多了几列”，就需要在应用层保存原始 record 并自行记录问题。

如果文件有明确的标准列宽，则不要为了“保留错误”把字段数检查关闭。正数会让 Read 在列数不匹配时同时返回记录和 csv.ErrFieldCount，这正好可以把异常行放入问题队列。本文只讨论字段数策略、读取错误和部分记录返回，不展开 CSV 自动映射结构体。

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

先把列数策略分成三种

FieldsPerRecord 的值决定了 csv.Reader 是否检查每条记录的字段数。它不是“容错开关”这么简单，而是输入契约的一部分：

最容易误解的是零值。新建的 Reader 默认是零值语义，第一条成功读到的记录会“锁定”字段数；它并不是“允许任意列数”。真正想接受可变列，应该显式写成 -1，把意图留在代码里。

用 FieldsPerRecord=-1 接收可变列记录

当输入来自多个历史版本，或者导出方允许在末尾增加扩展字段，可以先关闭标准库的列数比较，再把业务关心的规则放到自己的处理函数里。这样做的重点不是“忽略错误”，而是先完整保留输入，再决定这一行能否进入主表。

package main

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

type rowIssue struct {
    Line   int
    Record []string
    Reason string
}

func main() {
    input := "id,name,region\n1,Ada,East\n2,Bob\n3,Cleo,North,Trial\n"
    reader := csv.NewReader(strings.NewReader(input))
    // -1 明确表示列数可变，避免第一行把后续扩展列锁死。
    reader.FieldsPerRecord = -1

    var issues []rowIssue
    line := 0
    for {
        record, err := reader.Read()
        if err == io.EOF {
            // EOF 只表示输入读完，不是一条需要入库的记录。
            break
        }
        line++
        if err != nil {
            // 语法解析错误时也保留已经读到的字段，便于审计或人工修复。
            issues = append(issues, rowIssue{Line: line, Record: append([]string(nil), record...), Reason: err.Error()})
            continue
        }

        // 业务层按自己的规则判断列数，不把可变列误报成 csv.ErrFieldCount。
        if len(record)  4 {
            issues = append(issues, rowIssue{Line: line, Record: append([]string(nil), record...), Reason: "列数不在允许范围"})
            continue
        }
        fmt.Println("accepted:", record)
    }
    fmt.Println("issues:", issues)
}

示例允许 3 到 4 列。第二行少一列、第三行多一列时，原始字段仍然在 issues 中；这比先把字段截断成固定结构更适合后续排查。注意 append([]string(nil), record...) 是有意的拷贝：如果后续打开了 ReuseRecord，就不能把返回切片直接长期保存。

需要固定列宽时，别丢掉 ErrFieldCount

如果表头定义了严格列宽，推荐保留标准库的检查能力。将 FieldsPerRecord 设为正数，Read 遇到少列或多列时会返回当前 record 和 csv.ErrFieldCount。也就是说，不能因为 err != nil 就直接丢掉 record。

package main

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

func main() {
    input := "id,name,region\n1,Ada,East\n2,Bob\n3,Cleo,North\n"
    reader := csv.NewReader(strings.NewReader(input))
    // 这里的模板明确要求三列，字段数异常要进入问题队列。
    reader.FieldsPerRecord = 3

    for {
        record, err := reader.Read()
        if errors.Is(err, io.EOF) {
            // 正常结束不应被记录成导入失败。
            break
        }
        if errors.Is(err, csv.ErrFieldCount) {
            // 字段数异常仍带回 record，先复制再交给问题处理器。
            saved := append([]string(nil), record...)
            fmt.Printf("field-count issue: record=%q fields=%d\n", saved, len(saved))
            continue
        }
        if err != nil {
            // 其他错误交给统一错误通道，避免掩盖 CSV 语法问题。
            fmt.Println("parse issue:", err)
            continue
        }
        fmt.Println("accepted:", record)
    }
}

这里的处理顺序有两个要点：先判断 io.EOF，再识别 ErrFieldCount；字段数错误分支先复制记录，再异步写入问题表或日志。若把所有非空错误都直接 continue，虽然程序还会往下读，但异常行的字段内容就丢失了。

Read 返回值为什么不能只看 err

Reader.Read 的返回值是 (record, err)，两者要一起解释：

• 列数不符合固定策略时，返回当前记录和 csv.ErrFieldCount。
• 字段语法无法解析时，返回已经读到的部分记录和解析错误。
• 没有更多数据时，返回 nil, io.EOF。
• 没有错误时，返回完整记录和 nil。

字段数错误和语法错误的区别很重要：前者通常说明数据结构偏离业务约定，后者说明 CSV 引号、转义或字段内容本身无法按 CSV 语法读取。二者都可以进入问题队列，但修复动作不同。

func readOne(reader *csv.Reader) (record []string, kind string, err error) {
    record, err = reader.Read()
    if err == nil {
        return record, "ok", nil
    }
    if errors.Is(err, io.EOF) {
        // EOF 是循环控制信号，不是坏数据。
        return nil, "eof", nil
    }
    if errors.Is(err, csv.ErrFieldCount) {
        // 固定列宽失配仍有 record，调用方可以保存它。
        return record, "field-count", err
    }
    // ParseError 可能携带行、列和已经解析出的部分字段。
    return record, "parse", err
}

上面的辅助函数需要在文件导入包中引入 errors、encoding/csv 和 io。它把“有没有返回值”和“返回值是什么类型”分开，调用方就可以针对不同问题选择重试、人工修复或直接结束。

把可变列导入做成可审计结果

生产导入通常不应只返回一个 error。可以把每一行归入三类：

如果需要记录更准确的原始位置，可以在每次读取后配合 Reader.InputOffset 保存字节偏移；对字段解析错误，还可以将错误断言为 *csv.ParseError，读取它的行、列和底层错误。这里的定位信息服务于问题记录，不改变 FieldsPerRecord 的字段数语义。

另一个容易踩坑的点是 Reader.ReuseRecord。默认情况下，每次 Read 返回由调用方持有的新切片；打开复用后，后续读取可能覆盖之前的底层数组。凡是要放入异步队列、批量缓存或审计表的记录，都应复制后再交给下游。

最后的选择建议

如果列数确实允许变化，用 FieldsPerRecord = -1，然后由业务层保存原始字段并定义允许范围；如果首行定义了模板，用默认的零值语义，让后续失配通过 ErrFieldCount 暴露；如果接口契约固定，则直接设置正数，并在错误分支保存返回的 record。

一句话概括：FieldsPerRecord=-1 解决“能不能读进来”，应用层问题记录解决“这行是否可用”；固定列宽模式下的 ErrFieldCount 解决“它为什么不符合约定”。把三者分开，既不会误报可变列，也不会在容错时丢失异常数据。

相关问题

FieldsPerRecord 等于 0 能读取列数不固定的 CSV 吗？

不能把它当成完全可变模式。零值会使用第一条记录的字段数作为后续期望值，后续不同列数通常会得到 ErrFieldCount。完全可变时应显式设置为负数。

遇到 ErrFieldCount 时 record 一定是 nil 吗？

不一定。字段数不匹配时，Read 会把当前记录和 ErrFieldCount 一起返回，调用方应先复制并保存记录，再决定是否跳过。

为什么解析错误还要保留部分 record？

部分字段可以帮助定位坏行、审计已读取内容和判断修复范围。它不是完整业务记录，不能未经标记直接写入主表。

能用 ReadAll 处理可变列吗？

可以，但需要注意错误策略。ReadAll 会持续读取到 EOF，成功时返回的错误是 nil；如果导入需要逐行保存字段数异常、部分记录或重试信息，直接使用 Read 循环更容易保留上下文。