Go encoding/csv.Reader.ReadAll 读取小表时怎么处理字段数变化

用 Go 的 encoding/csv.Reader.ReadAll 读取一张小 CSV 表时，字段数变化是否报错，关键不在 ReadAll 本身，而在 Reader.FieldsPerRecord。默认值为 0：第一条记录读到几个字段，后续记录就按同样数量检查；如果明确允许每行字段不同，应在第一次读取前设置为 -1。

因此，导入前先决定数据契约：需要严格表格就保留固定字段校验，需要兼容供应商偶尔多列或少列的小表就使用变长模式，读取完成后再按表头整理成稳定对象。

FieldsPerRecord 决定 ReadAll 的字段策略

ReadAll 会持续读取剩余记录，成功时返回的错误是 nil，不会把读到文件末尾当成错误。字段数策略由 FieldsPerRecord 控制：

默认配置下，假设表头有三列，第三条数据只有两列，ReadAll 会返回包含 csv.ErrFieldCount 的解析错误。这个错误说明字段数量不符合契约，不等同于 CSV 引号、分隔符等语法解析错误。

允许变长记录：读取前设置为 -1

设置必须发生在第一次调用 Read 或 ReadAll 之前。下面的示例把一张小表完整读入内存，并保留每行的原始字段切片：

package main

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

func main() {
	input := "name,age,city\n小林,28,杭州\n小周,31\n小吴,26,上海,备注"
	r := csv.NewReader(strings.NewReader(input))

	// -1 表示不校验每行字段数量，适合这里的变长小表。
	r.FieldsPerRecord = -1
	records, err := r.ReadAll()
	if err != nil {
		// 这里仍然要处理引号、分隔符等真正的 CSV 解析错误。
		log.Fatal(err)
	}

	// ReadAll 成功时不会返回 io.EOF，records 中保留每行字段。
	for rowNumber, record := range records {
		fmt.Printf("第 %d 行：%v\n", rowNumber+1, record)
	}
}

这个模式的重点是“只放宽字段数量，不放弃语法解析”。引号没有闭合、字段中出现不合法的引号等问题，仍然会让 ReadAll 返回错误；FieldsPerRecord = -1 只影响列数检查。

读取后按表头整理短行和长行

允许变长记录后，业务层不要直接假设每个 record 都能访问到所有列。更稳妥的做法是把第一行作为表头，短行缺失字段按空字符串处理，长行从约定的额外字段位置开始收集。

package main

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

type Row struct {
	Name  string
	Age   string
	City  string
	Extra []string
}

func field(record []string, index int) string {
	if index = len(record) {
		// 短行没有该列时返回空值，避免下标越界中断整表导入。
		return ""
	}
	return record[index]
}

func main() {
	input := "name,age,city\n小林,28,杭州\n小周,31\n小吴,26,上海,备注"
	r := csv.NewReader(strings.NewReader(input))
	// 先接收不规则行，再由业务层决定如何归一化。
	r.FieldsPerRecord = -1
	records, err := r.ReadAll()
	if err != nil {
		log.Fatal(err)
	}
	if len(records) == 0 {
		return
	}

	for _, record := range records[1:] {
		row := Row{
			Name: field(record, 0),
			Age:  field(record, 1),
			City: field(record, 2),
		}
		if len(record) > 3 {
			// 超出表头的字段不丢弃，单独保留给后续审计或扩展处理。
			row.Extra = append([]string(nil), record[3:]...)
		}
		fmt.Printf("%+v\n", row)
	}
}

示例中的 field 只负责安全取值，真正的业务规则仍应由调用方决定：年龄是否必填、城市是否允许为空、额外列是记录日志还是拒绝导入，都不应该隐藏在 CSV 读取器里。

什么时候应该保留固定字段校验

如果 CSV 是系统导出的固定模板，放宽字段数量反而会掩盖上游变更。此时可以设置明确的正数，或者保留默认的 0 让第一行定义字段数。发现数量错误时，用 errors.Is 区分字段契约问题和其他解析问题：

package main

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

func main() {
	input := "name,age,city\n小林,28,杭州\n小周,31"
	r := csv.NewReader(strings.NewReader(input))
	// 固定三列，任何缺列或多列的记录都应该暴露出来。
	r.FieldsPerRecord = 3

	_, err := r.ReadAll()
	if err == nil {
		fmt.Println("导入成功")
		return
	}
	if errors.Is(err, csv.ErrFieldCount) {
		// 字段数错误通常需要回到模板或上游数据源处理。
		fmt.Println("字段数量不符合约定")
		return
	}
	// 其他错误可能来自引号或分隔符格式，按解析失败处理。
	fmt.Println("CSV 解析失败：", err)
}

固定模式下，问题会尽早暴露；变长模式下，读取范围更宽，但必须补上业务层的归一化和异常记录。两者没有绝对的优劣，选择取决于这张表是“外部不稳定输入”还是“内部稳定契约”。

小结：先选字段契约，再调用 ReadAll

• 默认 FieldsPerRecord = 0 会用第一条记录的字段数约束后续记录。
• FieldsPerRecord = -1 可以让 ReadAll 接收字段数不同的行，但不会关闭 CSV 语法解析。
• 变长读取后要按表头安全取值，短行补空，长行保留额外字段，避免直接下标访问。
• 固定模板导入应保留正数字段数，并用 errors.Is(err, csv.ErrFieldCount) 做针对性提示。

相关问题

FieldsPerRecord 为什么不能在 ReadAll 之后再改？

ReadAll 调用期间已经完成记录读取和字段数判断，之后修改只会影响后续读取，不会改变已经返回的结果。

FieldsPerRecord 设置为 -1 会忽略坏引号吗？

不会。它只关闭字段数量检查，CSV 的引号、分隔符和换行解析仍然按 encoding/csv 的规则执行。

变长 CSV 适合直接映射到结构体吗？

不建议直接按固定下标强行映射。先用表头和安全取值整理出稳定对象，再单独保留缺失字段和额外字段，后续处理更容易追踪。