FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 三个 BOM 字节 0xef 0xbb 0xbf 在用普通 utf-8 解码时会污染第一个列名;utf-8-sig 会自动跳过它们。
  • Python 的 csv 模块默认不会对格式错误的行报错,errors='replace' 也会悄悄插入替换字符,两者都必须切换到严格模式。
  • 黄金测试保存解析器规范化后的输出,编码或分隔符处理一有变化,就会以 diff 的形式出现,等待审查。
分三行的前后对比图。BOM:encoding='utf-8' 丢失客户 ID 列,encoding='utf-8-sig' 则跳过 BOM。编码:errors='replace' 悄悄插入 U+FFFD,errors='strict' 则抛出 UnicodeDecodeError。解析器:strict=False 的 csv.reader 放过损坏的 CSV,strict=True 加黄金测试则让测试在解析器处变红。最后一行以橙色突出显示。
三个会悄悄损坏越南语数据的默认设置,以及应改用的设置。来源:文中引用的 Python 文档(codecs、csv 模块)。

文件开头只要多出三个字节 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 都不会悄悄卷土重来。

这篇文章对你有帮助吗?

5 个信源
路线图上的下一篇 · 阶段 1: 基础认知脚本每晚都记录“Backup OK”,备份却是空的典型交接脚本里有四行会悄无声息地失败,从 cd 进未挂载的目录,到可能清空根文件系统的 rm -rf。