适用场景：什么时候需要做数据脱敏
在开发与运维过程中，业务文本常包含手机号、身份证号、银行卡号、邮箱和中文姓名等个人敏感信息。这些信息一旦完整出现在日志、工单、测试数据或第三方分析报告中，就会带来数据合规风险。典型场景包括：
- 开发调试日志：后端框架打印请求参数时，如果直接输出完整手机号或身份证，日志文件会变成敏感信息泄露的载体。
- 测试环境数据：从生产库导出的数据如果原样进入测试环境，测试人员可能接触到真实个人信息。
- 客服与工单系统：客服界面展示用户联系方式时，只显示掩码后的结果，降低内部人员获取完整信息的可能性。
- 数据导出与共享：将业务数据交给外部团队分析前，先对文本中的 PII（个人身份信息）做掩码处理，避免直接暴露用户身份。
这类需求通常不需要复杂的机器学习模型，通过正则匹配即可覆盖大部分常见格式。本文介绍的数据脱敏接口就是围绕这个需求设计的。
接口能力边界：能做什么、不能做什么
在接入前，需要明确接口的能力范围，避免产生不切实际的预期。
支持识别的类型
该接口可以自动检测并脱敏以下类型的敏感信息：
- 手机号（常见国内 11 位手机号）
- 身份证（15 位或 18 位）
- 银行卡（16-19 位）
- 邮箱地址
- 中文姓名
默认情况下，接口会尝试识别上述全部类型；也可以使用types参数按需指定，例如只处理手机号和姓名。
关键限制
- 纯本地正则匹配：接口不依赖外部数据源，毫秒级返回。这意味着对格式规范、无特殊符号的文本识别效果好，但对格式变体（如手机号中间带空格、身份证号前后带中文说明）可能需要预处理。
- 中文姓名依赖常见姓氏库：对常见姓氏如“张、李、王”等识别稳定，但生僻姓氏或少数民族姓名可能无法命中。
- 文本长度上限：
text字段最长 50000 字节，超出后需要分片处理。 - QPS 限制：接口 QPS 为 10/s，适合中低并发场景，不适合作为高吞吐数据管线的核心组件。
请求参数与鉴权
接口基本信息
| 项目 | 说明 |
|---|---|
| 请求方法 | POST |
| 请求地址 | https://v1.apizero.cn/api/desensitize |
| Content-Type | application/json |
| 鉴权方式 | 请求头X-API-Key |
每个请求都需要在 HTTP 头中携带X-API-Key，对应的 API Key 通过环境变量$APIZERO_API_KEY传入，避免在代码中硬编码。
请求体字段
请求体是一个 JSON 对象，字段说明如下：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 要脱敏的文本，最长 50000 字节 |
types | string | 否 | 类型逗号分隔：phone、idcard、bankcard、email、name，或all（默认） |
with_original | boolean | 否 | 是否在detections中回显原文，默认false |
示例：如果只想处理手机号和姓名，可以设置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": "成功" }字段含义如下：
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 业务状态码，0表示成功 |
msg | string | 状态描述 |
data.detection_count | number | 识别出的敏感信息数量 |
data.detections | array | 每次匹配的脱敏结果，包含masked（脱敏后的文本）和type（敏感类型） |
data.masked_text | string | 原始文本中被脱敏后的完整文本 |
data.summary | object | 每种敏感类型的命中数量，如{"phone": 1} |
data.types_applied | array | 本次请求实际应用的类型列表 |
当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