引言
在开发调试、日志打印或数据分析过程中，原始文本往往携带手机号、身份证号、银行卡号、邮箱甚至中文姓名。若把这些内容直接写入日志或传给第三方，容易造成敏感信息泄漏。数据脱敏（敏感信息掩码）API 提供了一种轻量解法：发送一段文本，接口会在本地完成正则匹配并返回掩码结果，默认不回显原文，适合在各类业务流程中作为前置处理步骤。
本文以一个最小可运行示例为主线，介绍该接口的使用场景、参数约束、鉴权方式、请求构造、返回字段含义以及工程化落地时的注意事项。
适用场景
数据脱敏可以用于以下典型场景：
- 业务日志脱敏：在打印订单信息、用户资料前，先调用接口把手机号、姓名替换为掩码形态。
- 测试数据准备：将生产环境的真实数据转为脱敏文本后再导入测试库。
- 客服工单展示：在工单系统或后台管理界面中，对用户联系方式做部分隐藏。
- 数据导出审计：导出 CSV 或 JSON 数据时，对身份证、银行卡等字段做定向掩码。
接口不区分业务行业，只要文本中包含符合模式的敏感信息，就可以通过正则自动识别并处理。
接口能力边界
在使用前，需要明确以下几点：
- 接口只处理文本，不接收文件上传，也不支持批量文件传输。
- 匹配类型包括手机号（phone）、身份证（idcard）、银行卡（bankcard）、邮箱（email）、中文姓名（name），也可以通过
types=all一次处理全部类型。 - 文本最长 50000 字节，约为 1.6 万多个中文字符（按 UTF-8 每个汉字 3 字节估算）。
- 接口通过正则进行敏感信息检测，不依赖外部数据库或人工审核。
- 默认不回显原文，只有设置
with_original=true时，返回的detections中才会包含原始敏感信息片段。 - QPS 限制为 10 / s，不适合超高频调用；高频场景应在本地做缓存或批量合并。
鉴权方式
接口采用请求头鉴权，需要在每次请求时携带 API Key：
X-API-Key: $APIZERO_API_KEY$APIZERO_API_KEY是调用方自己的密钥，可以通过环境变量注入，也可以直接在命令行中写死，但生产环境不建议把密钥提交到代码仓库。
请求参数
接口地址：
POST https://v1.apizero.cn/api/desensitize请求体为 JSON 对象，字段说明如下：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 要脱敏的文本，最长 50000 字节 |
types | string | 否 | 类型逗号分隔，如phone,idcard；默认all |
with_original | boolean | 否 | 是否在detections中回显原文，默认false |
types支持以下取值：
phone：手机号idcard：身份证号（15/18 位）bankcard：银行卡号（16-19 位）email：邮箱name：中文姓名all：以上全部类型（默认值）
如果需要同时脱敏手机号和身份证号，可以传：
"types": "phone,idcard"最小可运行示例
下面是一个完整的最小可运行示例，直接复制到终端即可执行：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "联系人：张三，电话 13812348000，身份证 110101199003078888", "types": "phone,idcard,name", "with_original": false }' \ "https://v1.apizero.cn/api/desensitize"请求前确认环境变量APIZERO_API_KEY已设置，否则需要把$APIZERO_API_KEY替换为实际密钥。
执行后返回的 JSON 大致如下：
{ "code": 0, "msg": "成功", "data": { "detection_count": 3, "detections": [ { "masked": "张*", "type": "name" }, { "masked": "138****8000", "type": "phone" }, { "masked": "110101********8888", "type": "idcard" } ], "masked_text": "联系人：张*，电话 138****8000，身份证 110101********8888", "summary": { "name": 1, "phone": 1, "idcard": 1 }, "types_applied": [ "phone", "idcard", "name" ] } }如果你只想脱敏邮箱和手机号，可以这样构造请求体：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "注册邮箱：alice@example.com，手机：13912345678", "types": "email,phone"}' \ "https://v1.apizero.cn/api/desensitize"返回字段解读
接口返回的 JSON 结构如下：
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，0表示成功 |
msg | string | 状态描述 |
data.detection_count | int | 识别的敏感信息数量 |
data.detections | array | 每个识别项的掩码结果和类型 |
data.detections[].masked | string | 掩码后的片段 |
data.detections[].type | string | 敏感信息类型 |
data.masked_text | string | 整段文本脱敏后的结果 |
data.summary | object | 各类型出现次数统计 |
data.types_applied | array | 实际生效的脱敏类型列表 |
其中types_applied明确告诉我们本次请求实际启用了哪些类型的正则，便于排查types传参是否生效。
如果希望在detections中看到每个敏感片段对应的原文，可以将with_original设为true：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "手机 13812348000", "types": "phone", "with_original": true }' \ "https://v1.apizero.cn/api/desensitize"此时detections数组中的元素会多出原始内容字段，例如：
{ "masked": "138****8000", "type": "phone", "original": "13812348000" }需要提醒的是，开启with_original后，接口响应中会包含真实敏感信息，务必确保响应链路本身有足够的访问控制，否则脱敏的意义会打折扣。
常见错误与排查
下面整理了几类接入时容易遇到的问题：
1. 缺少 API Key
如果请求头未携带X-API-Key，接口会返回鉴权失败。排查时先确认环境变量是否正确注入：
echo $APIZERO_API_KEY若输出为空，说明密钥未设置。
2.text超过长度限制
text最长 50000 字节。如果传入超长文本，需要先做截断或分片处理。可以按字节长度切割，避免把中文字符从中间切断。
3.types传值不规范
types只接受小写英文类型名，多个类型用英文逗号分隔。误写成大写或中文逗号会导致部分类型没有生效，此时可以观察返回的types_applied来确认。
4. 返回非零code
当code不为0时，需要结合msg字段判断具体原因。常见情况包括：
- 请求体不是合法 JSON
text为空或缺失types包含不支持的类型
工程化注意事项
1. 日志脱敏优先于日志输出
脱敏 API 应当位于日志写入之前。不要把原文先打进日志，再把脱敏结果写入另一个文件，那样仍然存在泄漏风险。
2. 控制with_original的使用范围
默认false可以避免原文进入响应体。只有在调试或内部审计场景下才建议开启，并且需要避免在公网链路中传输原始敏感信息。
3. QPS 限制与降级策略
接口 QPS 为 10 / s。对调用频率较高的业务，建议增加本地缓存或把待处理文本合并后调用。对于非核心链路，可以考虑异步处理或失败降级：脱敏失败时，业务不应直接中断。
4. 密钥管理
API Key 不要硬编码在前端代码或公开仓库中。建议通过环境变量或配置中心管理，并定期轮换。
5. 正则匹配的局限
接口基于正则匹配，无法对语义做百分百判断。例如符合手机号格式但实际是测试数字的字符串，也会被当作敏感信息处理。若有更高精度要求，需要在上层结合业务规则做二次过滤。
参考文档
- 接口文档：https://apizero.cn/aidocs/desensitize
- 原始文档：https://apizero.cn/aidocs/desensitize/raw.md
