企业做短信接入问得最多的就是“移动MAS短信发送怎么对接”“HTTP短信发送接口怎么调”。这两个词放在一起其实指向同一个业务场景通过移动MAS网关用HTTP协议把短信发出去。最近帮某公司改造短信模块正好把MAS短信发送从老的半自动方式切换到全HTTP接口自动提交整个过程踩了不少坑也有了一些可以说给后来人听的经验干脆整理成一篇。先说清楚MAS短信发送适合谁。如果你们公司要做验证码、订单通知、物流提醒或者内部系统需要给员工发告警短信一个月几千到几十万条的量级走运营商MAS短信通道基本是性价比最高的选择。MAS这条链路不需要自己建短信中心也不需要租用短信猫只需要从运营商拿到一组HTTP接口的账号和权限业务系统直接发起请求就能把短信发出去省掉了中间一堆硬件和协议转换的事。这篇文章就围绕MAS短信发送和HTTP短信发送这两个核心点展开覆盖原理、对接步骤、常见问题和排查实录适合刚接手短信模块的开发也适合被领导临时安排去对接短信通道的同学。1. MAS短信发送是什么为什么还在用1.1 从需求说起企业短信为什么绕不开MAS很多团队做短信功能第一反应是去注册某个云短信平台充钱、买套餐、调API。但真到了企业级场景尤其是一些传统行业你会发现运营商侧的集团客户短信通道仍然占据很重要的位置。MAS移动代理服务器/Mobile Agent Server是面向集团客户提供的一款信息化接入产品简单理解它就是运营商放在企业内网或者云端的一台“短信代理服务器”把企业业务系统的发送请求转换成短信网元的信令下发。为什么绕不开MAS我分析过几个典型原因。第一是企业本身已经办理了运营商专线或者集团专网IT负责人倾向于在现有网络框架内解决短信需求不愿意再单独拉一条互联网通道。第二是MAS支持HTTPS、专线等相对私密的传输方式不用担心互联网通道被第三方截获头部客户对这点特别在意。第三是MAS的HTTP短信发送接口往往还能顺带拿到状态报告和上行短信也就是用户回复短信的内容这对做双向短信交互的系统来说很关键。1.2 MAS短信发送的三种接入方式对比真正接触MAS短信发送之后会发现它不是只有一种接入形态。按我的实际经验大致能分成下面三种各有各的使用场景。接入方式传输协议适用场景优点缺点HTTP接口HTTP/HTTPS JSON或表单互联网应用、业务系统快速接入开发简单、调试直观、适合大部分企业依赖公网链路需要做好鉴权和加密专线CMPPTCP长连接CMPP协议银行、证券等对稳定性要求极高的客户链路专有可靠性和时效性好接入复杂需要申请专线开发和运维成本高本地MAS服务器本地局域网HTTP服务运营商在客户机房部署一台MAS设备网络隔离内部系统访问方便硬件有维护成本升级和扩容要等运营商HTTP短信发送是这里面普及度最高的一种尤其现在移动云化趋势明显很多MAS能力都变成了一组远程网关接口。我强烈建议中小团队优先用HTTP方式起步先把业务跑通如果后续量巨大、要秒级下行再考虑专线CMPP都不迟。不用一上来就追求高难度MAS的核心目标是把短信稳稳发出去而不是把整个项目做成协议实验室。2. HTTP短信发送接口的底层逻辑2.1 HTTP短信接口的报文与返回设计刚接一个HTTP短信发送接口最要紧的是把报文格式搞清楚。不同省份、不同运营商的MAS网关略有差异但主流设计基本一致都是POST一个表单或JSON到指定URL。核心字段说来说去也就这几个用户名、密码、手机号、短信内容、扩展码、发送时间、全局消息ID。我贴一个实际生产环境里的请求示例curl -X POST https://mas-gateway.example.com/sms/submit \ -H Content-Type: application/x-www-form-urlencoded \ -d userNametest_user \ -d password3ed2f1a4b6c7d8e9f0123456789abcde \ -d mobile13800138000,13900139000 \ -d content%E3%80%90%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7%E3%80%91%E6%82%A8%E7%9A%84%E9%AA%8C%E8%AF%81%E7%A0%81%E6%98%AF123456 \ -d msgId20250111153000123这里有个很容易踩的坑password字段。很多MAS网关不接收明文密码要求先做一次MD5而且有的还要加盐盐往往是用户名加上某个固定密钥。到底用的哪种必须以运营商下发的接口文档为准不能想当然。我见过一个项目开发照着旧系统里的代码抄结果新环境改了摘要算法导致线上全部鉴权失败排查了一下午才发现是密码加密规则没同步。返回报文也值得仔细看。一般会返回一个纯文本或JSON区分成功和失败。成功时返回的往往是一个提交成功的状态码同时回显我们提交的msgId。失败时的错误码需要整理成对照表比如常见的“1”代表鉴权失败“2”代表号码格式错误“3”代表内容包含敏感词“4”代表缺少签名“5”代表余额不足。注意这些码值不是全国统一的每个运营商甚至每个省都有自己的定义最稳妥的做法是从运营商拿一份错误码清单放进项目里做成枚举类后续排查会省非常多力气。2.2 鉴权、防重与幂等设计HTTP短信发送接口不像内部RPC那样可随便重试一条短信重复发两次轻则用户烦重则影响业务。所以鉴权和幂等必须在一开始就设计好。鉴权层面的核心是不要用简单的用户名明文密码裸奔。很多MAS网关支持IP白名单这是最有效的一层先把出口IP加白再从应用层做账号密码校验双保险。如果是HTTPS接口传输本身已经加密但密码还是要做摘要避免数据在网关日志里泄露。我见过有些网关返回报文里会带提交日志明文密码就那样躺在里面这非常危险。幂等这块关键在于msgId或requestId。每次业务系统发起发送请求前先基于业务主键生成一个唯一的msgId例如订单号加发送时间戳。如果网络超时导致不确定是否提交成功我们用同一个msgId再次提交网关侧一般会依据msgId去重返回上一次的提交结果而不是重新下发一条短信。这一点需要在签合同或对接前向运营商确认有些网关压根不做去重那就要自己在应用层做分布式锁或本地去重表来兜底。2.3 长短信、模板变量和字符编码长短信是很多新人在对接HTTP短信发送时忽略的细节。纯英文数字短信单条可以到140字节但中文短信按70字计价超过70字就要分条发送而且计费按多条算。MAS HTTP接口对长短信一般有两种处理方式一种是把整个长文本传给网关由网关自动分片另一种是要求调用方自己拆分。自动分片比较省事但要注意如果内容里有自定义的协议头或者变量拆分点可能落在变量中间导致变量显示不全。所以涉及验证码、金额、订单动态内容的最好控制模板长度固定字幕加变量尽量别超过65个字符。编码问题同样阴魂不散。有些MAS网关严格要求UTF-8编码有些却要求GBK或GB2312。对接时先问清楚再写好编码转换工具类。我建议统一在应用层做UTF-8编码然后在HTTP请求里显式设置charset并且对content做一次URL编码避免特殊字符干扰。实践下来最稳的组合是应用层UTF-8、请求头Content-Type带charset、参数值做URLEncoder。3. 对接实战从申请到跑通全流程3.1 对接前需要向运营商确认的5个关键信息不要急着写代码。先和运营商侧的技术对接人开个短会把下面5件事问清楚后面能少改一版接口。第一接口地址和测试环境地址。很多运营商有专门的联调环境参数和生产不一样务必在配置里区分开。第二账号密码的加密规则包括摘要算法、盐值拼接顺序、是否大小写敏感。第三短信签名报备要求。多数网关要求内容前带有【签名】签名要与营业执照或业务报备名称一致不能乱来。第四状态报告的推送方式是主动推送HTTP回调还是需要调用方定时拉取回调URL如何配置验签规则是什么第五发送频率限制与并发上限。MAS网关不可能允许无限并发要拿到每秒最大提交量、单号码一天最大条数等约束。这些信息每条都很关键尤其是签名报备。我见过一个客户接口已经联调通过上线之后短信全部被拒最后排查发现是签名里有一个字和报备不一致运营商那边一秒钟就拦截下来了。这种问题不在代码层面在商务层面早问早解决。3.2 接口联调的核心实现等上面信息都确认后联调阶段就可以专心跑通链路了。我挑一个典型流程来讲。第一步是本地写一个发送工具类封装HTTP提交、返回解析、异常处理。第二步是拉通一个最简单的发送请求比如给测试手机号发一条固定内容确认返回成功。第三步再验证状态报告看回调地址能不能收到网关推送。写示例代码import requests import hashlib import time def send_sms(user_name, raw_password, secret_key, mobile, content, msg_id): # 密码做MD5摘要具体规则以下发文档为准 password hashlib.md5((raw_password secret_key).encode(utf-8)).hexdigest() url https://mas-gateway.example.com/sms/submit data { userName: user_name, password: password, mobile: mobile, content: content, msgId: msg_id, sendTime: , } response requests.post(url, datadata, timeout10) return response.text这段代码虽然简短但有三个细节值得展开。一是timeout必须设置不然后端线程容易被慢接口拖死二是返回结果不要直接打日志避免明文内容泄漏至少要脱敏处理三是msg_id要由调用方传入而不是在方法内部随机生成否则无法和业务表关联。收到响应后应当先判断HTTP状态码再解析业务返回码。只有业务返回码明确表示成功才能把短信状态置为“已提交”。其他情况统一进失败表走告警和重试。重试要控制次数一般不超过3次间隔按1分钟、5分钟、30分钟梯度递增避免对网关造成压力。3.3 状态报告与上行回复的处理MAS短信发送的价值一半在“发送”另一半在“状态报告”。状态报告也就是短信最终的投递结果比如DELIVRD代表用户已收到UNDELIV代表未送达REJECTD代表被网关拒绝。HTTP接口模式下运营商一般通过回调地址把状态报告推送过来。先写一个接收状态报告的伪代码框架from flask import Flask, request, jsonify app Flask(__name__) app.route(/sms/report, methods[POST]) def sms_report(): payload request.get_json() msg_id payload.get(msgId) mobile payload.get(mobile) status payload.get(status) report_time payload.get(reportTime) # 根据msgId更新数据库中的短信状态 update_sms_status(msg_id, mobile, status, report_time) return jsonify({result: 0})注意运营商要求回调接口必须快速返回且要返回特定值比如“0”或“success”。如果不返回网关会判定回调失败然后多次重推。这本身是好事但会给应用带来重复数据所以处理状态报告时要做幂等同一个msgId的状态只能更新一次重复推送直接用旧纪录覆盖或者忽略。上行短信也是一样的机制用户的回复内容会POST到另一个回调URL。做上行时重点是把手机号和上行内容解析出来并且通过扩展码识别不同业务。比如一个外卖平台不同活动用不同扩展码用户回复“Y”时上下游系统就能知道是针对哪个活动的确认。4. 常见问题速查与排查实录4.1 提交成功但用户收不到短信这个问题排名第一。网关返回提交成功状态报告迟迟不来或者来了显示DELIVRD但用户就是没收到。遇到这种最先怀疑的应当是用户手机端拦截。国内手机自带的安全软件对带链接和营销词的内容非常敏感容易被扔进骚扰拦截这属于“用户侧成功接收但被软件吞掉”的情况。解决办法是引导用户在拦截记录里把号码加白。如果状态报告最终返回了失败码比如EXPIRED过期、UNDELIV未送达那就要检查号码状态。携号转网的号码有时会有兼容问题空号、停机也会导致这类状态。线上遇到这种情况判断思路是先看状态码再按号码归属地细分最后看是否是批量群发触发风控。MAS通道的风控策略往往比云平台更严一批次里如果有多个号码被投诉通道可能被临时关停这种情况只能找运营商人肉申诉。4.2 状态报告半天不回来应用里短信一直停留在“已提交”状态用户跑来问“到底发出去没有”开发也很焦虑。状态报告延迟的可能原因有三个。第一个是回调地址没有公网可达。很多企业内网机器无法被外网访问回调配置的是内网IP或localhost网关推不过来。解决方法是提供一个公网HTTPS地址或者用内网穿透和消息队列中转。第二个是回调处理慢导致网关重推如果回调业务逻辑里查库、发通知、走ES都同步执行响应超过5秒网关可能判定失败然后重推又造成积压。第三个是网关侧本身状态报告就有延迟高峰时段能拖到几分钟甚至更久。这个没法从代码根治只能做好心理预期并且在业务上设计“兜底确认”机制比如短信发出后多少分钟未收到状态报告就触发人工核查或二次短信提醒。另一个容易被忽略的细节状态报告里的msgId或mobile可能和提交时不完全一致。部分网关的msgId会在下发时重新映射或者加上前缀。如果本地一直拿提交时的msgId去关联状态报告会发现怎么都关联不上最后造成明明已经投递成功本地却显示失败。对策是建一个“外部消息ID映射表”把网关返回的唯一ID和本地业务ID绑定起来再更新状态。4.3 签名被拒、模板审核不过MAS短信发送对内容审核要比云平台严格得多尤其涉及营销类文案。签名被拒最常见的原因是签名和报备名称不一致。比如营业执照上叫“某科技有限公司”报备签名却是“某家平台”这种不一致就会被拒。解决方法是签名必须完整包含报备名称中的核心字号如果业务需要多个签名提前在运营商侧做多个签名报备不要上线前临时换。模板审核不过主要是内容里有敏感词或疑似营销词。这里的“敏感”不单指违法违规词还包括“优惠”“免费”“特价”“清仓”这类在金融和零售行业很常见的词。MAS通道对于面向普通用户的营销内容限制尤其多如果业务确实需要做活动通知最好走独立的营销短信通道而不是用验证码和通知类的MAS签名。把两类内容混在一个通道里测试时能发出去正式放量后极易被风控吞掉。5. 实操心得那些文档里不会写的事5.1 别忽视发送限速和队列设计MAS网关几乎都有隐性限速。所谓“隐性”是说文档里不一定写明确数字但一旦并发超过某条线网关就开始丢弃或延后表现为提交成功但状态报告大面积失败。我处理过一个案例业务方在促销时段一次性提交了两万条验证码网关直接延迟几分钟后通道被临时限流。后来我们把发送改成了异步队列做一个简单的调度器按号码维度哈希分桶每桶间隔固定毫秒数控制每秒最大提交量问题才解决。域名解析和连接池也需要提前压测。HTTP短信发送对响应时间很敏感如果使用长连接但服务端主动断开客户端没有及时重连就会有一堆ConnectException。建议使用连接池设置合理的最大连接数和空闲存活时间同时对网关域名做多IP解析防止单点故障。5.2 日志、监控和告警必须提前铺好短信是强依赖外部通道的功能一旦静默失败用户感知极强。所以从一开始就要把日志和监控设计到位。日志至少包括提交日志手机号脱敏、内容脱敏、msgId、返回码、状态报告日志msgId、状态、时间戳、异常日志请求超时、解析失败。监控告警至少覆盖三个维度提交成功率、状态报告返回率、失败码分布。任何指标突然下跌或失败码飙升都应该立刻报警。特别强调内容脱敏。日志里打印完整短信内容一旦日志系统被攻破用户隐私就会泄露。MAS短信经常承载验证码这等于把用户账户的安全凭证放进了日志非常危险。我现在的习惯是日志里只保留手机号前3后4内容只打印模板ID和关键变量长度不打印原文宁可排查时多联合查询一次数据库也不冒明文泄漏的风险。5.3 给新手的几条忠告第一永远以运营商的接口文档为准不要参考老代码老代码可能是几十个版本之前的环境对接的。第二先把回调验签做正确再讨论其他功能。很多MAS网关在状态报告回调里会带一个数字签名参数验签通过才说明数据真实否则任何人都可以伪造状态报告把你的系统搞乱。第三生产环境配置与联调环境配置隔离尤其是账号、密码、URL这三项建议放到配置中心并加密存储。我自己的经验是MAS短信发送这条链路并不复杂但它是典型的“细节决定成败”业务。做好了业务系统可以稳定跑很多年做不好各种莫名其妙的短信丢失、重复发送、模块卡死会耗尽整个团队的耐心。所以宁可前期多花两天做幂等、做监控、做队列也不要用线上事故来交学费。
企业做短信接入问得最多的就是“移动MAS短信发送怎么对接”“HTTP短信发送接口怎么调”。这两个词放在一起其实指向同一个业务场景通过移动MAS网关用HTTP协议把短信发出去。最近帮某公司改造短信模块正好把MAS短信发送从老的半自动方式切换到全HTTP接口自动提交整个过程踩了不少坑也有了一些可以说给后来人听的经验干脆整理成一篇。先说清楚MAS短信发送适合谁。如果你们公司要做验证码、订单通知、物流提醒或者内部系统需要给员工发告警短信一个月几千到几十万条的量级走运营商MAS短信通道基本是性价比最高的选择。MAS这条链路不需要自己建短信中心也不需要租用短信猫只需要从运营商拿到一组HTTP接口的账号和权限业务系统直接发起请求就能把短信发出去省掉了中间一堆硬件和协议转换的事。这篇文章就围绕MAS短信发送和HTTP短信发送这两个核心点展开覆盖原理、对接步骤、常见问题和排查实录适合刚接手短信模块的开发也适合被领导临时安排去对接短信通道的同学。1. MAS短信发送是什么为什么还在用1.1 从需求说起企业短信为什么绕不开MAS很多团队做短信功能第一反应是去注册某个云短信平台充钱、买套餐、调API。但真到了企业级场景尤其是一些传统行业你会发现运营商侧的集团客户短信通道仍然占据很重要的位置。MAS移动代理服务器/Mobile Agent Server是面向集团客户提供的一款信息化接入产品简单理解它就是运营商放在企业内网或者云端的一台“短信代理服务器”把企业业务系统的发送请求转换成短信网元的信令下发。为什么绕不开MAS我分析过几个典型原因。第一是企业本身已经办理了运营商专线或者集团专网IT负责人倾向于在现有网络框架内解决短信需求不愿意再单独拉一条互联网通道。第二是MAS支持HTTPS、专线等相对私密的传输方式不用担心互联网通道被第三方截获头部客户对这点特别在意。第三是MAS的HTTP短信发送接口往往还能顺带拿到状态报告和上行短信也就是用户回复短信的内容这对做双向短信交互的系统来说很关键。1.2 MAS短信发送的三种接入方式对比真正接触MAS短信发送之后会发现它不是只有一种接入形态。按我的实际经验大致能分成下面三种各有各的使用场景。接入方式传输协议适用场景优点缺点HTTP接口HTTP/HTTPS JSON或表单互联网应用、业务系统快速接入开发简单、调试直观、适合大部分企业依赖公网链路需要做好鉴权和加密专线CMPPTCP长连接CMPP协议银行、证券等对稳定性要求极高的客户链路专有可靠性和时效性好接入复杂需要申请专线开发和运维成本高本地MAS服务器本地局域网HTTP服务运营商在客户机房部署一台MAS设备网络隔离内部系统访问方便硬件有维护成本升级和扩容要等运营商HTTP短信发送是这里面普及度最高的一种尤其现在移动云化趋势明显很多MAS能力都变成了一组远程网关接口。我强烈建议中小团队优先用HTTP方式起步先把业务跑通如果后续量巨大、要秒级下行再考虑专线CMPP都不迟。不用一上来就追求高难度MAS的核心目标是把短信稳稳发出去而不是把整个项目做成协议实验室。2. HTTP短信发送接口的底层逻辑2.1 HTTP短信接口的报文与返回设计刚接一个HTTP短信发送接口最要紧的是把报文格式搞清楚。不同省份、不同运营商的MAS网关略有差异但主流设计基本一致都是POST一个表单或JSON到指定URL。核心字段说来说去也就这几个用户名、密码、手机号、短信内容、扩展码、发送时间、全局消息ID。我贴一个实际生产环境里的请求示例curl -X POST https://mas-gateway.example.com/sms/submit \ -H Content-Type: application/x-www-form-urlencoded \ -d userNametest_user \ -d password3ed2f1a4b6c7d8e9f0123456789abcde \ -d mobile13800138000,13900139000 \ -d content%E3%80%90%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7%E3%80%91%E6%82%A8%E7%9A%84%E9%AA%8C%E8%AF%81%E7%A0%81%E6%98%AF123456 \ -d msgId20250111153000123这里有个很容易踩的坑password字段。很多MAS网关不接收明文密码要求先做一次MD5而且有的还要加盐盐往往是用户名加上某个固定密钥。到底用的哪种必须以运营商下发的接口文档为准不能想当然。我见过一个项目开发照着旧系统里的代码抄结果新环境改了摘要算法导致线上全部鉴权失败排查了一下午才发现是密码加密规则没同步。返回报文也值得仔细看。一般会返回一个纯文本或JSON区分成功和失败。成功时返回的往往是一个提交成功的状态码同时回显我们提交的msgId。失败时的错误码需要整理成对照表比如常见的“1”代表鉴权失败“2”代表号码格式错误“3”代表内容包含敏感词“4”代表缺少签名“5”代表余额不足。注意这些码值不是全国统一的每个运营商甚至每个省都有自己的定义最稳妥的做法是从运营商拿一份错误码清单放进项目里做成枚举类后续排查会省非常多力气。2.2 鉴权、防重与幂等设计HTTP短信发送接口不像内部RPC那样可随便重试一条短信重复发两次轻则用户烦重则影响业务。所以鉴权和幂等必须在一开始就设计好。鉴权层面的核心是不要用简单的用户名明文密码裸奔。很多MAS网关支持IP白名单这是最有效的一层先把出口IP加白再从应用层做账号密码校验双保险。如果是HTTPS接口传输本身已经加密但密码还是要做摘要避免数据在网关日志里泄露。我见过有些网关返回报文里会带提交日志明文密码就那样躺在里面这非常危险。幂等这块关键在于msgId或requestId。每次业务系统发起发送请求前先基于业务主键生成一个唯一的msgId例如订单号加发送时间戳。如果网络超时导致不确定是否提交成功我们用同一个msgId再次提交网关侧一般会依据msgId去重返回上一次的提交结果而不是重新下发一条短信。这一点需要在签合同或对接前向运营商确认有些网关压根不做去重那就要自己在应用层做分布式锁或本地去重表来兜底。2.3 长短信、模板变量和字符编码长短信是很多新人在对接HTTP短信发送时忽略的细节。纯英文数字短信单条可以到140字节但中文短信按70字计价超过70字就要分条发送而且计费按多条算。MAS HTTP接口对长短信一般有两种处理方式一种是把整个长文本传给网关由网关自动分片另一种是要求调用方自己拆分。自动分片比较省事但要注意如果内容里有自定义的协议头或者变量拆分点可能落在变量中间导致变量显示不全。所以涉及验证码、金额、订单动态内容的最好控制模板长度固定字幕加变量尽量别超过65个字符。编码问题同样阴魂不散。有些MAS网关严格要求UTF-8编码有些却要求GBK或GB2312。对接时先问清楚再写好编码转换工具类。我建议统一在应用层做UTF-8编码然后在HTTP请求里显式设置charset并且对content做一次URL编码避免特殊字符干扰。实践下来最稳的组合是应用层UTF-8、请求头Content-Type带charset、参数值做URLEncoder。3. 对接实战从申请到跑通全流程3.1 对接前需要向运营商确认的5个关键信息不要急着写代码。先和运营商侧的技术对接人开个短会把下面5件事问清楚后面能少改一版接口。第一接口地址和测试环境地址。很多运营商有专门的联调环境参数和生产不一样务必在配置里区分开。第二账号密码的加密规则包括摘要算法、盐值拼接顺序、是否大小写敏感。第三短信签名报备要求。多数网关要求内容前带有【签名】签名要与营业执照或业务报备名称一致不能乱来。第四状态报告的推送方式是主动推送HTTP回调还是需要调用方定时拉取回调URL如何配置验签规则是什么第五发送频率限制与并发上限。MAS网关不可能允许无限并发要拿到每秒最大提交量、单号码一天最大条数等约束。这些信息每条都很关键尤其是签名报备。我见过一个客户接口已经联调通过上线之后短信全部被拒最后排查发现是签名里有一个字和报备不一致运营商那边一秒钟就拦截下来了。这种问题不在代码层面在商务层面早问早解决。3.2 接口联调的核心实现等上面信息都确认后联调阶段就可以专心跑通链路了。我挑一个典型流程来讲。第一步是本地写一个发送工具类封装HTTP提交、返回解析、异常处理。第二步是拉通一个最简单的发送请求比如给测试手机号发一条固定内容确认返回成功。第三步再验证状态报告看回调地址能不能收到网关推送。写示例代码import requests import hashlib import time def send_sms(user_name, raw_password, secret_key, mobile, content, msg_id): # 密码做MD5摘要具体规则以下发文档为准 password hashlib.md5((raw_password secret_key).encode(utf-8)).hexdigest() url https://mas-gateway.example.com/sms/submit data { userName: user_name, password: password, mobile: mobile, content: content, msgId: msg_id, sendTime: , } response requests.post(url, datadata, timeout10) return response.text这段代码虽然简短但有三个细节值得展开。一是timeout必须设置不然后端线程容易被慢接口拖死二是返回结果不要直接打日志避免明文内容泄漏至少要脱敏处理三是msg_id要由调用方传入而不是在方法内部随机生成否则无法和业务表关联。收到响应后应当先判断HTTP状态码再解析业务返回码。只有业务返回码明确表示成功才能把短信状态置为“已提交”。其他情况统一进失败表走告警和重试。重试要控制次数一般不超过3次间隔按1分钟、5分钟、30分钟梯度递增避免对网关造成压力。3.3 状态报告与上行回复的处理MAS短信发送的价值一半在“发送”另一半在“状态报告”。状态报告也就是短信最终的投递结果比如DELIVRD代表用户已收到UNDELIV代表未送达REJECTD代表被网关拒绝。HTTP接口模式下运营商一般通过回调地址把状态报告推送过来。先写一个接收状态报告的伪代码框架from flask import Flask, request, jsonify app Flask(__name__) app.route(/sms/report, methods[POST]) def sms_report(): payload request.get_json() msg_id payload.get(msgId) mobile payload.get(mobile) status payload.get(status) report_time payload.get(reportTime) # 根据msgId更新数据库中的短信状态 update_sms_status(msg_id, mobile, status, report_time) return jsonify({result: 0})注意运营商要求回调接口必须快速返回且要返回特定值比如“0”或“success”。如果不返回网关会判定回调失败然后多次重推。这本身是好事但会给应用带来重复数据所以处理状态报告时要做幂等同一个msgId的状态只能更新一次重复推送直接用旧纪录覆盖或者忽略。上行短信也是一样的机制用户的回复内容会POST到另一个回调URL。做上行时重点是把手机号和上行内容解析出来并且通过扩展码识别不同业务。比如一个外卖平台不同活动用不同扩展码用户回复“Y”时上下游系统就能知道是针对哪个活动的确认。4. 常见问题速查与排查实录4.1 提交成功但用户收不到短信这个问题排名第一。网关返回提交成功状态报告迟迟不来或者来了显示DELIVRD但用户就是没收到。遇到这种最先怀疑的应当是用户手机端拦截。国内手机自带的安全软件对带链接和营销词的内容非常敏感容易被扔进骚扰拦截这属于“用户侧成功接收但被软件吞掉”的情况。解决办法是引导用户在拦截记录里把号码加白。如果状态报告最终返回了失败码比如EXPIRED过期、UNDELIV未送达那就要检查号码状态。携号转网的号码有时会有兼容问题空号、停机也会导致这类状态。线上遇到这种情况判断思路是先看状态码再按号码归属地细分最后看是否是批量群发触发风控。MAS通道的风控策略往往比云平台更严一批次里如果有多个号码被投诉通道可能被临时关停这种情况只能找运营商人肉申诉。4.2 状态报告半天不回来应用里短信一直停留在“已提交”状态用户跑来问“到底发出去没有”开发也很焦虑。状态报告延迟的可能原因有三个。第一个是回调地址没有公网可达。很多企业内网机器无法被外网访问回调配置的是内网IP或localhost网关推不过来。解决方法是提供一个公网HTTPS地址或者用内网穿透和消息队列中转。第二个是回调处理慢导致网关重推如果回调业务逻辑里查库、发通知、走ES都同步执行响应超过5秒网关可能判定失败然后重推又造成积压。第三个是网关侧本身状态报告就有延迟高峰时段能拖到几分钟甚至更久。这个没法从代码根治只能做好心理预期并且在业务上设计“兜底确认”机制比如短信发出后多少分钟未收到状态报告就触发人工核查或二次短信提醒。另一个容易被忽略的细节状态报告里的msgId或mobile可能和提交时不完全一致。部分网关的msgId会在下发时重新映射或者加上前缀。如果本地一直拿提交时的msgId去关联状态报告会发现怎么都关联不上最后造成明明已经投递成功本地却显示失败。对策是建一个“外部消息ID映射表”把网关返回的唯一ID和本地业务ID绑定起来再更新状态。4.3 签名被拒、模板审核不过MAS短信发送对内容审核要比云平台严格得多尤其涉及营销类文案。签名被拒最常见的原因是签名和报备名称不一致。比如营业执照上叫“某科技有限公司”报备签名却是“某家平台”这种不一致就会被拒。解决方法是签名必须完整包含报备名称中的核心字号如果业务需要多个签名提前在运营商侧做多个签名报备不要上线前临时换。模板审核不过主要是内容里有敏感词或疑似营销词。这里的“敏感”不单指违法违规词还包括“优惠”“免费”“特价”“清仓”这类在金融和零售行业很常见的词。MAS通道对于面向普通用户的营销内容限制尤其多如果业务确实需要做活动通知最好走独立的营销短信通道而不是用验证码和通知类的MAS签名。把两类内容混在一个通道里测试时能发出去正式放量后极易被风控吞掉。5. 实操心得那些文档里不会写的事5.1 别忽视发送限速和队列设计MAS网关几乎都有隐性限速。所谓“隐性”是说文档里不一定写明确数字但一旦并发超过某条线网关就开始丢弃或延后表现为提交成功但状态报告大面积失败。我处理过一个案例业务方在促销时段一次性提交了两万条验证码网关直接延迟几分钟后通道被临时限流。后来我们把发送改成了异步队列做一个简单的调度器按号码维度哈希分桶每桶间隔固定毫秒数控制每秒最大提交量问题才解决。域名解析和连接池也需要提前压测。HTTP短信发送对响应时间很敏感如果使用长连接但服务端主动断开客户端没有及时重连就会有一堆ConnectException。建议使用连接池设置合理的最大连接数和空闲存活时间同时对网关域名做多IP解析防止单点故障。5.2 日志、监控和告警必须提前铺好短信是强依赖外部通道的功能一旦静默失败用户感知极强。所以从一开始就要把日志和监控设计到位。日志至少包括提交日志手机号脱敏、内容脱敏、msgId、返回码、状态报告日志msgId、状态、时间戳、异常日志请求超时、解析失败。监控告警至少覆盖三个维度提交成功率、状态报告返回率、失败码分布。任何指标突然下跌或失败码飙升都应该立刻报警。特别强调内容脱敏。日志里打印完整短信内容一旦日志系统被攻破用户隐私就会泄露。MAS短信经常承载验证码这等于把用户账户的安全凭证放进了日志非常危险。我现在的习惯是日志里只保留手机号前3后4内容只打印模板ID和关键变量长度不打印原文宁可排查时多联合查询一次数据库也不冒明文泄漏的风险。5.3 给新手的几条忠告第一永远以运营商的接口文档为准不要参考老代码老代码可能是几十个版本之前的环境对接的。第二先把回调验签做正确再讨论其他功能。很多MAS网关在状态报告回调里会带一个数字签名参数验签通过才说明数据真实否则任何人都可以伪造状态报告把你的系统搞乱。第三生产环境配置与联调环境配置隔离尤其是账号、密码、URL这三项建议放到配置中心并加密存储。我自己的经验是MAS短信发送这条链路并不复杂但它是典型的“细节决定成败”业务。做好了业务系统可以稳定跑很多年做不好各种莫名其妙的短信丢失、重复发送、模块卡死会耗尽整个团队的耐心。所以宁可前期多花两天做幂等、做监控、做队列也不要用线上事故来交学费。
：Aquilon系统介绍)
实现原理)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
