三个看不见的字节,悄悄弄坏客户的 CSV 文件
Excel 为正确显示越南语而加上 BOM;小型 Python 解析器加黄金测试,能让它和另两个静默 bug 现形。
要点速览
- 三个 BOM 字节 0xef 0xbb 0xbf 在用普通 utf-8 解码时会污染第一个列名;utf-8-sig 会自动跳过它们。
- Python 的 csv 模块默认不会对格式错误的行报错,errors='replace' 也会悄悄插入替换字符,两者都必须切换到严格模式。
- 黄金测试保存解析器规范化后的输出,编码或分隔符处理一有变化,就会以 diff 的形式出现,等待审查。
文件开头只要多出三个字节 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、分号分隔符,以及一个在双引号内换行的地址。
# 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。如果客户用的是这两种之一,就需要单独的转换工具。
# 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。解析器照常运行,但写入客户系统的数据里,带变音符号的字母已经变成了小方框。
尝试编码的顺序同样重要。UTF-8 结构严格,用其他编码写成的文件很可能让它解码失败。
cp1258 这样的单字节代码页则宽松得多:绝大多数字节序列都能解码,哪怕结果是一堆乱码。一行代码就能看出来:把一个名字的 UTF-8 字节误当成 cp1258 解码:
>>> "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”的地址正是这种情况。不加这个参数,一个客户可能被拆成两行残缺的数据。
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 可能选错。
因此需要一个独立的校验,依据是在需求调研阶段从客户那里确知的信息:列数。
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 解析器规范化后的输出,天然适合这样做。
# 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 都不会悄悄卷土重来。
这篇文章对你有帮助吗?
感谢你的反馈!