大汉三通云短信接口如何处理发送失败？

Question

在使用大汉三通云短信接口时，常见的技术问题是：当调用接口发送短信后返回“发送失败”状态码（如-1、1003等），开发者如何准确判断失败原因并进行有效重试？由于网络波动、参数错误、账户余额不足或目标号码被列入黑名单等多种因素均可能导致失败，若未对返回码做精细化解析，容易造成消息漏发或重复提交。此外，缺乏合理的异步回调处理和日志记录机制，也会影响问题排查效率。因此，如何结合官方文档对各类错误码进行分类处理，并设计具备幂等性控制的重试机制，成为保障短信送达率的关键技术难点。

Answer 1

大汉三通云短信接口调用失败的深度解析与重试机制设计

1. 常见错误码分类与初步诊断

在调用大汉三通云短信接口时，返回的状态码是判断请求成败的第一依据。常见的失败状态码包括但不限于：

• -1：系统级异常或网络连接中断
• 1003：参数格式错误（如手机号非法、签名缺失）
• 1005：账户余额不足
• 1007：目标号码被运营商列入黑名单
• 1010：频率超限，单位时间内请求过多
• 1012：模板未审核通过
• 1015：IP不在白名单中
• 1020：签名不匹配或未授权
• 2001：内部服务处理超时
• 9999：未知错误

2. 错误码分层处理策略

根据错误性质的不同，可将错误分为以下三类，并制定不同的响应逻辑：

类别	典型错误码	是否可重试	处理建议
客户端错误	1003, 1012, 1020	否	修正参数后重新提交
服务端临时故障	-1, 2001, 1010	是	延迟重试 + 指数退避
资源限制类	1005, 1015	视情况	告警通知 + 人工介入

3. 异步回调机制与状态同步设计

为提升系统健壮性，应启用大汉三通提供的异步回执功能。当短信实际送达用户设备后，平台会推送状态报告至预设URL。示例回调数据结构如下：

{
  "mobile": "13800138000",
  "msgId": "20240405123456789",
  "status": "DELIVRD",
  "receiveTime": "2024-04-05 12:35:01"
}

开发者需在服务端实现幂等接收逻辑，避免因重复回调导致业务状态错乱。

4. 日志记录与链路追踪体系构建

完整的日志应包含：请求ID、手机号、模板ID、发送时间、HTTP状态码、响应体、耗时、调用堆栈。推荐使用MDC（Mapped Diagnostic Context）实现跨线程上下文传递。

关键代码片段：

logger.info("SMS_SEND_TRY", 
    Marker.forStaticLoggerContext(),
    "reqId={}, mobile={}, code={}, resp={}", 
    reqId, mobile, response.getCode(), response.getMessage());

5. 幂等性控制与智能重试机制

为防止因重试造成消息重复发送，必须引入唯一消息标识（如UUID + 手机号 + 模板哈希），并结合Redis进行去重判断：

String lockKey = "sms:dedup:" + DigestUtils.md5Hex(uniqueTag);
Boolean acquired = redisTemplate.opsForValue().setIfAbsent(lockKey, "1", Duration.ofMinutes(5));
if (!acquired) {
    throw new SmsSendException("Duplicate request rejected");
}

6. 重试流程的可视化建模

采用指数退避算法（Exponential Backoff）控制重试节奏，最大尝试3次，间隔分别为1s、2s、4s。

graph TD
            A[发起短信请求] --> B{HTTP响应成功?}
            B -- 否 --> C[记录错误码]
            C --> D{是否属于可重试错误?}
            D -- 是 --> E[等待退避时间]
            E --> F[递增重试计数]
            F --> G[重新请求]
            G --> B
            D -- 否 --> H[终止并告警]
            B -- 是 --> I[检查业务结果]
            I --> J{code == 0?}
            J -- 是 --> K[发送成功]
            J -- 否 --> C

7. 监控告警与自动化运维集成

将短信发送成功率、平均响应时间、高频错误码等指标接入Prometheus + Grafana监控体系。设置阈值触发企业微信/钉钉告警。

例如：连续5分钟失败率 > 5% 时自动通知SRE团队。

8. 最佳实践总结与演进方向

建议建立标准化的短信网关抽象层，封装底层服务商差异，支持多通道切换与熔断降级。未来可结合AI模型预测高危号码段，提前规避黑名单风险。