数据体检·CSV/Excel 入库前脏数据校验

数据校验 / 表结构校验 / 数据质量检查（别称：数据体检、脏数据检查、入库前校验）：用 pandera 按规则校验 CSV 或 Excel 表——列类型（int/float/str）、取值范围、是否可空，支持从 JSON 加载规则、输出逐行失败明细（列/检查/实际值/行号）。当用户说「校验这份数据对不对」「检查表里年龄是不是都在合理范围」「入库前验下表结构」「把脏数据行找出来」「多人表格格式对齐」时使用。适合：数据入库/分析前的质量闸门、检查某列是否越界、多人产出表格格式对齐。基于 pandera（纯 Python，pandas 后端）。⚠️ 排除范围：当前只支持 int/float/str 三型与区间检查，不含正则/唯一性/枚举校验；只报告问题不自动修复，也不直连数据库。

数据表结构校验

概述

在数据进入分析或数据库前做一道闸门：列是否齐全、类型对不对、数值是否越界。比肉眼检查快且可重复。

何时使用

数据入库 / 分析前的质量闸门
检查某列取值是否越界
多人产出表格的格式对齐

快速使用

# 方式一：命令行逐列给规则
python3 scripts/validate_schema.py 人员.csv \
  --col name:str:::False \
  --col age:int:0:120:False

# 方式二：从 JSON 文件加载规则（便于复用）
python3 scripts/validate_schema.py 人员.csv --schema rules.json

# 校验失败时，把逐行失败明细导出成 CSV 报告
python3 scripts/validate_schema.py 人员.csv --col age:int:0:120:False --report failures.csv

rules.json 格式：

[{"name":"name","dtype":"str","nullable":false},
 {"name":"age","dtype":"int","min":0,"max":120,"nullable":false}]

列规则格式：name:type:min:max:nullable（无上下限留空）

依赖安装

# 提示：脚本用相对路径 scripts/，请先 cd 到本技能目录再运行
python3 -m pip install pandera pandas

常见错误 / 注意

当前版本只支持 int/float/str 三型与区间检查，后续可加正则、唯一性、枚举
依赖 pandas，大文件注意内存；可后续接分块
校验失败会打印具体违反项，便于定位脏数据

实测验证（v0.1.0）

核心依赖：pandera
安装体积：🟢 13.7 MB（依赖闭包实测，轻量级）
环境要求：无外部二进制依赖。
单元测试：python3 -m unittest tests.test_...（须 cd 到本技能目录运行）
CLI 冒烟：已通过端到端实测

已验证行为

✅ 合规数据校验通过并回传行数
✅ 越界/空值数据被拦截，lazy 模式一次给出所有失败行（列/检查/实际值/行号）
✅ 支持 --schema JSON 加载规则、--report 导出失败明细 CSV

已知边界 / 坑

⚠️ pandera ≥0.20 推荐 from pandera.pandas import ...，顶层导入已弃用

本技能刻意用轻量用法（无 pandas 重依赖路径），实测闭包仅 13.7MB。