结构化导出差异比对

问题：diff 告诉你文件变了，却没说业务上发生了什么

周期性导出的 CSV、TSV 或 JSON 快照（订单、用户表、任务结果、埋点分片）总是在变。diff one.csv two.csv 只能告诉你“第 47 行不同”，回答不了下面这些：

• 哪些记录是新增的？
• 哪些记录被删除了？
• 哪些记录还在，但字段值被修改了，改了哪个？
• 这个差异能不能被下游脚本直接消费？

当你需要在同步进数据库、触发告警或写变更日志之前，把两期导出之间的差异讲清楚，你需要的是一份行级变更集（change set），而不是逐行比对的文本。

工作方式：先按稳定键对齐，再分类

这个技能的核心是 csv-diff。它不假设两份文件的行顺序一致，而是先按一个稳定的键（id 这类主键列或字段）把记录对齐，再逐字段比较，把结果分成三类：

• 新增行：只在第二份快照中出现的键
• 删除行：只在第一份快照中出现的键
• 修改行：键相同，但至少一个字段的值变了

输出可以是人类可读的文本，方便直接贴进 issue 或 PR 描述；也可以是机器友好的 JSON，交给同步任务、通知机器人或审计日志解析。两种形态都只包含变化本身，不带无关上下文。

由于底层就是一个 Python 库，你也可以在自己的代码里直接 import，把它嵌进已有数据管道，而不必只当命令行工具用。

适用边界

几个实际会踩的坑：

• 键必须稳定且唯一。 键在两份快照里重复或为空，行的对应关系就会错乱，新增/删除的判定随之失真。没有稳定键的导出无法使用这个方案。
• 只覆盖结构化文件。 输入是 CSV、TSV 或 JSON，格式更松散的（原始日志、XML、嵌套深度不一的 JSON）不在范围内。
• 字段集合变化需显式指定。 两份快照的列或字段不一致时，比较结果取决于你让它关注哪些字段，而不是它自己推断业务含义。
• 它描述差异，不执行同步。 输出是变更集，写入目标系统、重试与补偿仍由你自己的流程负责。
• 环境前置条件：Python 3 与 pip，以及两份可直接比较的快照。上游文档还提供 --extra 这类格式化参数，用于把 {id} 这样的变量注入输出模板。

示例输入很简单，就是一个带 id,name,age 三列的 one.csv——这恰好说明它的价值在于把“键匹配 + 字段级比较 + 变更分类”这套逻辑固化下来，让你不再手写 pandas 脚本。