最小可运行示例：用数据脱敏API给文本里的敏感信息打码

引言

在开发调试、日志打印或数据分析过程中，原始文本往往携带手机号、身份证号、银行卡号、邮箱甚至中文姓名。若把这些内容直接写入日志或传给第三方，容易造成敏感信息泄漏。数据脱敏（敏感信息掩码）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 对象，字段说明如下：

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 结构如下：

其中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