引言在开发调试、日志打印或数据分析过程中原始文本往往携带手机号、身份证号、银行卡号、邮箱甚至中文姓名。若把这些内容直接写入日志或传给第三方容易造成敏感信息泄漏。数据脱敏敏感信息掩码API 提供了一种轻量解法发送一段文本接口会在本地完成正则匹配并返回掩码结果默认不回显原文适合在各类业务流程中作为前置处理步骤。本文以一个最小可运行示例为主线介绍该接口的使用场景、参数约束、鉴权方式、请求构造、返回字段含义以及工程化落地时的注意事项。适用场景数据脱敏可以用于以下典型场景业务日志脱敏在打印订单信息、用户资料前先调用接口把手机号、姓名替换为掩码形态。测试数据准备将生产环境的真实数据转为脱敏文本后再导入测试库。客服工单展示在工单系统或后台管理界面中对用户联系方式做部分隐藏。数据导出审计导出 CSV 或 JSON 数据时对身份证、银行卡等字段做定向掩码。接口不区分业务行业只要文本中包含符合模式的敏感信息就可以通过正则自动识别并处理。接口能力边界在使用前需要明确以下几点接口只处理文本不接收文件上传也不支持批量文件传输。匹配类型包括手机号phone、身份证idcard、银行卡bankcard、邮箱email、中文姓名name也可以通过typesall一次处理全部类型。文本最长 50000 字节约为 1.6 万多个中文字符按 UTF-8 每个汉字 3 字节估算。接口通过正则进行敏感信息检测不依赖外部数据库或人工审核。默认不回显原文只有设置with_originaltrue时返回的detections中才会包含原始敏感信息片段。QPS 限制为 10 / s不适合超高频调用高频场景应在本地做缓存或批量合并。鉴权方式接口采用请求头鉴权需要在每次请求时携带 API KeyX-API-Key: $APIZERO_API_KEY$APIZERO_API_KEY是调用方自己的密钥可以通过环境变量注入也可以直接在命令行中写死但生产环境不建议把密钥提交到代码仓库。请求参数接口地址POST https://v1.apizero.cn/api/desensitize请求体为 JSON 对象字段说明如下参数名类型必填说明textstring是要脱敏的文本最长 50000 字节typesstring否类型逗号分隔如phone,idcard默认allwith_originalboolean否是否在detections中回显原文默认falsetypes支持以下取值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: 注册邮箱aliceexample.com手机13912345678, types: email,phone} \ https://v1.apizero.cn/api/desensitize返回字段解读接口返回的 JSON 结构如下字段类型说明codeint业务状态码0表示成功msgstring状态描述data.detection_countint识别的敏感信息数量data.detectionsarray每个识别项的掩码结果和类型data.detections[].maskedstring掩码后的片段data.detections[].typestring敏感信息类型data.masked_textstring整段文本脱敏后的结果data.summaryobject各类型出现次数统计data.types_appliedarray实际生效的脱敏类型列表其中types_applied明确告诉我们本次请求实际启用了哪些类型的正则便于排查types传参是否生效。如果希望在detections中看到每个敏感片段对应的原文可以将with_original设为truecurl -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字段判断具体原因。常见情况包括请求体不是合法 JSONtext为空或缺失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
