数据验证Skill：把输入校验、清理编码与数据质量一次做到位
- 全链路覆盖：从 JSON Schema、Zod、Pydantic、Joi、Yup、Ajv、class-validator 等模式验证库，到输入清理、输出编码、类型强制，再到 API 请求/响应校验、数据管道质量检查、ML 特征验证，一套技能串起"数据可信"的完整链路。
- 写校验代码时自动加载：当你提出"做表单验证"“防 XSS”“写 Zod 模式”"做数据质量检查"等需求时，该技能会按对应主题提供参考实现与最佳实践，而不是给一段泛泛的示例。
- 强调安全与错误体验：内置白名单优先、上下文感知输出编码、参数化查询替代 SQL 转义、可操作的中文错误消息等规范，让校验不仅"挡得住"，还"说得清"。
- 角色化分工：技能内部按任务类型分配不同的代理职责（模式架构、验证逻辑实现、安全清理策略、管道与数据质量检查），复杂需求也能拆解推进。
- 适用面广：后端接口、前端表单、富文本、文件上传、数据仓库/ETL、机器学习特征管道、基础设施配置校验都可复用同一套思路。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
- 中文名：数据验证Skill
- 英文名：data-validation
- 技能 ID：13516
- 技能定位：面向"数据在进入系统之前是否可信"这一核心问题，提供模式验证、输入清理、输出编码、类型强制与安全防护的完整方法论与参考代码。
它解决什么问题
绝大多数线上事故，都能追溯到"系统相信了不该相信的输入"。表单里少一个字段、接口里多一个属性、CSV 里混进一列脏数据、模型推理时特征分布悄悄漂移一位——这些问题的共性在于：校验要么缺失，要么零散，要么写得太晚。数据验证Skill 的价值就是把"尽早验证、在边界验证、按上下文清理与编码"变成可复用的工程习惯：
- 边界不清：不清楚应该在控制器、服务层还是数据库层做校验；
- 写法不统一：一个项目里同时出现三种校验风格，错误返回格式各不相同；
- 安全意识弱：只知道"转义一下"，不知道不同输出上下文需要不同编码方式；
- 数据侧空白：代码校验做得不错，但数据管道的空值率、分布漂移没人管。
"一键安装"的思路与步骤
该技能属于 AI 技能（Skill）形态，通常依附于支持 Skill 机制的 AI 编程助手或客户端使用。通用安装思路如下（具体命令、入口与是否收费以官方说明为准）：
- 确认前提：你的 AI 客户端/插件需要支持自定义技能或技能市场；准备可用的账号与项目工作目录。
- 找到技能入口：在客户端的技能市场、技能管理页或插件配置中搜索技能名称"数据验证"或英文名
data-validation，也可按技能 ID 13516 检索。 - 一键添加/导入：按界面提示完成添加，通常是一次点击即可完成挂载；若以文件形式分发，则按官方文档指引导入技能包。
- 确认生效：新建一个会话，提出一个明显的验证类需求，例如"帮我用 Zod 写一个用户注册接口的校验，并返回中文字段级错误"。若回答中出现模式定义、错误格式化函数、边界与安全建议等结构化内容，说明技能已被正确加载。
- 纳入日常流程：把"写校验"这一动作固定交给技能处理，例如在提交接口代码前先让它生成模式与清理函数，再人工评审。
提示：不同客户端对技能的触发方式不同，有的靠关键词自动匹配（如"表单验证"“XSS”“JSON Schema”“数据漂移”），有的需要手动在对话中引用技能名。具体以你所使用产品的官方说明为准。
2. 该技能的主要功能和特点
- 多库模式验证：覆盖 JSON Schema（Ajv）、Zod、Pydantic、Joi、Yup、class-validator 等主流方案，能按你的技术栈给出对应写法，而不是硬塞一种库。
- 输入清理（Sanitization）：提供 HTML 清理（DOMPurify 白名单标签/属性）、文件名清理、路径遍历防护、通用字符串清理预设（用户名、邮箱、手机号、slug、搜索词）。
- 输出编码（Encoding）：按上下文区分 HTML、HTML 属性、JavaScript 字符串、URL、CSS 五种编码场景，避免"一律 HTML 转义"造成的漏防或过度转义。
- 类型强制与默认值：支持类型强转、默认值填充、移除未声明属性的"严格模式"，让"多余字段"无法悄悄进入业务逻辑。
- 安全重点防护：XSS 预防、注入预防、白名单优先、参数化查询优先于手工 SQL 转义，明确"黑名单不可靠"的原则。
- API 请求与响应双向校验：既校验入参（body/query/params），也校验出参结构，防止内部数据结构变更泄漏到外部契约。
- 数据管道验证：包含 Great Expectations 期望套件与 dbt 测试（唯一、非空、取值范围、枚举、时效性）的落地写法。
- ML 特征验证：模式一致性、分布漂移（z 分数）、方差变化比、空值率阈值、意外类别检测，并可基于训练数据设定基线。
- 基础设施配置校验：Kubernetes 清单、Terraform 配置的结构校验与自定义业务规则（如必填标签）检查。
- 工程化最佳实践：早验证、失败快、错误消息具体可操作、生产环境不暴露内部细节、纵深防御（客户端 + 服务端 + 多层校验）。
和普通工具比强在哪：单一校验库只解决"怎么校验一个对象"，而本技能解决的是"在哪校验、校验什么、失败怎么反馈、脏数据怎么清理、输出怎么编码、数据侧怎么监控"这一整套问题，并且能跨语言、跨层给出相互一致的方案。
3. 如何使用该技能？
步骤一：明确数据结构与约束
先用自然语言把字段、类型、必填性、取值范围、枚举值、跨字段关系讲清楚。描述越具体，产出越可直接使用。
步骤二：说明技术栈与库偏好
告诉技能你用的是 TypeScript + Zod、Python + Pydantic、还是语言无关的 JSON Schema；若已有既定规范（如错误统一返回 422 + 字段级错误数组），一并说明。
步骤三：提出校验需求
输入示例：
帮我用 Zod 为注册接口写一套校验：邮箱必填、最长 255 并自动转小写去空格；密码 12–128 位，必须含大小写字母、数字和特殊字符；昵称 1–100 字符并去除首尾空格；年龄 13–150 可选整数；角色只能是 user/admin/moderator，默认 user；需要确认密码且两次一致，最终输出中移除确认密码字段；错误消息全部用中文。
步骤四：接收并理解输出
典型输出会包含：
- 模式定义（含
transform转换、refine跨字段校验、default默认值）； - 从模式推断出的输入/输出类型，避免重复声明接口；
- 统一的验证助手函数，返回
{ success, data }或{ success, errors: [{ field, message }] }； - 中间件/装饰器示例，把校验挂到路由或控制器入口；
- 安全提示，例如密码不应出现在日志中、错误消息不要回显用户原始输入。
步骤五：追加清理与编码要求
继续追问："这个昵称字段会渲染到评论区，输出时应该怎么处理？"技能会按 HTML 上下文给出编码方案；如果是富文本，则给出白名单标签与属性清单。
步骤六：扩展到数据侧
接口层完成后，可继续要求："为这张用户表写 dbt 测试和 Great Expectations 期望，包含邮箱唯一、年龄区间、状态枚举、created_at 近 7 天内有更新。"技能会给出对应的 YAML 与 Python 期望套件。
步骤七：验证效果
把生成的校验代码跑一遍正例与反例（缺字段、超长、类型错、非法枚举、多余属性），确认错误消息清晰、状态码正确、日志不泄漏敏感信息。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 数据验证Skill（data-validation） | 校验与数据质量的"方法论 + 参考实现"技能 | 模式验证、输入清理、输出编码、类型强制、API 双向校验、数据管道与 ML 特征验证 | 需支持 Skill 的 AI 客户端，一键添加；具体入口与费用以官方说明为准 | 需要成体系落地校验规范的团队、跨语言多项目 | 优势：覆盖面广、跨语言、强调安全与错误体验；不足：产出仍需人工评审与测试覆盖，不能替代安全审计 |
| 单一校验库（如 Zod / Pydantic / Joi） | 具体的运行时校验库 | 模式定义、类型推断、基础错误信息 | 通过包管理器安装，学习成本中等 | 单语言单体项目的对象校验 | 优势：成熟稳定、生态完善；不足：只管"对象校验"这一层，清理、编码、数据质量需另行解决 |
| 通用 AI 编程助手（未加载技能） | 通用代码生成 | 可写任意代码，包含校验 | 零配置 | 临时性、简单校验需求 | 优势：随时可用；不足：校验风格不稳定，安全细节容易遗漏，缺少统一的错误规范与数据侧方案 |
| 静态安全扫描工具（SAST 类） | 事后发现安全问题 | 代码规则扫描、漏洞告警 | 需接入 CI、配置规则集 | 上线前安全把关 | 优势：能发现已知模式的风险；不足：事后发现、修复成本高，无法替代"在边界做校验"的设计 |
从对比可以看出，本技能与具体校验库是"设计与实现"的关系，与通用 AI 助手是"专精与通用"的关系，与安全扫描工具是"事前预防与事后检查"的关系，三者互补而非互斥。
5. 该技能的典型应用场景与实际体验情况
场景一：后端工程师开发用户注册/登录接口
- 角色与痛点：后端工程师要在有限时间内交付接口，校验往往"能跑就行"，导致错误返回格式五花八门，前端难以统一处理。
- 使用方式：描述字段约束后，让技能生成模式、统一错误助手与路由中间件三件套，并按"生产环境不暴露内部细节"的原则调整错误消息。
- 实际体验：上手难度低，只要能把业务规则说清楚，基本一次就能得到可用代码；效果上，字段级中文错误显著减少了前后端联调扯皮。注意事项：跨字段规则（如两次密码一致）和异步唯一性校验要单独确认，避免把同步校验写成阻塞调用。
场景二：前端处理用户富文本与昵称展示
- 角色与痛点：前端同学对 XSS 的理解常停留在"转义一下"，富文本编辑器回显时又不敢转义，容易两头出错。
- 使用方式：让技能按"输入清理 + 输出编码"两段式给出方案——入库前用白名单标签清理，渲染时按 HTML 上下文编码，属性与 URL 分别处理。
- 实际体验：方案结构清晰，能直接对照落地；对"哪些标签该放行"这类业务决策，技能会给建议但不会替你拍板，需要产品与安全同学共同确认。注意事项：不要在客户端做唯一防线，服务端必须重复校验。
场景三：数据工程师搭建数仓质量监控
- 角色与痛点：代码层的校验做完了，但数据表里的空值、重复、异常分布没人盯，问题往往在下游报表出错时才暴露。
- 使用方式：要求生成 dbt 测试与 Great Expectations 期望套件，覆盖唯一性、非空、枚举、区间与时效性。
- 实际体验：示例可直接改成项目里的
schema.yml，改动量小；建议先从核心表的关键字段入手，避免一次性铺开导致告警疲劳。注意事项：阈值（如空值率 5%）需结合业务实际设定，不要照搬示例。
场景四：算法工程师维护特征管道
- 角色与痛点：训练时特征正常，上线后因为上游字段类型变化或分布漂移，模型效果悄悄下降。
- 使用方式：让技能给出特征校验器骨架——模式一致性检查、基于训练数据基线设定的分布漂移检测（z 分数阈值）、方差变化比、意外类别检测。
- 实际体验：思路完整、代码可运行，属于"低成本换来高确定性"的投入；注意事项：基线需随模型版本同步更新，否则会持续误报。
6. 该技能能为用户带来的价值
- 效率提升：把"查文档 + 试错 + 对齐风格"的过程压缩成一次对话，接口校验从半天缩短到十几分钟量级（具体取决于字段复杂度）。
- 门槛降低：不熟悉 DOMPurify 白名单配置、不清楚路径遍历怎么防、没写过 dbt 测试的开发者，也能拿到可直接改造的正确范式。
- 质量一致性：统一错误结构、统一命名与返回格式，让多个开发者产出的校验代码像一个团队写的。
- 风险前置：把安全与数据质量问题的发现点从"上线后"提前到"写代码时"，修复成本相差一个数量级。
- 长期价值：技能沉淀的是可复用的工程规范——边界校验、白名单优先、上下文编码、分布监控，这些习惯会持续产生收益，而不只是一次性的代码片段。
7. 常见问题 FAQ
Q1：怎么安装这个技能？需要什么前提？
A：需要在支持 Skill 机制的 AI 客户端中使用，通常可在技能市场或技能管理页搜索"数据验证"或英文名 data-validation（技能 ID 13516）后一键添加。安装入口、命令与是否支持离线导入，以你所使用产品的官方说明为准。安装后用一个验证类问题测试即可确认是否生效。
Q2：这个技能收费吗？
A：技能本身的费用与获取方式由分发平台决定，请以官方说明为准。通常成本来自你所使用的 AI 客户端订阅或调用额度，而非技能单独计费。
Q3：它适合谁用？前端、后端还是数据团队？
A：三类人都适合。后端用它做接口入参/出参校验与安全清理；前端用它做表单校验、富文本清理与上下文编码；数据与算法团队用它做数据质量期望、dbt 测试与特征漂移检测。基础设施工程师也能用它校验 Kubernetes 与 Terraform 配置。
Q4：它和直接装一个 Zod 或 Pydantic 有什么区别？
A：库解决"怎么校验一个对象"，技能解决"在哪校验、校验什么、失败怎么反馈、脏数据怎么清理、输出怎么编码、数据侧怎么监控"。两者是配合关系：技能给你设计方案和代码骨架，库提供运行时能力。
Q5：用了它是不是就不用写测试和安全审计了？
A：不能。技能产出的是校验实现与规范建议，仍需正例/反例测试覆盖，仍需安全扫描与人工评审。它的价值在于减少遗漏、统一风格、把问题前置，而不是替代完整的质量体系。