Go encoding/csv跳过表头并校验列数的实现方法

处理 CSV 导入时，跳过表头不应该靠“先读一行再不管它”草草结束。更稳妥的做法是：先用 Reader.Read() 消费第一条记录，确认它确实是预期表头，再把 FieldsPerRecord 设为固定列数。这样，后续数据行一旦少列或多列，encoding/csv 会返回 csv.ErrFieldCount，业务代码不会把错位字段继续写入数据库。

先读表头并确认输入契约

假设导入文件的列顺序是 sku,name,price，数据行必须正好有 3 列。表头读取成功只说明第一条 CSV 记录能被解析，不代表它就是正确的表头；因此还应检查列数，必要时检查字段名。检查通过后再进入数据循环，边界会清楚很多。

package main

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

func readProducts(src io.Reader) error {
    reader := csv.NewReader(src)

    // 第一条记录只作为表头，先验证列数和字段名，再处理数据。
    header, err := reader.Read()
    if err != nil {
        return fmt.Errorf("读取 CSV 表头失败: %w", err)
    }
    expected := []string{"sku", "name", "price"}
    if len(header) != len(expected) {
        return fmt.Errorf("表头列数为 %d，期望 %d", len(header), len(expected))
    }
    for i := range expected {
        if header[i] != expected[i] {
            return fmt.Errorf("第 %d 列表头为 %q，期望 %q", i+1, header[i], expected[i])
        }
    }

    // 正数表示后续 Read 必须拥有完全相同的列数。
    reader.FieldsPerRecord = len(expected)
    for rowNo := 2; ; rowNo++ {
        record, err := reader.Read()
        if errors.Is(err, io.EOF) {
            return nil // 读完所有合法数据行。
        }
        if errors.Is(err, csv.ErrFieldCount) {
            return fmt.Errorf("第 %d 条数据列数不符: %w", rowNo, err)
        }
        if err != nil {
            return fmt.Errorf("第 %d 条数据解析失败: %w", rowNo, err)
        }

        // 只有通过列数校验的记录才进入业务处理。
        fmt.Printf("sku=%s name=%s price=%s\n", record[0], record[1], record[2])
    }
}

func main() {
    // 示例输入包含表头和两条三列数据。
    input := "sku,name,price\nA-01,键盘,99\nA-02,鼠标,49\n"
    if err := readProducts(strings.NewReader(input)); err != nil {
        panic(err)
    }
}

这里“跳过表头”发生在第一次 Read 之后，而不是通过读取底层字节流寻找换行符。这样可以保留 CSV 的引号、逗号和跨行字段规则。表头字段名是否大小写敏感，则由业务契约决定；如果只关心列数，可以省略字段名比较，但不建议省略列数检查。

用 FieldsPerRecord 让列数错误尽早暴露

FieldsPerRecord 有三个典型取值：正数表示固定列数，0 表示用第一条记录的列数作为后续基准，负数表示不检查列数。本文已经显式消费了表头，所以用正数最直观，也避免某个格式错误的表头把错误列数“注册”为合法标准。

常见误区是把 FieldsPerRecord 留在默认值 0，同时又把表头当作普通数据读掉。那样会让表头列数成为隐含约束，代码读者很难判断这是刻意设计还是遗漏配置。固定的业务结构应该直接写成正数或由已经验证过的表头长度得到。

把列数错误和 CSV 语法错误分开处理

列数不对与 CSV 本身写坏不是一类问题。前者通常意味着上游导出字段变化、逗号错位或文件版本不一致；后者可能是未闭合引号、非法引号或字段格式无法解析。调用方至少要保留这两类错误的语义，才能决定是提示重新导出，还是定位某条坏记录。

// 这个辅助函数把 CSV 读取错误转换成可定位的中文信息。
func readOne(reader *csv.Reader, rowNo int) ([]string, error) {
    record, err := reader.Read()
    if errors.Is(err, csv.ErrFieldCount) {
        // ErrFieldCount 说明记录已读到，但字段数量违反契约。
        return nil, fmt.Errorf("第 %d 条记录列数错误: %w", rowNo, err)
    }
    if err != nil {
        var parseErr *csv.ParseError
        if errors.As(err, &parseErr) {
            // ParseError 适合把行号、列号等语法定位信息带回调用方。
            return nil, fmt.Errorf("第 %d 条记录存在 CSV 语法错误: %w", rowNo, err)
        }
        return nil, fmt.Errorf("第 %d 条记录读取失败: %w", rowNo, err)
    }
    return record, nil
}

如果需要继续收集所有坏行，可以在循环中记录错误并跳到下一条；但财务、库存等强一致导入更适合遇到第一条结构错误就终止。无论采用哪种策略，都不要在 err != nil 时无条件使用返回的 record，因为解析错误时它可能只是部分字段。

让校验先于入库或转换

最后一个落地点是业务顺序：表头验证、列数约束、CSV 语法处理应发生在类型转换和数据库写入之前。比如价格字段要转成数字时，再单独检查空值和格式；列数校验不能替代字段内容校验。这样一行数据的失败原因不会被后面的数组访问或类型转换错误覆盖。

• 文件打开成功不等于表头合法。
• 表头合法不等于所有数据行列数一致。
• 列数一致也不等于字段内容满足业务类型。

相关问题

把 FieldsPerRecord 设为 0 是否也能校验列数？

可以，它会用第一条记录的列数作为基准。但如果第一条是未经验证的表头，约束就变成了隐式规则；已经知道固定列数时，正数更清晰。

ErrFieldCount 时返回的 record 能不能继续用？

不建议直接用。它可能包含读到的字段，但这条记录已经违反结构契约；应记录错误、跳过或终止，而不是继续入库。

CSV 有多行字段时 rowNo 会不会和物理行号不同？

会。CSV 的一条记录可能跨越多行；需要语法定位时使用 csv.ParseError 提供的位置信息，不要只把业务记录序号当成物理行号。

把表头当作一次有意义的读取，再用 FieldsPerRecord 固定后续契约，Go 的 CSV 导入就能在进入业务逻辑前挡住最常见的错位数据。剩下的字段类型、空值和重复键校验，再交给各自的业务层处理。