# 三个看不见的字节，悄悄弄坏客户的 CSV 文件

> Excel 为正确显示越南语而加上 BOM；小型 Python 解析器加黄金测试，能让它和另两个静默 bug 现形。

原文: https://fdetimes.net/zh/guides/csv-encoding-bom-golden-tests/

文件开头只要多出三个字节 `0xef 0xbb 0xbf`，数据管道就找不到“Customer ID”这一列。代码不会抛出任何异常，只是悄悄生成一个开头带不可见字符的列名，之后所有按这个列名的查找都会失败。

做前线部署工程师（FDE）时间一长，迟早会碰上这个问题。客户从 Excel、老旧的财务软件或第三方系统导出数据，发来一个 CSV 文件。越南语文本，或任何带变音符号的语言，都会暴露三个经典 bug：编码、BOM 和分隔符。

本指南会搭建一个基于 Python 标准库的小型解析器，一次处理这三个问题，再用黄金测试（golden test）锁定它的行为。只需要 Python 3 和 pytest。为便于阅读，代码做了精简，用于真实项目前请补上日志和错误处理。

## 为什么客户文件经常带 BOM？

据 Python 文档，字节顺序标记（BOM）就是字节序列 `0xef 0xbb 0xbf`。这是源自微软记事本的一种 UTF-8 变体，Python 把对应的编解码器命名为 `utf-8-sig`。BOM 不是客户自己加的，而是他们用的软件加的。

罪魁祸首是 Excel。Chase Seibert 在 2014 年的一篇文章中指出，Excel 2007、2010 和 2013 只有在文件带 BOM 时才能识别 UTF-8。

没有 BOM，越南语的变音符号就会显示成乱码，所以导出工具会插入 BOM，让 Excel 正确显示。结果就是：送到你手上的文件常常带 BOM，而不带 BOM 的文件，客户用 Excel 打开时往往会出现乱码。

同一篇文章还指出了另一个陷阱：如果文件同时带有 BOM 和顶部的 `sep=,` 行，Windows 版 Excel 会忽略 BOM。这篇文章写于 2014 年，请在客户实际使用的 Excel 版本上验证。即便如此，只要看到文件顶部有 `sep=` 行，首先就该想到这个 bug。

## 第 1 步：构造一个与客户文件相似的样例

先准备一个包含所有棘手情况的文件：BOM、分号分隔符，以及一个在双引号内换行的地址。

```python
# make_fixture.py
from pathlib import Path

FIX = Path("tests/fixtures")
FIX.mkdir(parents=True, exist_ok=True)
text = ('Customer ID;Full name;Address\r\n'
        'C01;Anna Wałęsa;"12 Ly Thuong Kiet Street\r\nWard 7"\r\n')
(FIX / "bom_semicolon.csv").write_bytes(text.encode("utf-8-sig"))
```

**检查：**运行 `python -c "print(open('tests/fixtures/bom_semicolon.csv','rb').read(3))"`，输出必须是 `b'\xef\xbb\xbf'`。对于旧编码的文件，不要自己编造样例：向客户要一份真实文件并做匿名化处理。样例越接近真实数据，测试就越有价值。

## 第 2 步：先读字节，再判断编码

最常见的错误，是用 `encoding="utf-8"` 打开文件就以为万事大吉。遇到带 BOM 的文件，BOM 字符会粘在第一个列名的开头。据 Python 文档，如果文件的前三个字节是 BOM，`utf-8-sig` 编解码器会跳过它们，这就是直接的解决办法。

如果文件不是合法的 UTF-8，Python 还为越南语提供了 `cp1258` 编解码器，即 windows-1258。Python 的标准编码表里既没有 TCVN，也没有 VISCII。如果客户用的是这两种之一，就需要单独的转换工具。

```python
# customer_csv.py
CANDIDATES = ("utf-8-sig", "cp1258")

def detect_encoding(raw: bytes) -> str:
    for enc in CANDIDATES:
        try:
            raw.decode(enc, errors="strict")
            return enc
        except UnicodeDecodeError:
            continue
    raise ValueError("无法用任何已知编码解码该文件")
```

关键在于 `errors="strict"`。据 Python 文档，这是默认值，遇到非法字节会报错。而 `errors="replace"` 会在损坏处悄悄插入字符 U+FFFD。解析器照常运行，但写入客户系统的数据里，带变音符号的字母已经变成了小方框。

**要点:** 最危险的编码 bug，是不抛出任何异常的那种。

尝试编码的顺序同样重要。UTF-8 结构严格，用其他编码写成的文件很可能让它解码失败。

cp1258 这样的单字节代码页则宽松得多：绝大多数字节序列都能解码，哪怕结果是一堆乱码。一行代码就能看出来：把一个名字的 UTF-8 字节误当成 cp1258 解码：

```python
>>> "Wałęsa".encode("utf-8").decode("cp1258")
'WaÅ‚Ä™sa'
```

没有异常，只有一个被弄乱的名字。所以一定要先尝试 `utf-8-sig`，再由第 5 步的黄金测试捕捉误选 cp1258 的情况。

## 第 3 步：用 newline='' 打开文件

`csv` 模块文档写得很明确：如果不指定 `newline=''`，引号字段内嵌的换行符将无法被正确解析。从“12 Ly Thuong Kiet Street”换行到“Ward 7”的地址正是这种情况。不加这个参数，一个客户可能被拆成两行残缺的数据。

```python
import csv

def parse_file(path, expected_cols: int) -> list[list[str]]:
    raw = open(path, "rb").read()
    enc = detect_encoding(raw)
    with open(path, encoding=enc, errors="strict", newline="") as f:
        sample = f.read(4096)
        f.seek(0)
        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t|")
        rows = list(csv.reader(f, dialect, strict=True))
    check_columns(rows, expected_cols)
    return rows
```

**检查：**运行 `print(parse_file("tests/fixtures/bom_semicolon.csv", 3))`，应该恰好得到两行。第一个单元格必须是 `'Customer ID'`，前面没有 `'﻿'`，地址单元格里必须包含换行符。

## 第 4 步：不要完全相信 Sniffer

`csv.Sniffer` 用来推断文件格式。文档允许传入 `delimiters` 参数，限定哪些字符可以作为分隔符，这里是逗号、分号、制表符和竖线。这样可以防止 Sniffer 选中数据里某个无关的字符。

但 Sniffer 仍有弱点。据文档，当 `,` 和 `;` 都能把每一行切分得一样整齐时，Sniffer 会按照 `preferred` 属性里的优先顺序来选，而不管每个字符出现了多少次。

设想一家经销商的文件，价格列写成“125,5”，分隔符是分号。如果每一行的价格单元格数量相同，逗号切分每一行的一致性就和分号一样，Sniffer 可能选错。

因此需要一个独立的校验，依据是在需求调研阶段从客户那里确知的信息：列数。

```python
def check_columns(rows, expected_cols):
    for i, row in enumerate(rows):
        if len(row) != expected_cols:
            raise ValueError(f"第 {i} 行：{len(row)} 列，预期 {expected_cols} 列")
```

`csv.reader` 的 `strict=True` 参数也并不多余。据文档，默认 Dialect 使用逗号并设置 `strict=False`，格式错误的 CSV 会一声不响地通过。打开 strict 后，错误会停在解析器这一层，不会继续污染下游数据。

## 第 5 步：用黄金测试锁定解析器的行为

解析器现在能用了。问题在于，下周可能有同事为了“减少报错”加上 `errors="replace"`，或者调换尝试编码的顺序。

TensorFlow Federated 文档对黄金测试的定义是：当你希望开发者知道自己的代码改变了某个函数的输出时，就该用这类测试。

CSV 解析器规范化后的输出，天然适合这样做。

```python
# tests/test_golden.py（节选）
import json, os
from pathlib import Path
import pytest
from customer_csv import parse_file

HERE = Path(__file__).parent

@pytest.mark.parametrize("name", ["bom_semicolon.csv"])
def test_golden(name):
    rows = parse_file(HERE / "fixtures" / name, expected_cols=3)
    actual = json.dumps(rows, ensure_ascii=False, indent=2)
    gold = HERE / "golden" / f"{name}.json"
    if os.environ.get("UPDATE_GOLDEN"):
        gold.parent.mkdir(exist_ok=True)
        gold.write_text(actual, encoding="utf-8")
    assert actual == gold.read_text(encoding="utf-8")
```

第一次运行 `UPDATE_GOLDEN=1 pytest` 生成参考文件，然后打开 JSON，逐个单元格核对。如果不想自己写，pytest-goldie 插件提供了 `golden` fixture 和用于覆盖已存输出的 `update_goldens` 标志。

黄金测试最常见的错误，是更新参考文件却不去读它。TensorFlow Federated 文档强调，重新生成黄金文件后，必须审查 diff 里有没有意外变化。diff 中“Wałęsa”变成“WaÅ‚Ä™sa”，正是第 2 步提醒过的误选 cp1258 的 bug。

## 这项技能在客户现场如何落地？

到客户那里的第一天，在写下任何一行转换代码之前，先向每个源系统要三到五份样例文件。全部放进 `tests/fixtures`，坏文件也不例外，并为每份文件建立黄金测试。

客户发来的新文件把解析器搞崩了，就把它加入 fixtures，修复代码，再读 diff。每一次事故都变成一个新测试。

阅读 FDE 招聘启事时，留意关于集成或接入客户数据的描述：出现这类字样，指的就是这项工作。简历上不要只写“CSV 处理”。

要写得更具体，比如：为客户数据导入搭建了黄金测试套件，在数据进入生产环境之前就发现了编码 bug。一个附带真实、已匿名化 fixtures 的小仓库，比这样的描述更有说服力。

客户数据里永远会有你没见过的 bug。黄金测试能保证，每一个修过的 bug 都不会悄悄卷土重来。

**本周动手试试:**

- 找一份真实的客户 CSV 文件，做匿名化处理，然后运行 python -c "print(open('file.csv','rb').read(3))"，看它是否以 BOM 开头
- 在目前使用的解析器里，找出所有 errors='replace' 和所有缺少 newline='' 的地方，按上面的步骤修正
- 创建 tests/fixtures 和 tests/golden 文件夹，为一份客户样例文件写下第一个黄金测试

## 信源

- [codecs — Codec registry and base classes (Python docs)](https://docs.python.org/3/library/codecs.html)

- [csv — CSV File Reading and Writing (Python docs)](https://docs.python.org/3/library/csv.html)

- [Creating International CSV files with Python](https://chase-seibert.github.io/blog/2014/07/30/international-csv-files-python.html)

- [Golden Testing (TensorFlow Federated)](https://tensorflow.org/federated/golden_tests?hl=en)

- [pytest-goldie (PyPI)](https://pypi.org/project/pytest-goldie/)
