Go csv.Reader 遇到不定列数怎么处理

Go 的 encoding/csv 读取器遇到每行字段数不一致时，默认会把第一条记录的字段数当成后续约束，于是第二行或更后面的缺列、多列数据可能返回 ErrFieldCount。如果业务允许 CSV 行长度变化，应在第一次读取前设置 FieldsPerRecord = -1，再由业务代码决定缺列如何补齐、额外列如何处理。官方文档入口：https://pkg.go.dev/encoding/csv。

这类问题的关键不是“忽略所有错误”，而是把字段数变化与引号、换行等真正的 CSV 格式错误分开。先关闭固定列数约束，再按表头做显式归一化，程序才能既读得进去，又不会悄悄吞掉坏数据。

• 默认 FieldsPerRecord 为 0：首条记录决定后续期望字段数。
• 设为负数：允许每条记录返回不同长度的字段切片。
• 缺列可以补空值，额外列应拒绝、记录到扩展字段，或交给单独的兼容策略。
• 引号不闭合、裸引号等问题仍属于解析错误，不能靠 FieldsPerRecord 修复。

故障现场：为什么第二行开始突然报 ErrFieldCount

一个导入任务最容易在“供应商增加了一个可选列”时出问题。旧文件的表头和数据行都是三列，新文件在后面的某一行多出一个备注字段；代码仍然直接调用 csv.NewReader 和 Read，日志就会出现 record on line 3: wrong number of fields。看起来像解析器不支持变长 CSV，实际是默认策略在保护调用方。

官方文档把 FieldsPerRecord 的三种状态区分得很清楚：正数要求每条记录具有指定字段数，0 会在第一条记录后设置期望值，负数则不做字段数量检查。因此，问题不是 CSV 必须固定列数，而是代码选择了固定列数的默认模式。

先复现默认行为，再决定要不要放宽约束

下面的示例刻意让第三条数据多出一个字段。代码里的注释只保留关键判断，便于把故障和解决策略对应起来。

package main

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

func main() {
	input := "name,age,city\nAlice,30,Shanghai\nBob,28,Beijing,extra\n"
	r := csv.NewReader(strings.NewReader(input))

	for {
		record, err := r.Read()
		if err == io.EOF {
			break // 文件读完是正常结束，不应当当成失败。
		}
		if err != nil {
			fmt.Printf("record=%v error=%v\n", record, err)
			continue // 这里仅展示故障；生产代码要决定是否留存坏行。
		}
		fmt.Println(record)
	}
}

默认配置下，第一行有三列，后续记录也会被要求有三列。当第四个字段出现时，Read 会返回该记录以及字段数错误。要注意，官方文档还说明：真正的字段解析失败可能只返回已经解析出的部分字段，所以不能只看 record 是否为空来判断成功。

修复动作：在第一次读取前允许字段数变化

如果你的输入协议本来就允许可选列，最小修复是设置 FieldsPerRecord = -1。必须在第一次调用 Read 或 ReadAll 之前完成，否则首条记录可能已经建立了不合适的约束。

package main

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

func main() {
	input := "name,age,city\nAlice,30,Shanghai\nBob,28,Beijing,extra\n"
	r := csv.NewReader(strings.NewReader(input))
	r.FieldsPerRecord = -1 // 允许每行长度不同，列策略交给业务层。

	for {
		record, err := r.Read()
		if err == io.EOF {
			break // Read 读到末尾时用 EOF 结束循环。
		}
		if err != nil {
			return // 引号或其他语法错误不能被“变长”设置掩盖。
		}
		fmt.Printf("%d fields: %v\n", len(record), record)
	}
}

此时读取器只负责把 CSV 记录切出来，不再替你决定第四列是否可以接受。也就是说，FieldsPerRecord = -1 不是“数据已经合法”的证明，而是把字段数量这个判断权交给了更了解业务的代码。

有了变长记录，缺列和额外列要分别处理

工程上最稳妥的做法是把第一条记录当作表头，然后明确目标结构。例如目标结构只有 name、age 和 city 三列：缺少 city 时可以补空值；多出 extra 时则拒绝、告警，或把它保存在扩展字段中。不要简单截断，否则数据提供方增加的重要字段会无声丢失。

package main

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

type Row struct {
	Name string
	Age  string
	City string
}

func readRows(input string) ([]Row, error) {
	r := csv.NewReader(strings.NewReader(input))
	r.FieldsPerRecord = -1 // 先允许变长，再按业务结构归一化。

	header, err := r.Read()
	if err != nil {
		return nil, fmt.Errorf("read header: %w", err)
	}
	if len(header)  3 {
			return nil, fmt.Errorf("line %d has unexpected extra fields: %d", line, len(record)-3)
		}
		for len(record) 

这里选择“额外列即失败”，适合字段契约必须稳定的导入任务。如果供应商确实会持续增加扩展列，可以把 record[3:] 单独保存，并在日志中同时记录源文件、行号和列数；核心原则是让取舍可见，而不是默认丢弃。

把字段数问题和真正的 CSV 格式错误分开

放宽字段数后，仍要对 io.EOF、普通错误和解析错误分层处理。比如双引号没有闭合、非引号字段中出现裸引号，都可能产生 *csv.ParseError；它们与“这一行多了一列”不是同一类问题。对于需要定位源文件的导入服务，还可以读取解析错误里的行号和列号。

package main

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

func readWithErrorClass(input string) error {
	r := csv.NewReader(strings.NewReader(input))
	r.FieldsPerRecord = -1 // 字段数变化不再触发 ErrFieldCount。

	for {
		_, err := r.Read()
		if err == io.EOF {
			return nil // 正常结束。
		}
		if err == nil {
			continue
		}
		var parseErr *csv.ParseError
		if errors.As(err, &parseErr) {
			return fmt.Errorf("csv syntax error at line %d column %d: %w", parseErr.Line, parseErr.Column, err)
		}
		return fmt.Errorf("read csv: %w", err)
	}
}

由于已经设置了负数模式，ErrFieldCount 不再承担字段契约检查。如果业务仍要拒绝额外列，应在拿到 record 后比较长度，而不是期待读取器继续替你报错。

防复发：保留行号，注意 ReuseRecord 的生命周期

故障修好后，导入任务还容易在两处留下隐患。第一，归一化失败时只打印“解析失败”，却不记录输入文件和行号，导致供应商无法修复源数据。第二，为了减少分配而开启 ReuseRecord，但把返回的切片直接存进结果数组；下一次 Read 可能复用同一个底层数组，历史行就会被后续内容覆盖。

如果需要长期保存记录，请复制切片，或在读取循环内立即转换成自己的结构体。只有在处理完当前记录就丢弃它时，才适合依赖复用带来的性能收益。对于大文件，还可以只留坏行摘要和输入偏移，避免日志直接写入敏感字段。

常见问题

把 FieldsPerRecord 设成 -1 后还会报错吗？

会。它只关闭字段数量检查，不能修复不完整引号、非法引号等 CSV 语法错误。遇到这类问题仍应处理 ParseError。

缺列一定要补空字符串吗？

不一定。补空适合“缺失”和“空值”语义相同的协议；如果两者不同，应使用显式的存在标记，或把该行放入待修复队列。

可以直接用 ReadAll 吗？

可以，先设置 FieldsPerRecord = -1 再调用 ReadAll。但大文件通常更适合逐行读取，这样能控制内存，并在发现额外列或格式错误时及时停止。

为什么不直接截取前几列？

截取会掩盖输入协议变化，新增字段可能包含关键业务信息。除非协议明确规定“多出的字段永远无意义”，否则应拒绝或显式留存。

总结一下：先在读取前把 FieldsPerRecord 设为 -1，再基于表头实现自己的字段策略；缺列、额外列和语法错误分别记录。这样既能兼容真实世界里不完全整齐的 CSV，也能让每次数据异常都留下可追踪的处理结果。