Go csv.Reader 怎样允许每行列数不同并记录缺失字段

CSV 导入时，如果表头有 4 列，但某些数据行只有 3 列，Go 的 encoding/csv 默认会把列数不一致当成错误。要允许这种变长记录，先把 csv.Reader.FieldsPerRecord 设为负值；随后由业务层按表头映射已有值，并显式记录没有出现的字段。

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

本文只解决“每行列数不同怎么办”：不改写 CSV、不自动补齐数据，也不把语法错误隐藏起来。关键是把“读取策略”和“缺失字段的业务决策”分成两层。

先明确 FieldsPerRecord 的三种模式

FieldsPerRecord 控制 Read 是否要求每条记录具有固定列数。它有三种语义，区别不在于 CSV 的分隔符，而在于 Reader 对记录长度的检查方式：

因此，允许变长行的最小配置是 reader.FieldsPerRecord = -1。这只关闭“列数必须一致”的检查，不会关闭 CSV 引号、换行和分隔符的语法解析。

用负值读取变长 CSV

配置为负值后，Read 会按实际内容返回每条记录的字段切片。下面的示例让表头和数据行可以拥有不同长度，并把每条记录原样交给后续的业务映射：

package main

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

func main() {
	input := "order_id,customer,amount,note\nA-1024,Lin Lan,89.50\nA-1025,Wei Chen,120.00,priority\n"
	reader := csv.NewReader(strings.NewReader(input))

	// 负值表示不检查每条记录的字段数量，允许短行和长行共存。
	reader.FieldsPerRecord = -1

	for {
		record, err := reader.Read()
		if err == io.EOF {
			// 读完输入后正常结束循环。
			break
		}
		if err != nil {
			// 列数不一致不会在此处报错，但引号等语法错误仍应返回。
			panic(err)
		}

		// record 保留当前行的实际字段数量，不会自动补空字符串。
		fmt.Printf("fields=%d record=%q\n", len(record), record)
	}
}

这段代码的重点是：第一条表头记录有 4 个字段，第二条记录有 3 个字段，第三条记录有 4 个字段。设置负值后，Reader 返回实际切片，不会为了“对齐”而偷偷增加第四个空字段。

如果只想严格要求固定列数，则不要使用负值。正数模式会把协议要求写在配置里；零值模式则会以第一条成功读取的记录作为列数基准。选哪种模式，取决于文件格式本身是不是允许可选列。

按表头映射并记录缺失字段

csv.Reader 只负责把一行解析成 []string，它不知道“第三列应该叫什么”，也不会替业务决定短行是否可接受。要记录缺失字段，可以先读取表头，再按索引遍历表头，把存在的值放进映射，把没有对应值的列名放进缺失列表。

package main

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

type RowResult struct {
	Values  map[string]string
	Missing []string
}

func mapRow(headers, record []string) RowResult {
	result := RowResult{Values: make(map[string]string)}
	for index, header := range headers {
		if index >= len(record) {
			// 短行没有对应值时，记录字段名而不是伪造一个输入值。
			result.Missing = append(result.Missing, header)
			continue
		}

		// 只把实际返回的字段写入映射，保留空字符串和缺失字段的区别。
		result.Values[header] = record[index]
	}
	return result
}

func main() {
	input := "order_id,customer,amount,note\nA-1024,Lin Lan,89.50\n"
	reader := csv.NewReader(strings.NewReader(input))
	// 读取策略允许变长，是否接受缺失字段由 mapRow 决定。
	reader.FieldsPerRecord = -1

	headers, err := reader.Read()
	if err != nil {
		panic(err)
	}
	record, err := reader.Read()
	if err != nil && err != io.EOF {
		panic(err)
	}

	result := mapRow(headers, record)
	fmt.Printf("values=%v missing=%v\n", result.Values, result.Missing)
}

示例中的短行包含订单号、客户和金额，没有备注。结果可以表达为：Values 保存已有字段，Missing 保存 note。这样，“字段出现但值为空”和“字段根本没有出现”就能由业务层分别处理。

如果文件允许长行，也应提前决定多出的字段怎么处理。例如可以记录“额外字段数量”，或直接把它视为业务错误。不要默认把超出表头的值静默丢弃，否则后续很难判断源文件是否发生了列漂移。

保留坏行与解析错误边界

把 FieldsPerRecord 设成负值，只影响列数检查。它不会让不完整的引号、非法的引号位置或其他 CSV 语法问题自动变成合法数据。读取循环仍然要区分三类结果：

• err == nil：记录已解析，可以交给表头映射。
• err == io.EOF：输入结束，不是坏行。
• 其他错误：保留解析错误并决定跳过、告警或终止导入。

Read 在记录列数不符合固定配置时会返回 ErrFieldCount；但在负值模式下，列数差异不再触发这一类检查。相反，如果一行的引号结构无法解析，仍应把它当作格式问题处理，不能因为“允许变长”就继续使用不完整的结果。

func readRows(reader *csv.Reader, headers []string) ([]RowResult, error) {
	var rows []RowResult
	for {
		record, err := reader.Read()
		if err == io.EOF {
			// EOF 只表示没有下一条记录，不需要包装成导入失败。
			return rows, nil
		}
		if err != nil {
			// 语法解析错误要原样返回，避免把坏行当成缺失字段。
			return nil, fmt.Errorf("read csv row: %w", err)
		}
		rows = append(rows, mapRow(headers, record))
	}
}

这个函数假设调用方已经读取并保存了表头，并且 Reader 已经配置为负值。它只负责三件事：正常记录交给映射、EOF 正常结束、其他错误立即返回。至于缺失字段是否允许入库，则继续由上层根据 RowResult.Missing 决定。

小结

要让 Go csv.Reader 接受每行列数不同的 CSV，设置 FieldsPerRecord = -1，然后按实际字段切片读取。Reader 不会自动补列，缺失字段需要业务层依据表头索引显式记录。最后要保留解析错误边界：宽松的是列数检查，不是 CSV 语法。

相关问题

FieldsPerRecord 设为 0 能允许变长记录吗？不能。零值会以第一条记录的列数为基准，后续列数不同仍可能返回 ErrFieldCount。

负值模式会自动把缺失列补成空字符串吗？不会。Read 返回实际字段切片，补值或记录缺失字段必须由业务代码完成。

为什么设置负值后仍然会报错？负值只关闭列数检查；引号不完整、引号位置非法等 CSV 语法错误仍会返回错误。

短行和空字段有什么区别？短行表示后面的列没有出现；如果列已经出现但内容为空，返回切片中仍会有对应的空字符串。