API接口数据清洗核心是前置拦截与标准化，需在入口层通过可配置、可验证的规则实现字段校验、格式归一、安全过滤，并记录清洗过程以保障准确性、稳定性与可观测性。
API接口开发中做数据清洗，核心是“在数据进入业务逻辑前拦截并标准化”，不是等出问题再补救。重点在于把清洗逻辑前置到请求入口，用可复用、可配置、可验证的方式处理脏数据。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
一、定义清洗规则：先搞清楚要洗什么
不同接口的数据脏点差异很大。比如用户注册接口常见空字符串、手机号带空格、邮箱大小写混用；而订单查询接口可能面临时间格式混乱（"2024-01-01" vs "01/01/2024"）、金额带单位（"¥199.00"）、ID传了字符串却要求整型。清洗前必须明确：
• 哪些字段必填、哪些可选
• 每个字段的类型、长度、格式约束（正则、枚举、范围）
• 是否需要标准化（如统一转小写、去前后空格、补零、格式归一）
• 错误如何反馈（直接拒绝？自动修正？记录日志？）
二、在API入口层嵌入清洗逻辑
推荐在框架中间件或请求解析阶段完成，避免业务代码里到处写trim()和parseInt()。以常见场景为例：
• 请求体（JSON）：用校验库（如Zod、Joi、Pydantic）声明schema，自动做类型转换+基础清洗（如字符串trim、数字转number、日期转ISO格式）
• 查询参数（Query）：统一解码URL编码，对id、page、size等做类型强转和范围限制
• 表单数据（Form）：过滤HTML标签、移除不可见字符（\u200b、\ufeff等），防止XSS或存储异常
• 文件上传元信息：校验文件名是否含非法字符，大小是否超限，MIME类型是否匹配
三、设计可配置的清洗策略
硬编码清洗逻辑难维护。建议把规则抽成配置项：
• 字段级开关：如"mobile: { trim: true, normalize: 'e164' }"
• 清洗链式调用：先trim → 再正则替换 → 最后格式校验
• 环境差异化：测试环境允许宽松清洗（如自动补全http://），生产环境严格拒绝
• 支持绕过：给内部调试接口加?debug=clean_skip参数临时跳过清洗，方便排查
四、记录与反馈：让清洗过程可追踪
清洗不是黑盒操作。每次请求应记录：
• 原始输入（脱敏后，如手机号显示为138****1234）
• 清洗后结果
• 执行了哪些规则（如"applied: trim, toLowerCase, emailDomainNormalize"）
• 是否发生强制修正（warn级别）或拦截（error级别）
前端调用时，返回结构中可包含cleaned字段（如{"email": "user@domain.com", "cleaned": ["trim", "toLowerCase"]}），便于客户端感知变化；严重清洗失败则返回400 + 明确提示（如"phone格式错误：请提供11位纯数字"）
基本上就这些。数据清洗不是越狠越好，关键是“准”——准确定义规则，“稳”——稳定嵌入流程，“明”——清晰暴露过程。不复杂但容易忽略。
