适用场景：什么时候需要做数据脱敏

在开发与运维过程中，业务文本常包含手机号、身份证号、银行卡号、邮箱和中文姓名等个人敏感信息。这些信息一旦完整出现在日志、工单、测试数据或第三方分析报告中，就会带来数据合规风险。典型场景包括：

• 开发调试日志：后端框架打印请求参数时，如果直接输出完整手机号或身份证，日志文件会变成敏感信息泄露的载体。
• 测试环境数据：从生产库导出的数据如果原样进入测试环境，测试人员可能接触到真实个人信息。
• 客服与工单系统：客服界面展示用户联系方式时，只显示掩码后的结果，降低内部人员获取完整信息的可能性。
• 数据导出与共享：将业务数据交给外部团队分析前，先对文本中的 PII（个人身份信息）做掩码处理，避免直接暴露用户身份。

这类需求通常不需要复杂的机器学习模型，通过正则匹配即可覆盖大部分常见格式。本文介绍的数据脱敏接口就是围绕这个需求设计的。

接口能力边界：能做什么、不能做什么

在接入前，需要明确接口的能力范围，避免产生不切实际的预期。

支持识别的类型

该接口可以自动检测并脱敏以下类型的敏感信息：

• 手机号（常见国内 11 位手机号）
• 身份证（15 位或 18 位）
• 银行卡（16-19 位）
• 邮箱地址
• 中文姓名

默认情况下，接口会尝试识别上述全部类型；也可以使用types参数按需指定，例如只处理手机号和姓名。

关键限制

• 纯本地正则匹配：接口不依赖外部数据源，毫秒级返回。这意味着对格式规范、无特殊符号的文本识别效果好，但对格式变体（如手机号中间带空格、身份证号前后带中文说明）可能需要预处理。
• 中文姓名依赖常见姓氏库：对常见姓氏如“张、李、王”等识别稳定，但生僻姓氏或少数民族姓名可能无法命中。
• 文本长度上限：text字段最长 50000 字节，超出后需要分片处理。
• QPS 限制：接口 QPS 为 10/s，适合中低并发场景，不适合作为高吞吐数据管线的核心组件。

请求参数与鉴权

接口基本信息

每个请求都需要在 HTTP 头中携带X-API-Key，对应的 API Key 通过环境变量$APIZERO_API_KEY传入，避免在代码中硬编码。

请求体字段

请求体是一个 JSON 对象，字段说明如下：

示例：如果只想处理手机号和姓名，可以设置types为"phone,name"。

curl 接入示例

下面给出两个可直接替换参数执行的 curl 示例。请提前在环境变量中设置APIZERO_API_KEY：

export APIZERO_API_KEY="your_api_key_here"

示例一：使用默认类型脱敏文本

curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "联系人：张三，电话 13812348000，身份证 110101199003071234，邮箱 zhangsan@example.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": "成功" }

字段含义如下：

当with_original为true时，detections中的每个对象还会额外包含原文回显字段，具体字段名以实际响应为准。线上环境建议保持with_original为默认值false，避免原文从响应中泄漏。

常见错误与排查

接入过程中可能遇到以下几类问题：

• HTTP 401 / 403：X-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