Data Validation

核心用法

本技能提供全面的模式驱动数据验证方案，覆盖主流语言和场景：

• JSON Schema：语言无关的验证标准，支持对象结构、类型约束、条件逻辑、模式匹配等复杂规则，可通过 ajv-cli、jsonschema 等工具命令行验证
• Zod (TypeScript)：运行时类型安全库，支持从 schema 推断 TypeScript 类型，提供 .safeParse() 安全解析、.parse() 抛错解析、变换（transform）、精炼（refine）、判别联合（discriminated union）等高级模式，原生适配 Express/Fastify 等框架
• Pydantic (Python)：基于类型注解的数据验证，支持字段校验器（@field_validator）、模型校验器（@model_validator）、计算字段（@computed_field）、严格模式、别名映射，与 FastAPI 深度集成自动生成文档
• 数据完整性检查：bash 脚本校验 CSV 行列一致性、空值、重复；jq 验证 JSON 结构、必填字段、唯一性；Python 脚本对比迁移前后数据完整性

显著优点

1. 跨语言统一：JSON Schema 作为通用契约，Zod/Pydantic 双向生成 Schema，实现前后端、多语言服务间类型对齐
2. 开发体验极佳：Zod 的类型推断消除重复定义；Pydantic 的 EmailStr、HttpUrl 等即开即用；两者错误信息结构化、可本地化
3. 生产级集成：FastAPI/Express 中间件直接消费 schema，API 文档自动生成；CLI 工具链支持 CI/CD 流水线数据质检
4. 防御性设计：边界验证策略（"信任内部数据"）、严格模式拒绝隐式类型转换、additionalProperties: false 捕获拼写错误

潜在缺点与局限

• JSON Schema 学习曲线：复杂条件（if/then/else）、递归 $ref 对新手不友好，调试困难
• Zod 运行时开销：大型 schema 或高频验证场景需考虑性能，复杂变换链增加延迟
• Pydantic v1/v2 迁移成本：v2 性能提升但 API 变动大，旧项目升级需改造
• CSV 验证简陋：bash/jq 方案仅覆盖基础质检，无原生 schema 支持，复杂业务规则需自定义脚本
• 生态锁定：深度使用 Zod/Pydantic 特有功能后，迁移至其他语言/库需重写验证逻辑

适合人群

• 全栈开发者：需要前后端共享类型定义，追求端到端类型安全
• API 设计师：构建 REST/GraphQL 服务，需自动生成 OpenAPI 文档
• 数据工程师：ETL 管道、数据迁移、CSV/JSON 导入前的质量门禁
• 微服务团队：服务间数据契约治理，多语言技术栈下的 schema 同步

常规风险

| 风险 | 说明 | 缓解措施 |

|------|------|---------|

| 验证绕过 | 生产环境关闭验证或内部数据未校验 | 边界强制验证，内部信任但审计 |

| ReDoS 攻击 | JSON Schema `pattern` 使用贪婪正则 | 限制输入长度，审计正则复杂度 |

| 敏感数据泄露 | 错误信息暴露字段值或系统路径 | 定制错误响应，生产环境脱敏 |

| 类型强制风险 | Pydantic 默认 coercion 导致 `"42"` → `42` | 关键路径启用 `strict=True` |

| 性能退化 | 巨型 JSON 数组或深度嵌套 schema | 流式验证、分页处理、缓存 schema |

核心用法

data-validation 是一份跨语言的数据验证技术参考文档，覆盖三大主流方案：

1. JSON Schema — 语言无关的声明式验证标准，适合 API 契约、配置校验与跨团队协作。支持条件验证（if/then）、模式属性（patternProperties）、可复用定义（$defs/$ref）等高级特性。

2. Zod（TypeScript） — 运行时类型安全与静态类型推导的双重保障。核心特性包括：.safeParse() 返回结构化错误、.infer<> 从 schema 提取 TypeScript 类型、.coerce 类型转换、discriminated union 标签联合、以及 .refine() 自定义校验逻辑。特别适用于 Express/Fastify 等 Node.js 框架的请求验证中间件。

3. Pydantic（Python） — 数据类与验证的深度整合。v2 版本性能大幅提升，支持 @field_validator/@model_validator 多级校验、EmailStr/HttpUrl 语义类型、ConfigDict(strict=True) 禁用隐式转换、以及 FastAPI 原生集成自动生成 OpenAPI 文档。

文档同时提供 CLI 验证脚本（ajv-cli、jsonschema、jq）与数据完整性检查方案（CSV 行列一致性、JSON 结构校验、ETL 迁移比对）。

显著优点

• 多语言覆盖：一份文档同时服务 TypeScript 与 Python 技术栈，降低团队选型成本
• 类型安全闭环：Zod/Pydantic 均支持 schema → 类型 → 运行时验证的端到端一致性
• 生产级示例：含 FastAPI/Express 中间件、Query 参数校验、错误处理等可直接落地的代码
• 迁移与数据质量：专门的 ETL 校验脚本与 CSV/JSON 质量检查工具链

潜在局限

• 语言局限：未覆盖 Rust（serde）、Go（validator）、Java（Jakarta Validation）等后端语言
• 性能未量化：仅提及 Pydantic v2"更快"，无具体基准数据
• 错误定制深度：Zod/Pydantic 的错误消息国际化与字段级定制示例较少
• 无测试示例：缺乏验证失败场景的单元测试写法演示

适合人群

• 全栈开发者构建类型安全的 REST/GraphQL API
• 数据工程师设计 ETL 数据契约与质量门禁
• 架构师制定跨服务数据交换标准
• 技术负责人评估验证方案选型

常规风险

• 过度验证陷阱：边界层验证后仍可能在业务层重复校验，影响性能；文档已提示"信任内部数据"
• 模式漂移：JSON Schema 与代码 schema 分离时易产生版本不一致，建议利用 Zod/Pydantic 的 JSON Schema 导出能力保持同步
• 严格模式误用：additionalProperties: false 或 strict=True 可能破坏向前兼容性，API 升级时需谨慎