适用场景什么时候需要做数据脱敏在开发与运维过程中业务文本常包含手机号、身份证号、银行卡号、邮箱和中文姓名等个人敏感信息。这些信息一旦完整出现在日志、工单、测试数据或第三方分析报告中就会带来数据合规风险。典型场景包括开发调试日志后端框架打印请求参数时如果直接输出完整手机号或身份证日志文件会变成敏感信息泄露的载体。测试环境数据从生产库导出的数据如果原样进入测试环境测试人员可能接触到真实个人信息。客服与工单系统客服界面展示用户联系方式时只显示掩码后的结果降低内部人员获取完整信息的可能性。数据导出与共享将业务数据交给外部团队分析前先对文本中的 PII个人身份信息做掩码处理避免直接暴露用户身份。这类需求通常不需要复杂的机器学习模型通过正则匹配即可覆盖大部分常见格式。本文介绍的数据脱敏接口就是围绕这个需求设计的。接口能力边界能做什么、不能做什么在接入前需要明确接口的能力范围避免产生不切实际的预期。支持识别的类型该接口可以自动检测并脱敏以下类型的敏感信息手机号常见国内 11 位手机号身份证15 位或 18 位银行卡16-19 位邮箱地址中文姓名默认情况下接口会尝试识别上述全部类型也可以使用types参数按需指定例如只处理手机号和姓名。关键限制纯本地正则匹配接口不依赖外部数据源毫秒级返回。这意味着对格式规范、无特殊符号的文本识别效果好但对格式变体如手机号中间带空格、身份证号前后带中文说明可能需要预处理。中文姓名依赖常见姓氏库对常见姓氏如“张、李、王”等识别稳定但生僻姓氏或少数民族姓名可能无法命中。文本长度上限text字段最长 50000 字节超出后需要分片处理。QPS 限制接口 QPS 为 10/s适合中低并发场景不适合作为高吞吐数据管线的核心组件。请求参数与鉴权接口基本信息项目说明请求方法POST请求地址https://v1.apizero.cn/api/desensitizeContent-Typeapplication/json鉴权方式请求头X-API-Key每个请求都需要在 HTTP 头中携带X-API-Key对应的 API Key 通过环境变量$APIZERO_API_KEY传入避免在代码中硬编码。请求体字段请求体是一个 JSON 对象字段说明如下字段类型必填说明textstring是要脱敏的文本最长 50000 字节typesstring否类型逗号分隔phone、idcard、bankcard、email、name或all默认with_originalboolean否是否在detections中回显原文默认false示例如果只想处理手机号和姓名可以设置types为phone,name。curl 接入示例下面给出两个可直接替换参数执行的 curl 示例。请提前在环境变量中设置APIZERO_API_KEYexport APIZERO_API_KEYyour_api_key_here示例一使用默认类型脱敏文本curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { text: 联系人张三电话 13812348000身份证 110101199003071234邮箱 zhangsanexample.com, types: all } \ https://v1.apizero.cn/api/desensitize此请求会脱敏文本中所有可识别的敏感信息。示例中的姓名、手机号、身份证号均为虚构数据。示例二指定类型并开启原文回显curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { text: 张三 13812348000 110101199003071234, types: phone,name, with_original: true } \ https://v1.apizero.cn/api/desensitize这里只处理手机号和姓名身份证号不会被脱敏。with_original设为true后响应中的detections数组会携带原文方便调试时确认匹配结果。返回值解读成功响应示例如下{ code: 0, data: { detection_count: 2, detections: [ { masked: 张*, type: name }, { masked: 138****8000, type: phone } ], masked_text: 联系人张*电话 138****8000, summary: { name: 1, phone: 1 }, types_applied: [phone, idcard, bankcard, email, name] }, msg: 成功 }字段含义如下字段类型说明codenumber业务状态码0表示成功msgstring状态描述data.detection_countnumber识别出的敏感信息数量data.detectionsarray每次匹配的脱敏结果包含masked脱敏后的文本和type敏感类型data.masked_textstring原始文本中被脱敏后的完整文本data.summaryobject每种敏感类型的命中数量如{phone: 1}data.types_appliedarray本次请求实际应用的类型列表当with_original为true时detections中的每个对象还会额外包含原文回显字段具体字段名以实际响应为准。线上环境建议保持with_original为默认值false避免原文从响应中泄漏。常见错误与排查接入过程中可能遇到以下几类问题HTTP 401 / 403X-API-Key缺失、无效或已过期。先确认环境变量是否正确传入再检查 Key 是否被正确复制。HTTP 400请求体不是合法 JSON或者缺少必填字段text。用jq或在线校验工具确认请求体格式注意在 shell 中嵌套引号时使用单引号包裹整个 JSON。code非 0响应中返回了业务错误码和msg描述例如types传入了不支持的枚举值。请参照msg修正参数具体错误码含义以官方文档为准。脱敏结果与预期不符检查原文中是否包含空格、全角符号或换行。比如138 1234 8000这类写法可能会被拆成多段导致识别失败。可考虑先对文本做标准化预处理。并发被限流接口 QPS 为 10/s若短时间发起大量请求可能收到限流响应。建议在调用侧增加本地队列或重试机制控制实际请求速率。工程化注意事项将数据脱敏接口集成到业务系统时除了基本的请求/响应处理还需要关注以下工程化细节1. 在日志链路最前端做脱敏不要等到日志写出后再尝试删除敏感信息。最佳实践是在请求入口或日志切面中先调用脱敏接口再用脱敏后的文本去记录日志。这样能避免敏感信息在日志缓冲区中短暂停留。2. 分离调试模式与生产模式开发阶段可以开启with_original检查匹配结果但上线前必须关闭。可以借助配置中心或环境变量控制该参数避免在正式环境意外回显原文。3. 超长文本的分片策略text字段有 50000 字节上限。对更长的文本需要分片处理。分片时不要从中间硬切否则可能把一个手机号或身份证号切成两段导致无法识别。建议按段落或换行符切分并保留一定重叠区域。4. 缓存与幂等同一段文本重复调用接口返回结果通常是确定的。对于日志脱敏这类高频场景可以考虑在内存中缓存文本到脱敏结果的映射降低 QPS 消耗。注意缓存需要设置有效期避免内存膨胀。5. 不要依赖脱敏做加密脱敏是“有损模糊化”主要用于降低展示和日志中的敏感信息暴露风险不等于加密存储。对于需要保密的字段仍应使用加密算法存储访问时再解密。6. 监控与告警跟踪接口调用成功率、耗时、返回非零code的频率。如果出现大面积识别失败可能是原文格式变化或接口策略调整需要及时更新预处理规则。总结数据脱敏接口提供了一种简单、快速的敏感信息掩码能力适用于日志清洗、测试数据准备和业务展示等场景。接入时重点关注鉴权方式、types参数组合、with_original的安全使用以及超长文本分片策略。整体而言该接口适合作为业务系统中的一个轻量级脱敏组件但不应替代完整的隐私保护体系。参考文档接口文档https://apizero.cn/aidocs/desensitize原始文档https://apizero.cn/aidocs/desensitize/raw.md