# 客户的 CSV 迟早出错，让数据管道直接拒收

> MIT 许可的 Pandera 把合同条款写成 DataFrame 模式，在报告出错前指出出错的列、规则和值。

原文: https://fdetimes.net/zh/tools/pandera-dataframe-schema-validation/

`year` 列里出现一个 1999，通常没人注意。一周后，一份客户报告带着错误的数字发了出去，团队花两天才追查到源头。Pandera 能帮你在入口处拦下这类错误：数据校验失败时，它会准确报出是哪一列、违反了哪条规则、哪个值出了问题。

对前线部署工程师（FDE）来说，这一点比对产品工程师更重要。在自己公司，数据源由你掌控；到了客户现场，情况正好相反：数据经过别人的系统，用别人的工具导出，文档往往比数据本身还旧。

`unionai-oss/pandera` 仓库的自我介绍是一个轻量级的统计数据测试库，由 Niels Bantilan 编写和维护，目标是让数据处理管道更易读、更健壮。理解它最快的办法，是动手写一个模式。

## 模式长什么样？

假设客户是一家零售连锁企业，给你发来一份订单文件。合同写明，只有 2000 年之后的数据在范围内。你的任务是把这句话变成代码，让数据管道自己拒收坏文件，而不是悄悄把它处理完。

使用 pandas 时，用 `pip install 'pandera[pandas]'` 安装。然后用类似 pydantic 的写法声明模式：写一个继承 `DataFrameModel` 的类，每一列是一个类属性。

```python
import pandas as pd
import pandera.pandas as pa
from pandera.typing import DataFrame, Series

class Orders(pa.DataFrameModel):
    order_id: Series[str]
    year: Series[int] = pa.Field(gt=2000)

@pa.check_types
def load_orders(df: DataFrame[Orders]) -> DataFrame[Orders]:
    return df

raw = pd.DataFrame({"order_id": ["A1", "A2"], "year": [2021, 1999]})
load_orders(raw)
```

运行这段代码，第二行会被拦下。Pandera 文档中给出了类似的报错信息：`year` 列未通过 `greater_than(2000)` 校验器，失败用例是 `1999`。一行信息里就有三要素：哪一列、哪条规则、哪个值。

## 第一个坑：注解本身什么都不检查

很多新手以为在函数签名里写上 `DataFrame[Orders]` 就够了。并非如此。Pandera 文档写得很清楚：要在运行时校验 DataFrame，必须使用 `check_types()` 装饰器。所以上例如果少了 `@pa.check_types` 这一行，1999 会毫无警告地溜过去。

这个错误之所以危险，是因为代码看上去很让人放心。评审者看到类型注解，看到模式，就以为数据有了保护。在客户现场审查数据管道时，要检查的是接收数据的函数上是否真的挂了装饰器，而不只是模式是否存在。

**要点:** 没有执行机制的模式，什么也校验不了。

## 第二个坑：以为模式覆盖了一切

模式只守护你写下的规则。上例中，`year` 带有 `gt=2000` 条件，而 `order_id` 只声明了类型，没有其他约束。如果最终报告还依赖一个你没写进类里的营收列，那一列就毫无保护，尽管数据管道照样跑得一片“绿”。

避免的办法是从输出倒推：列出发给客户的数字所依赖的每一列，再逐一确认它们在模式里都有规则。

## 第三个坑：升级会改变校验行为

在 PyPI 上，Pandera 的最新版本是 0.35.0，也就是说这个库还没到 1.0。对仍处于 0.x 的库，要预期 API 可能在版本之间变化。

因此，把 Pandera 引入客户的代码仓库时，要在依赖文件里锁定版本。你不希望某次重装环境之后，模式的校验方式悄悄变了却没人察觉。

## 报错信息就是给客户的问题

Pandera 对 FDE 最大的价值，出现在报错之后。“你们的数据有问题”这种话没有下文。而“`year` 列里有 1999 这个值，约定的范围是 2000 年之后；这一行是删掉，还是扩大范围？”这样的问题，客户当天就能答复。

所以模式同时承担两项工作。它是代码里的技术护栏，也是你和客户在数据上达成共识的记录。客户改主意时，你只需改类里的一行，提交历史会清楚记下谁在什么时候同意了什么。

## 先学什么？

从能跑起来的最小单元开始：为客户最重要的那张表写一个 `DataFrameModel`，再给第一个加载函数加上 `check_types`。暂时不必覆盖所有列。

从职业发展看，这项技能很容易展示。简历上与其写“熟练使用 pandas”，不如描述你如何在客户数据管道的入口处加上模式校验，并说明它拦下了哪些类型的错误。岗位描述里提到“data quality”或“messy customer data”时，面试中正好讲这个故事。

每次进驻客户现场的第一周，总会在某处冒出一个 1999。区别只在于，你是在加载环节就发现它，还是等客户来问报告为什么错了。

**本周动手试试:**

- 安装 pandera[pandas]，为一张来自客户或公开来源的表写一个 DataFrameModel
- 给数据管道中第一个加载数据的函数挂上 check_types，故意喂一行坏数据，看看报错信息
- 把一条真实的 Pandera 报错改写成给客户的问题，写明列名、规则和出错的值

## 信源

- [Pandera documentation](https://pandera.readthedocs.io/en/stable/)

- [unionai-oss/pandera: A light-weight, flexible, and expressive statistical data testing library](https://github.com/unionai-oss/pandera)

- [DataFrame Models - Pandera documentation](https://pandera.readthedocs.io/en/stable/dataframe_models.html)

- [pandera · PyPI](https://pypi.org/project/pandera/)
