1. 适用场景数据脱敏接口适用于所有需要隐藏敏感信息的场景例如日志清洗在写入日志前将手机号、身份证号、银行卡号、邮箱、姓名等替换为掩码形式避免泄漏用户隐私。数据展示前端页面或API返回中对敏感字段进行脱敏后再展示给低权限角色。测试数据将生产数据脱敏后用于开发或测试环境。合规审计满足《个人信息保护法》等法规中对敏感信息处理的要求。该接口采用纯本地正则匹配毫秒级返回无网络依赖除API调用本身适合高并发离线或准实时处理。2. 接口能力边界支持脱敏类型手机号phone、身份证15/18位idcard、银行卡16-19位bankcard、邮箱email、中文姓名name。可组合传入默认全部处理。输入限制每条文本最长 50000 字节约 50000 个英文字符或 16666 个中文字符超长会拒绝。输出选项可选择是否在detections数组中回显原文with_original默认 false避免日志泄漏。QPS10次/秒超限会返回限流错误。幂等性多次请求相同输入返回结果一致纯正则匹配无状态。3. 鉴权与请求参数3.1 鉴权方式使用 X-API-Key 头部传递 API 密钥例如X-API-Key: your_api_key_here密钥需在控制台申请任何请求都必须携带否则返回 401 错误。3.2 请求参数字段类型必填说明textstring是要脱敏的文本最长 50000 字节typesstring否逗号分隔的类型phone,idcard,bankcard,email,name或all默认with_originalboolean否是否在 detections 中回显原文默认为 false3.3 请求示例JSON Body{ text: 联系张三电话13812348000身份证110101199001011234卡号6222021234567890邮箱zhangsanexample.com, types: phone,idcard,name, with_original: false }4. 快速接入curl 示例以下 curl 命令可复制至终端直接运行需替换$APIZERO_API_KEY为真实密钥curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { text: 联系张三电话13800000000, types: phone,name, with_original: false } \ https://v1.apizero.cn/api/desensitize若需调试可先使用-v选项查看完整请求与响应头。5. 返回值深度解读响应 JSON 结构如下{ code: 0, msg: 成功, data: { masked_text: 联系张*电话138****0000, detection_count: 2, detections: [ { type: name, masked: 张*, original: 张三 // 仅当 with_originaltrue 时出现 }, { type: phone, masked: 138****0000 } ], summary: { name: 1, phone: 1 }, types_applied: [phone, name] } }code0 表示成功非零表示错误具体错误码参见文档。data.masked_text整个文本脱敏后的结果。data.detections每个检测到的敏感信息及脱敏结果。data.summary按类型统计的脱敏数量。data.types_applied实际应用的脱敏类型列表。注意detections中不包含原文除非with_originaltrue避免意外的信息泄漏。6. 常见错误与排错清单6.1 错误一鉴权失败HTTP 401现象返回 HTTP 状态码 401响应体类似{code: 401, msg: Unauthorized}。原因未携带X-API-Key请求头。携带的 API Key 无效或已过期。请求头名称拼写错误如x-api-key大小写不符。排错步骤确认 curl 命令中包含-H X-API-Key: your_key。检查控制台该 Key 是否有效必要时重新生成。使用-v模式输出请求头确认发送了正确的头部。6.2 错误二请求体格式错误HTTP 400现象返回 HTTP 400提示“Invalid JSON body”或“Unsupported Media Type”。原因Content-Type不是application/json。JSON 格式错误例如多余逗号、单引号代替双引号。text字段缺失。排错步骤确保Content-Type: application/json头已设置。使用 JSON 校验工具如jq .验证请求体。检查text字段是否存在。6.3 错误三文本超长HTTP 413 或业务错误码现象可能返回 HTTP 413 Payload Too Large或业务层错误码如code: 1001提示文本超长。原因text字节数超过 50000。排错步骤在发送前计算文本字节数中文占3字节英文1字节。例如echo -n 你的文本 | wc -c。若超长可拆分为多条请求每条控制在 50000 字节内。注意types和with_original不占空间。6.4 错误四类型参数不合法现象types字符串包含未知类型如phone,wechat接口可能返回错误。原因只支持phone,idcard,bankcard,email,name或all。排错步骤检查types列表中的值是否全部在支持范围内。使用逗号分隔不要有空格phone,idcard正确phone, idcard可能失败。若不确定可省略types字段默认all。6.5 错误五返回数据中 detections 为空现象detection_count为 0detections为空数组但masked_text与原文本相同。原因文本中没有匹配到对应类型的敏感信息如手机号格式错误。types指定了不包含实际存在的类型例如文本只有手机号但typesemail。排错步骤确认文本中确实包含该类型的敏感数据如手机号必须是 11 位数字身份证号符合校验规则。尝试使用all类型重新请求。检查敏感数据格式是否标准如带空格或短线需要先预处理。6.6 错误六响应体中code ! 0现象code为其他值例如1002表示内部处理错误。原因服务器端正则匹配异常极少见或传入非字符串类型。排错步骤检查msg字段获取具体错误描述。确认text的编码为 UTF-8不含非法字符。重试请求若持续失败可查看 API 文档中的错误码列表。7. 工程化注意事项7.1 密钥管理将 API Key 存储在环境变量或密钥管理服务中不要硬编码到代码仓库。定期轮换密钥并更新所有调用方。7.2 超时与重试设置合理 HTTP 超时时间如 5 秒避免长时间等待。对网络错误如 502、连接超时实现指数退避重试最大重试 3 次。对业务错误如 400、401不必重试。7.3 批量文本处理由于 QPS 限制为 10如果需处理大量文本建议控制并发数并在请求间加入小间隔如 100ms。可使用异步队列如 Celery逐步消费避免瞬间流量打满。7.4 日志脱敏在业务日志中打印脱敏后的masked_text不要记录原文。如调试需要检测结果可启用with_originaltrue但务必在测试环境使用生产环境默认关闭。7.5 输入预处理建议在调用前对文本进行基础清洗去除多余空格、统一格式如去掉手机号中的连字符-以提高匹配准确率。8. 参考文档官方文档https://apizero.cn/aidocs/desensitize原始文档Markdownhttps://apizero.cn/aidocs/desensitize/raw.md注文档中会包含完整的错误码表、更新日志及更多示例。