Go encoding/csv Reader.FieldsPerRecord 如何处理列数变化：严格校验与按行读取

订单导入脚本有个很典型的坑：供应商把一条备注拆成了额外一列，程序却只报“列数不对”，没有告诉你应该严格拒绝，还是先读进来再按业务规则处理。Go 的 encoding/csv.Reader 把这个选择收敛在 FieldsPerRecord 上。

FieldsPerRecord 为正数时固定校验列数，为 0 时用第一条记录定下期望列数，为负数时允许每条记录列数不同。生产导入不要依赖默认值，先按文件契约明确选一种模式。

先把列数变化复现出来

假设导入文件有表头、两条正常订单和一条多出备注列的订单。把 FieldsPerRecord 设为 3，每次调用 Read 都会检查当前记录的字段数量。

package main

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

func main() {
    input := "order_id,sku,quantity\nA001,G-100,2\nA002,G-200,1,urgent\n"
    reader := csv.NewReader(strings.NewReader(input))
    reader.FieldsPerRecord = 3

    for {
        record, err := reader.Read()
        if errors.Is(err, io.EOF) {
            break
        }
        if err != nil {
            var parseErr *csv.ParseError
            if errors.As(err, &parseErr) {
                fmt.Printf("line=%d err=%v\n", parseErr.Line, parseErr.Err)
            }
            continue
        }
        fmt.Println(record)
    }
}

这段程序会先打印表头和 A001，读到 A002 时进入错误分支。错误内部的 Err 是 csv.ErrFieldCount，而 Line 能把问题定位到实际记录。这里别只打印一条字符串，保留 ParseError 的行号，排查大文件会省很多时间。

三种 FieldsPerRecord 模式分别意味着什么

正数：把列数当成文件契约

设置为 3 就表示每条记录都必须有三列。这个模式适合导出格式由接口或供应商协议固定的文件。字段数量错了就拒绝该行，调用方可以把错误行写入隔离文件，避免把错位数据落进订单表。

零值：让第一条记录建立基线

默认值 0 并不是“完全不检查”。第一次成功解析记录后，Reader 会把 FieldsPerRecord 更新为该记录的字段数，后续记录必须保持一致。若文件有表头，表头列数自然会成为基线；如果供应商把表头漏掉一列，后面的数据会被按错误基线检查。

负数：接受可变列，但不替业务兜底

设置为 -1 会跳过列数检查，每条记录都可以返回不同长度的 []string。它适合尾部扩展字段确实允许变化的文件，但随后要明确最少字段数，并只读取业务需要的索引。

可变列文件应该怎样逐行接住

当文件格式允许在第三列之后追加备注、渠道或扩展属性时，可以选择 FieldsPerRecord=-1，但不要直接访问 record[3]。先校验必需字段，再把剩余部分作为可选数据。

reader := csv.NewReader(input)
reader.FieldsPerRecord = -1

for {
    record, err := reader.Read()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    if len(record) 

逐行读取的好处是可以在发现第一条坏记录时停止，或者把它送进隔离队列。相比 ReadAll 一次性加载，Read 更适合体积不确定的导入文件；如果要先确认整份文件没有列数错误，再统一写库，则应使用正数模式并在提交事务前读完。

ReadAll、表头和 ParseError 的几个边界

ReadAll 会持续读取直到 EOF；只要中途出现解析错误，它就返回已经读取的记录和错误。不要因为前面拿到了部分数据就直接入库。固定列数时，ErrFieldCount 同样会被包装在 ParseError 中，可以用 errors.As 提取行号。

如果第一行是表头，建议显式读取并检查列名，再开始处理数据行。列名检查解决“字段顺序错了”的问题，FieldsPerRecord 只解决“字段数量对不对”的问题，两者不能互相替代。

常见问题：到底该选哪一种

为什么默认的 0 不是“忽略列数”？

因为它会用第一条记录的字段数建立基线，后续记录仍然会校验。需要完全可变列时应显式设置为负数。

列数错误时能不能只跳过这一行？

可以在逐行 Read 中记录 ParseError.Line 后继续，但要确认业务允许部分成功；订单、财务等场景通常还要保留隔离文件和导入摘要。

FieldsPerRecord 能检查字段类型吗？

不能。它只检查数量，数量正确的 quantity 仍可能不是整数，日期也可能不符合格式，类型校验必须在业务层完成。

什么时候使用 ReadAll 更合适？

文件较小、需要在写库前一次性检查完整内容时可以使用；大文件或希望及时处理、及时报告坏行时，优先使用 Read。

把列数策略写在初始化代码旁边，后续维护者才能看懂这份 CSV 是“严格协议”还是“可扩展记录”。固定格式用正数，首条记录可信时才用零值，真正允许变化时再用负数并补上业务层的最少字段校验。