Go encoding/csv Reader FieldsPerRecord 处理变长列

CSV 的列数不一致时，关键设置不是把解析器“放宽”，而是明确告诉 encoding/csv.Reader 如何处理字段数量。Go 中 FieldsPerRecord = -1 表示不检查每条记录的列数；读取仍然会检查引号、分隔符和换行等 CSV 语法。然后由业务代码判断哪些列是必需的、哪些列是可选的。

先看懂 FieldsPerRecord 的三种模式

Reader.FieldsPerRecord 有三种语义。大于 0 时，每一行必须有指定数量的字段；等于 0 时，第一次成功读取会把字段数写回 Reader，之后都按首行的数量检查；小于 0 时不做字段数量检查，记录可以有不同长度。csv.NewReader 返回的默认值是 0，因此直接读取一个“首行 5 列、后面 6 列”的文件，第二行可能得到 ErrFieldCount。

用 -1 读取合法的变长记录

切换到变长模式后，先把每条记录当作字段切片接收，再按列数分支。下面的写法保留了 io.EOF、解析错误和行号信息，适合导入任务的第一层读取。

package main

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

func main() {
	input := "id,name,remark\n1,Ada\n2,Bob,needs-review\n"
	r := csv.NewReader(strings.NewReader(input))
	r.FieldsPerRecord = -1 // 允许每条合法记录拥有不同的字段数

	for {
		record, err := r.Read()
		if err == io.EOF { // 输入结束，正常退出读取循环
			break
		}
		if err != nil { // 引号或分隔符错误不能当作普通缺列
			fmt.Printf("parse failed: %v\n", err)
			continue
		}
		fmt.Printf("fields=%d record=%v\n", len(record), record) // 交给业务层继续校验
	}
}

这里第一条记录有 3 列，第二条有 2 列，第三条有 3 列，都可以被返回。注意，-1 只取消字段数量比较；例如未闭合的引号仍可能返回 *csv.ParseError，不能因为想兼容可选列就把语法错误吞掉。

变长不等于任意列数：补上业务层边界

导入通常不是“几列都收”。例如表头有 id,name,remark，可以接受 2 列和 3 列，但 0 列、超过 3 列或第一列为空都应进入异常分支。校验应围绕业务契约写，而不是重新修改 FieldsPerRecord。

func accept(record []string) (string, bool) {
	if len(record)  3 { // 允许 remark 缺省，但不允许未知列
		return "field-count-out-of-range", false
	}
	if strings.TrimSpace(record[0]) == "" { // 主键为空时不能进入后续写入
		return "missing-id", false
	}
	return "ok", true
}

生产代码还可以把列数、跳过原因和输入偏移写入审计日志。若列数变化代表版本迁移，应先识别表头或文件版本，再映射到内部结构；不要仅靠“多出来的字段先忽略”来隐藏上游协议变化。

排查时分开字段数量错误与语法错误

如果仍使用正数或默认的 0，字段数量不符通常对应 csv.ErrFieldCount。改成 -1 后，这类数量比较不会再阻断读取，但坏引号、非法换行和错误转义仍会报解析错误。排查顺序可以固定为：先确认分隔符和引号规则，再确认 FieldsPerRecord，最后检查业务允许的最小、最大列数。

LazyQuotes 只适合明确知道上游格式不规范且愿意承担歧义的场景，不能用来解决可选列。对于大文件，优先循环调用 Read，避免 ReadAll 一次性把所有记录放进内存；还可以在进入解析器前对单行大小和总输入大小设上限。

常见问题

FieldsPerRecord 设置为 0 能处理变长列吗？

不能。0 会在第一条记录后形成固定列数约束；需要允许不同列数时使用 -1，再自行做业务校验。

设置为 -1 后还会出现 ParseError 吗？

会。-1 只关闭字段数量检查，未闭合引号、错误转义等 CSV 语法问题仍然应该被报告。

什么时候应该坚持固定列数？

当文件要直接映射数据库表、财务字段或外部协议时，应优先固定列数并拒绝异常记录；只有可选字段确实属于契约时才使用变长模式。

最终可以把策略概括为：解析器负责识别合法 CSV，业务层负责解释列数。这样既能兼容可选列，又不会把未知字段和坏输入混成“兼容成功”。