# 名字看着一模一样，join 为什么还是对不上

> Unicode 允许一个越南字母有两种存法，不先做规范化，join 会悄无声息地漏掉客户。

原文: https://fdetimes.net/zh/guides/vietnamese-unicode-normalization-nfc-joins/

周五，你在客户办公室，把一份合同清单和对方客户关系管理（CRM）系统里的客户表做 join。结果里偏偏少了“Nguyễn Thị Huệ”这类名字的人。你打开两个文件，逐个核对声调符号：完全一致。可 `==` 依然返回 `False`。

多半没人打错字。常见的罪魁祸首是 Unicode 规范化：两段看起来一模一样的文字，可能用的是不同的码位。越南语尤其容易出这种问题，因为一个字母可以同时带元音符号和声调符号，而几乎每句话都满是带符号的字母。

对前线部署工程师（FDE）来说，这不是无关紧要的技术细节。join 出错不会报错，它只会悄悄丢掉一部分客户，而最先发现问题的，很可能是客户而不是你。

## 一个“ệ”，两种存法

Unicode 定义了*规范等价*（canonical equivalence）：不同的码位序列可以表示同一个字符。字母“ệ”可以存成一个预组合码位，也可以存成基础字母“e”，后面跟着下点和抑扬符两个组合符号。

这两种存法对应两种规范化形式。NFD 是规范分解：Python 文档将其描述为把每个字符转换为分解形式。NFC 先分解，再重新组合成预组合字符。

Unicode 标准附录 #15（UAX #15）写得很直白：这些规范化形式的目的，是让软件能判断两个 Unicode 字符串是否等价。

关键就在这里。比较字符串时，机器看的是字节，而不是字母长什么样。一篇介绍 Apple 文件系统的文章描述的正是这种现象：两段外观完全相同的文字，用的却是不同的码位。

**要点:** 看起来一样的两个字符串，字节序列未必相同。

## NFD 数据从哪来？

客户的每个系统各产出哪种形式，你很少能确切知道。所以最好记住几个常把 NFD 字符串悄悄带进数据的来源。

最常见的一个是从 Mac 导出的文件名。macOS 较早的文件系统 HFS+ 以 NFD 存储文件名：即使你用 C 形式命名，系统也会转成 D 形式。较新的文件系统 APFS 完全不做规范化，因此两个看起来相同的文件名，可能因创建它的程序不同而带着不同的码位。

回到开头的场景。法务团队给你发来一个合同 PDF 文件夹，每个文件以客户名命名，都是从 Mac 导出的。你从文件名中取出客户名，和通过网页表单录入的 CRM 表做 join。如果一边是 NFD、另一边是 NFC，所有带声调的名字都有被漏掉的风险。

## 可运行示例：join 为什么会漏

下面这段 Python 代码复现了上述情况。

```python
import unicodedata as ud


crm = "Nguyễn Thị Huệ"                    # 通过网页表单录入，NFC 形式

from_filename = ud.normalize("NFD", crm)  # 模拟从 Mac 导出的文件名中取出的名字


print(crm == from_filename)                 # False

print(len(crm), len(from_filename))         # 14 19

print(ud.normalize("NFC", from_filename) == crm)  # True

```

（注释的意思是：“通过网页表单录入，NFC”和“模拟从 Mac 导出的文件名中取出的名字”。）

数一数码位。在 NFC 中，“Nguyễn Thị Huệ”有 14 个字符。在 NFD 中，“ễ”变成三个码位（e、抑扬符、波浪符），“ị”变成两个，“ệ”变成三个，于是字符串长度为 19。多出来的这五个码位，足以让每一次比较、每一个哈希键、每一个数据库索引都把它们当成两个人。

长度不一致还会引出第二个 bug。越南语 Unicode FAQ 指出，只有“ệ”处于 NFC 时，长度计算才总是返回 1；在其他形式下，Java 或 C# 等语言会返回不同的长度。

像“姓名最多 50 个字符”这样的校验规则，可能仅仅因为名字来自 Mac，就拒绝一个完全合法的名字。

## 解决办法：在入口处规范化一次

第一步是先测量再修复。从 Python 3.8 起，`unicodedata.is_normalized` 可以告诉你一个字符串是否已经是指定的规范化形式。这是成本最低的数据质量检查。

```python
def audit(values, form="NFC"):
    mismatched = [v for v in values if not ud.is_normalized(form, v)]
    return len(mismatched), mismatched[:5]

def make_key(name: str) -> str:
    return ud.normalize("NFC", name).strip()
```

第二步是选定一种规范化形式并坚持使用。越南语选 NFC。W3C 建议从旧编码转码而来的文本最终应为 NFC；越南语 Unicode FAQ 也更推荐预组合字符，因为它们更易于处理和显示，打印效果也更好。

第三步是在边界处规范化：数据一进入管道就处理，并且 join 两侧都要处理。在 pandas 中只需一行：`df["key"] = df["customer_name"].map(make_key)`。原始列保持不动，客户问起时可以对照核查。

最后一步是报告数字。规范化前后，匹配数量变化了多少？像“NFC 规范化后，又有 N 份合同匹配到了对应客户”这样一句话，正是让客户信任你数据管道的那种证据。

## 常见错误

最常见的错误是图省事直接去掉声调。用不带声调的字符串做 join 当然能匹配上，但“Huệ”和“Huế”、“Lan”和“Lân”会合并成一个。你用一个容易发现的数据缺失 bug，换来一个更难发现的、把记录分配给错误客户的 bug。

第二个错误是只规范化一侧。你修好了手里的文件，但客户数据库里的表可能还留着几行早年导入的 NFD 数据。

W3C 的原则在这里适用：规范等价的字符串必须被视为完全相同，因此所有地方的比较都必须经过同一个函数。

第三个错误是因为 NFKC 或 NFKD 看起来“更强”就改用它们。W3C 提醒，兼容分解会丢失含义：上标“²”会被折叠成“2”，连字“ﬁ”会被折叠成“fi”。对越南语客户名这类键，NFC 就够了。

最后一个错误是相信自己的眼睛。两个“相同”的字符串匹配不上时，别再盯着屏幕看，打印 `len()` 或码位列表。这个习惯能帮你省下一整个下午。

## 从修好一个 join 到简历上的一行

上面四个步骤也是很好的简历素材。

不要写“精通 Unicode”。描述实际做法：用 `is_normalized` 测量，在入口处对 join 两侧统一规范化为 NFC，把匹配率从 X 提升到 Y。这样一行字能让招聘经理看到，你能在客户发现之前找出无声的 bug。

下次 join 莫名其妙少了几行，先问的不是“谁打错了字？”，而是“这个字符串是哪种规范化形式？”

**本周动手试试:**

- 在当前项目里选一列客户名，对每一行运行 unicodedata.is_normalized('NFC', ...)，统计未规范化的行数。
- 在 Mac 上创建一个名为“Nguyễn Thị Huệ.txt”的文件，在 Python 中读取文件名，打印 len()，并与手动输入的字符串比较。
- 写一个所有处理越南语数据 join 的管道共用的 make_key() 函数，并加一个使用 NFD 字符串的单元测试。

## 信源

- [UAX #15: Unicode Normalization Forms (Unicode 18.0.0, revision 58)](https://unicode.org/reports/tr15/)

- [Character Model for the World Wide Web: String Matching (W3C First Public Working Draft)](https://www.w3.org/TR/charmod-norm/)

- [unicodedata — Unicode Database (Python 3.14.8 documentation)](https://docs.python.org/3/library/unicodedata.html)

- [Explainer: Unicode, normalization and APFS](https://eclecticlight.co/2021/05/08/explainer-unicode-normalization-and-apfs/)

- [Vietnamese Unicode FAQs](https://vietunicode.sourceforge.net/faq.htm)
