短信接口这个东西，说简单也简单，无非就是把一段文本推给平台的网关，平台再往下发；说麻烦也麻烦，真正落到生产环境，签名、模板、编码、回执、限流、幂等、重试，一个环节没处理好就是线上事故。我这次要聊的是云MAS平台短信接口的完整对接过程——从账号申请到第一行代码跑通，再到把它变成一个能扛住日发几万条的业务组件。如果你手上正拿着一份平台给的接口文档，看得懂每个字段但不知道从哪儿下手；或者你的系统已经接了短信，但回执丢失、重复发送、内容超长这些坑一直没根治，那这篇东西应该能帮你省掉几天摸索。我把整个链路拆成五个部分来讲，包括接口形态选型、前置准备、报文细节、代码封装和故障排查，中间穿插我自己踩过的坑，代码和参数都可以直接拿去改改就用。
1. 先搞清楚MAS短信接口到底是什么形态
1.1 从业务代码到手机屏幕的完整链路
很多人对接短信时脑子里只有"调一个HTTP接口"，实际上从你的业务系统到用户手机，中间至少横跨五六个环节。你的业务代码发起一次提交请求，请求打到云MAS平台的前置机上；前置机做鉴权、签名校验、号码合规和内容过滤；过了这一关，消息进入平台内部的发送队列；队列按优先级和通道负载调度到具体的短信中心；短信中心下发到用户所在的网络，最后落到手机。成功后返回一个msgid，失败后返回一个错误码。这条链路上任何一环卡住，你在业务侧看到的都是"短信没收到"，但原因可能天差地别。
我习惯把这个链路画成一条"责任分界线"：提交接口的成功只代表平台收下了这条消息，不代表用户收到了。这是新手最容易误解的一点。平台返回"提交成功"时，消息可能还在队列里排队，也可能已经被下游拒绝，真正的结果要靠状态报告（回执）来确认。所以一套完整的对接必须包含三个方向：上行——你提交短信；下行——平台回推状态报告；反向——用户回复短信时平台把上行内容推给你。只做第一个方向，等于开车不看仪表盘。
理解这条链路还有个实际好处：出问题时你能快速定位是哪一段的责任。平台返回码是0但用户没收到，问题多半在下游通道或者号码本身的状态；平台返回码是负数，那就是你的报文有问题，跟下游无关。这个判断能帮你省掉大量和平台侧来回扯皮的时间。
1.2 HTTP短连接、长连接协议、SDK三种接入方式怎么选
云MAS平台一般会同时提供几种接入形态，文档里往往都列着，但不会告诉你什么场景该用哪个。我按实际使用体验做个对照。
| 接入方式 | 典型形态 | 适用场景 | 主要缺点 |
|---|---|---|---|
| HTTP短连接 | POST表单或JSON，一问一答 | 日发送量万级以下，业务分散 | 每次建连开销大，高并发下延迟抖动明显 |
| 长连接协议 | 私有二进制协议，需维持心跳 | 日发送量十万级以上，要求低延迟 | 实现复杂，要处理断线重连和滑动窗口 |
| 平台SDK | 平台封装的jar或动态库 | 想快速跑通验证阶段 | 版本绑定死，出问题不好排查 |
我的建议很直接：除非你的日均发送量稳定在十万条以上，否则一律先上HTTP短连接。理由不是HTTP更先进，而是它的可观测性最好——请求报文、响应报文、耗时、返回码全是明文，出问题抓个包就能看明白。长连接协议为了效率牺牲了可读性，二进制帧解出来一堆字节，排查成本高一个量级。而且短连接天然支持水平扩展，业务量涨了加机器就行，不用担心连接数分配。
真正需要切长连接的信号有三个：一是HTTP接口的QPS已经到了平台给你的上限，加机器也没用；二是你对下发延迟有硬要求，比如验证码要求两秒内到达，而短连接在高峰期建连就花掉几百毫秒；三是你的发送量已经到了按通道包销更划算的量级。这三个条件不满足之前，别为了"看起来更专业"去啃长连接协议，性价比很低。
还有一点要提醒：有些平台的HTTP接口和长连接接口走的是不同的通道资源，返回码体系和限流阈值都不一样。切换之前务必确认清楚，别以为换了个接入方式其他东西都不变。
2. 动手写代码之前必须搞定的事
2.1 账号、签名、模板这三样东西的正确申请姿势
很多人拿到账号密码就开始写代码，结果调通了接口却发不出去，回头一看是签名没备案。这三样东西的申请顺序和依赖关系得先理顺。
账号分两种：管理账号和发送账号。管理账号用来登录平台后台配置签名模板、查余额、看报表；发送账号才是接口里用的那个，通常带一个企业标识前缀。有些平台把两者合一，有些严格分离，申请时问清楚。发送账号还绑定了子端口号（扩展码），这个码会出现在用户收到的短信里，也决定了上行短信回推到哪个地址，别随便填。
签名就是短信开头那个方括号，比如【某某科技】。它必须提前在平台侧备案，备案时要提供主体资质材料，审核周期从半天到三天不等。这里有个高频坑：签名的字数算在单条短信的长度里，一个签名占6到8个字，直接吃掉你十分之一的内容空间。所以签名别起太长，四到六个字最合适，既能识别又不浪费计费长度。另外签名一旦备案通过，改动要走变更流程，别在代码里硬编码一个还没批下来的签名去测试，返回的会是签名不合法。
模板是现在的主流做法。纯自定义内容的短信在很多场景已经被限制，必须用报备过的模板加变量填充。模板申请时要写清楚变量位置和示例值，审核方会看内容是否合规。模板ID拿到后，代码里传的是模板ID加一组变量，平台负责拼装。这里要注意变量长度：模板正文加上变量实际值，总长度不能超限，变量太长一样会被截断或者拒发。
提示：签名和模板的审核状态是会变的，平台可能因为内容调整策略而下线某个模板。生产环境里最好加一个启动自检，把用到的模板ID列出来，定期查一次状态，别等发不出去才发现模板被停了。
2.2 网络连通性：白名单、端口、出口IP这三关
MAS平台通常部署在专有网络里，企业侧要接进去必须过三道关，任何一道没通，你看到的都是连接超时，而且报错信息毫无指向性。
第一关是出口IP白名单。平台侧会把你服务器的公网出口IP加进允许列表，不在列表里的请求直接拒绝。这里最容易出问题的是服务器有多出口的情况——比如你的应用部署在容器里，出口IP经过地址转换后和你在平台上登记的不是同一个。排查方法很简单，在服务器上执行一次查询自己出口地址的命令，拿到的结果和平台登记的对比。如果是集群部署，所有节点可能的出口地址都要登记，或者统一走一个固定的出口。
第二关是端口放通。平台接口常用的端口是8080、9090这类非标准端口，企业防火墙默认只放通80和443，请求出去就被拦了。这一关的特点是现象诡异——telnet能通但请求超时，或者偶尔通偶尔不通，因为防火墙策略可能是按会话做的。建议直接用抓包工具在服务器上抓一次请求，看SYN包有没有发出去、有没有收到回应，一眼就能判断是本地拦了还是对端拦了。
第三关是回调地址可达。状态报告和上行短信是平台主动推给你的，这就要求你的服务有一个平台能访问到的地址。内网地址平台访问不到，必须做地址映射。而且这个映射要稳定，地址一变回执就全丢了。我见过有团队把回调地址配在一台临时测试机上，上线后忘了改，跑了一个月发现回执一条没有，白白丢了所有送达数据。
注意：回调地址的连通性测试不要只测一次。平台侧推送往往有重试机制，如果你的服务在重试窗口内一直不可达，平台可能判定地址失效并降低推送频率，后续即使恢复了也会延迟很久才补齐。
2.3 编码与长度：被低估的两个隐形炸弹
编码问题在对接初期几乎必然遇到一次。MAS平台的接口对编码的支持不完全一致，有的要求UTF-8，有的要求GBK，还有的接口提交用UTF-8但回执推回来是GBK。表现就是：接口返回成功，用户收到的是一串问号或者乱码。
处理原则是以平台文档为准，并且显式声明。请求头里带上字符集声明，报文体按声明的编码序列化，不要依赖默认值。如果平台要求GBK而你的业务系统是UTF-8，在发送前做一次转码，转完再算长度——因为GBK下一个汉字占2字节，UTF-8下占3字节，长度算法完全不同。这一点在判断"内容是否超长"时特别关键，用错编码算长度会导致你以为没超，实际超了，平台直接拒发。
长度规则本身也要吃透。单条短信的计费长度是70个字，这里的"字"指字符数而不是字节数，一个汉字算一个字，一个英文字母也算一个字。超过70字自动拆成多条长短信，每条按67字计算（因为要占用几个字节做拼接标识），费用按拆分后的条数收。举个例子，一条含80个汉字的短信，会拆成2条，收2条的钱。签名也算在内。这个规则决定了你的文案设计：能压到70字以内就压，压不下去要算清楚成本，营销类短信对成本非常敏感。
还有个细节：部分平台对长短信的拼接有开关，关掉之后超过70字的部分会被直接截断，用户收到的是半句话。上线前一定要用一条超长内容做一次实测，看用户端收到的是完整两条还是被截断，这个实验五分钟就能做完，能避免后续大量客诉。
3. 三个核心接口的报文细节拆解
3.1 提交接口：必填字段背后的校验逻辑
提交接口是所有对接工作的核心，字段看着不多，但每个字段背后都有一层校验，理解这些校验能让你少走很多弯路。下面是一份典型报文的字段说明，不同平台版本会有差异，但核心字段基本一致。
| 字段 | 是否必填 | 说明 | 常见坑 |
|---|---|---|---|
| account | 是 | 发送账号 | 用成管理账号会鉴权失败 |
| password | 是 | 密码摘要，通常为MD5大写32位 | 大小写敏感，部分平台要求加时间戳 |
| mobile | 是 | 手机号，多个用英文逗号分隔 | 用中文逗号或分号会整体失败 |
| content | 是 | 短信正文，需含签名 | 签名缺失会被内容审核拦截 |
| templateId | 视场景 | 模板编号 | 模板变量个数必须与模板定义一致 |
| sendTime | 否 | 定时发送时间，格式yyyyMMddHHmmss | 格式错会被当成立即发送或直接报错 |
| extend | 否 | 扩展码/子端口 | 影响上行回推路由 |
| msgId | 否 | 业务侧唯一流水号 | 不传则无法做幂等，重复提交会重复发 |
密码摘要这块值得单独说。绝大多数平台不传明文密码，而是要求传一次摘要值。最常见的算法是把账号和密码拼接后做MD5，取32位大写。有些平台还要求带上时间戳一起摘要，防止重放。算法写错的表现是返回"账号或密码错误"，但这个错误码和真的密码错误长得一样，很容易误判。判断方法：先用平台提供的在线调试工具或者官方示例代码跑一次，确认摘要算法，再往自己的代码里搬。别自己猜。
mobile字段的批量能力要善用。多数平台支持一次提交多个号码，上限从100到500不等。批量提交能显著降低请求次数和连接开销，但要注意两点：一是批量提交的返回是整体返回，不区分单个号码的成功失败，如果其中一个号码格式不合法，可能整批失败；二是部分平台对批量的大小有限制，超过上限直接拒绝，不做部分处理。所以批量之前先在本地做号码格式预校验，把不合法的剔出去，别一股脑丢给平台。
msgId这个字段很多人不传，我觉得是最不该省的。它是你做幂等和追踪的唯一抓手。生成规则建议是业务前缀加时间戳加随机位，保证全局唯一。有了它，你可以在本地建一张发送记录表，提交前先查一下这个msgId有没有发过，避免重试逻辑导致重复发送——这在验证码场景下是致命的，用户收到两条不同验证码，不知道该填哪个。
一个最简的提交示例，用HTTP表单方式：
curl -X POST "http://平台地址:8080/sms/mt" \ -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \ --data-urlencode "account=企业发送账号" \ --data-urlencode "password=摘要值" \ --data-urlencode "mobile=13800000000,13900000000" \ --data-urlencode "content=【某某科技】您的验证码是123456，5分钟内有效。" \ --data-urlencode "msgId=BIZ20240101120000001" \ --data-urlencode "sendTime="响应一般是一个精简的文本或JSON，包含返回码和msgid。返回码为成功时，把平台返回的msgid和你自己的业务流水号一起落库，后面回执匹配要用。
3.2 状态报告接口：回执匹配与丢失处理
状态报告是平台主动推送到你配置的回调地址上的，通常是一批一批推，报文里包含msgid、手机号、状态码和时间。这个接口你必须自己实现一个接收端点，而且要做到三个"必须"。
必须快速响应。平台推送回执时有超时限制，一般两三秒。如果你的处理逻辑里有数据库慢查询或者远程调用，很容易超时，平台会判定推送失败并重试，重试几次还失败就可能停止推送。正确的做法是：收到请求后立刻返回成功，把报文丢进本地消息队列，异步去做落库和业务处理。这个模式叫"接收即返回"，是回执接收的标准做法。
必须做幂等。平台的重试机制意味着同一条回执你可能收到多次。落库时用msgid加状态码做唯一约束，重复的直接忽略，别让一条回执触发两次业务动作。我见过一个场景，回执重复处理导致订单状态被改了两遍，虽然结果一样但日志乱成一团，排查花了好久。
必须处理匹配失败。回执里的msgid是平台侧的，你需要在本地表里能查到对应的业务记录。如果查不到，通常是两种情况：一是你的落库比回执到达还慢，这是典型的竞态问题，处理办法是匹配失败时先落一张待匹配表，过一会儿再补偿匹配；二是回执里的msgid字段名或格式和你预期的不一致，这个要提前和平台确认，用实际报文验证。
状态码的取值各家不同，常见的有"DELIVRD"表示成功送达、"UNDELIV"表示未送达、"EXPIRED"表示过期、"REJECTD"表示被拒。这里的关键认知是："未送达"不等于"没发出去"，可能用户关机、停机、号码空号、或者手机内存满。这些情况在业务侧要不要重发，得按场景定。验证码类不重发，因为用户可能已经通过其他方式获取了；通知类可以有限重试，但要设上限，别把欠费号码天天发。
回执丢失是另一个绕不开的话题。现实里回执到达率不可能100%，能到95%以上就算健康。对于没有回执的消息，业务侧不能无限等待，要设一个超时兜底——比如24小时内没收到回执，就按"状态未知"处理，走人工或者降级渠道。这个兜底逻辑必须做，否则你的发送记录里会永远躺着一批状态不明的数据。
3.3 上行短信接口：用户回复怎么接住
上行短信是指用户回复你发出的短信，平台把这个回复内容推送到你配置的上行地址。很多系统对接时直接忽略这部分，觉得用不上，但真到需要的时候——比如用户回复"退订"，你没接住，就会持续骚扰用户，最后被投诉。
上行报文一般包含用户号码、回复内容、接收时间、扩展码。处理逻辑比回执复杂一点，因为要做内容解析和意图判断。最常见的是退订指令，用户回复"TD"、"退订"、"取消"这类关键词，你需要把号码加入黑名单。这个动作要快，因为退订是有时效要求的，处理晚了用户可能再投诉一次。
扩展码在这里起关键作用。如果你用的是共享通道，同一个平台上可能跑着你多个业务线的短信，上行推过来时靠扩展码区分是哪条业务线发的。所以提交短信时一定要带上扩展码，不然上行内容推过来你不知道该路由给哪个业务模块。
上行还有一个容易被忽视的作用：它是最好的内容质量信号。用户回复"你是哪位"“发错了”这类内容，说明你的触达名单有问题；回复"怎么退订"说明你的频次控制没做好。把这些上行内容做分类统计，比看发送成功率更能反映实际问题。我在一个项目里就是通过统计上行内容发现某批号码是错误采集的，及时止损。
提示：上行内容的解析不要做过度智能化的关键词匹配，容易误伤。比如用户回复"不要发了谢谢"，如果你的关键词是"不要"，可能被误判成退订，实际人家只是客气。稳妥做法是维护一个明确的指令词表，只认表内的词，表外的走人工复核。
4. 把接口封装成能上生产的组件
4.1 从裸调用到工程化：四个必须补上的能力
把接口调通只是起点，真正能上生产还得补四样东西：重试、限流、幂等、可观测。这四样缺一样，跑一段时间就会出问题。
重试要有边界。什么错能重试，什么错不能，得分清楚。网络超时、连接被拒这类传输层错误可以重试，因为请求可能压根没到平台；返回码是"系统繁忙"“队列满”这类临时性错误可以重试；但"号码格式错误"“签名不合法”“余额不足”这类业务错误重试一万次也没用，只会浪费资源。重试次数建议两到三次，采用递增间隔，别用固定间隔，固定间隔在平台侧出现拥塞时会加剧拥塞。
限流是保护自己也是保护平台。平台给你的账号有QPS上限，超了会返回限流错误甚至临时封禁。本地要有一个令牌桶或者信号量控制并发，阈值设在平台上限的七成左右，留出余量。这个余量的作用是应对突发——比如某个业务模块一次性提交了大量消息，限流器能把它削峰填谷，而不是一股脑打过去被拒。
幂等前面提过，核心是业务流水号加本地去重表。这里补充一个细节：去重表的过期时间要设，不能无限增长。一般设24小时，因为超过这个时间的重试已经没有意义了。清理任务用定时任务做，别在请求路径上做删除，会影响响应时间。
可观测包含三块：日志、指标、告警。日志要记录完整报文（注意脱敏，手机号中间四位打码）、耗时、返回码、msgid，一条日志一行，方便检索。指标至少要有提交量、成功率、平均耗时、回执到达率、余额。告警阈值这样设：成功率低于95%告警，回执到达率低于90%告警，余额低于三天用量告警。这几个指标能覆盖绝大多数异常场景。
4.2 一份可以直接改用的封装代码
下面这个封装用Python写，结构简单，重点是展示那几个能力的落点。实际用的时候按你的技术栈翻译就行，逻辑是通用的。
import hashlib, time, uuid, logging from datetime import datetime class SmsClient: def __init__(self, account, password, endpoint, qps_limit=10): self.account = account self.password = password self.endpoint = endpoint self.qps_limit = qps_limit self.logger = logging.getLogger("sms") def _digest(self): # 常见算法：账号+密码拼接后取MD5大写32位，以平台文档为准 raw = f"{self.account}{self.password}" return hashlib.md5(raw.encode("utf-8")).hexdigest().upper() def _gen_msg_id(self, biz_type): return f"{biz_type}{datetime.now():%Y%m%d%H%M%S}{uuid.uuid4().hex[:6]}" def send(self, mobiles, content, biz_type="BIZ", retry=2): msg_id = self._gen_msg_id(biz_type) payload = { "account": self.account, "password": self._digest(), "mobile": ",".join(mobiles), "content": content, "msgId": msg_id, } for attempt in range(retry + 1): start = time.time() try: resp = self._post(payload) cost = int((time.time() - start) * 1000) self.logger.info("sms_submit msgId=%s cost=%sms resp=%s", msg_id, cost, resp) if resp.get("code") == "0": return {"ok": True, "msgId": msg_id, "platformId": resp.get("msgid")} if not self._retryable(resp.get("code")): return {"ok": False, "msgId": msg_id, "code": resp.get("code")} except Exception as e: self.logger.warning("sms_submit_error msgId=%s attempt=%s err=%s", msg_id, attempt, e) time.sleep(0.3 * (attempt + 1)) return {"ok": False, "msgId": msg_id, "code": "RETRY_EXHAUSTED"} def _retryable(self, code): # 只有临时性错误才重试，业务错误直接返回 return code in ("SYSTEM_BUSY", "QUEUE_FULL", "TIMEOUT") def _post(self, payload): # 具体HTTP实现略，注意设置超时和字符集 ...这段代码里有三个设计点值得展开。第一，_digest()每次调用都重新计算，而不是在初始化时算一次缓存起来。原因是有些平台的摘要算法里带时间戳，缓存会导致过期失败。如果你的平台摘要不含时间变量，改成缓存能省一点CPU，但差别可以忽略，不如保持简单。第二，_retryable()把可重试的返回码白名单化，这是"默认不重试"的思路——只有明确知道可以重试的才重试，其他一律返回。这个思路比黑名单安全得多，因为平台新增返回码时黑名单会漏。第三，日志里把msgId放在最前面，方便按msgId搜索整条链路。
4.3 并发控制和连接管理的一些细节
HTTP短连接在高并发下的主要开销在TCP握手和TLS握手。如果平台接口是HTTPS，每次请求都要完整握手，延迟会明显上去。解决办法是复用连接，用连接池。连接池的大小设成并发数的1.5倍左右，别设太大，太大反而会因为连接空闲被对端关闭而产生一堆无效连接。
超时设置要分两段：连接超时和读取超时。连接超时设短一点，两三秒，因为连不上就是连不上，等太久没意义；读取超时设长一点，五到十秒，因为平台在处理高峰时响应可能变慢，读超时设太短会误判成失败然后重试，反而加重平台负担。
并发度怎么定？先按平台的QPS上限反推。假设平台给你20 QPS，单次请求平均耗时200毫秒，那么并发数大致是 20 × 0.2 = 4 就能跑满，设到6到8留点余量。这个算法比拍脑袋设个50要靠谱得多——并发数超过必要值，多出来的线程只是在排队，不提升吞吐，还增加内存和上下文切换开销。
批量提交和单条提交要分开处理。批量适合营销类场景，一次几十上百个号码，吞吐高；单条适合验证码这类要求低延迟、需要精确知道每个号码结果的场景。别用一种方式覆盖所有场景，那会逼着你在延迟和吞吐之间做不情愿的妥协。
5. 排查实录：那些文档里不会写的坑
5.1 返回码速查与对症处理
各平台的返回码定义有差异，但错误类型高度相似。下面这张表是按错误性质整理的处理思路，具体码值以你手上的文档为准。
| 错误类型 | 常见表现 | 根因判断 | 处理方式 |
|---|---|---|---|
| 鉴权失败 | 账号或密码错误 | 摘要算法不一致，或账号类型用错 | 用官方示例验证摘要，确认发送账号 |
| 签名不合法 | 内容审核不通过 | 签名未备案或与备案内容不一致 | 核对签名字符，包括括号类型 |
| 号码格式错误 | 整批提交失败 | 存在非法号码，或用了中文逗号 | 本地正则预校验，剔除后重提 |
| 内容超长 | 拒发或截断 | 编码用错导致长度计算偏差 | 按平台编码算长度，留出签名空间 |
| 敏感词拦截 | 内容审核不通过 | 文案含平台词库内的词 | 换表述，别试图绕过 |
| 余额不足 | 提交全部失败 | 账户余额低于阈值 | 做余额监控，提前充值 |
| 频率超限 | 间歇性失败 | 超出账号QPS | 本地限流，压到上限七成 |
| 连接超时 | 无返回码 | 白名单、端口、网络问题 | 服务器侧抓包定位 |
这张表里我想多说两句"敏感词拦截"。很多人遇到拦截第一反应是找变体写法绕过去，比如把字拆开、加符号、用谐音，这是绝对错误的方向。平台拦截的内容通常是监管要求，绕过拦截意味着你发出去的内容本身有问题，后果比发不出去严重得多。正确做法是改文案，或者和平台侧的对接人沟通确认词库边界。合规这条线不能碰。
"内容超长"这个坑我再补充一个细节。有些平台的长度计算把签名也算进去，有些不把签名算进去但发送时会自动加上，导致你以为还有余量实际已经超了。判断方法很简单：发一条正好70字的带签名内容，看返回是成功还是超长，一次实验就能确定规则。这种实验成本极低，收益极高，我建议每个新对接的平台都做一遍边界测试。
5.2 三个真实场景的排查思路
场景一：提交成功率高但用户投诉收不到。这个组合说明问题不在你的提交环节，而在下游。排查顺序是：先看回执状态分布，如果大量是未送达，那就是通道或号码问题；如果回执全是成功但用户说没收到，那可能是用户手机拦截了，或者号码归属地异常。第二步抽样看具体号码的回执明细，找出是哪些号段集中出问题。第三步拿一个确定正常的号码做对照测试。这套流程走下来，基本能定性是通道质量问题还是名单质量问题。前者要找平台侧要说法，后者要清洗你的号码库。
场景二：回执一条都收不到，但提交正常。九成是回调地址的问题。排查顺序：先确认平台后台配置的回调地址是不是当前服务的地址，特别注意有没有配成测试环境的；然后用外部工具模拟平台推一条回执到你的地址，看服务能不能收到；最后看服务日志里有没有平台来源的请求记录。这三步能覆盖绝大多数情况。还有一种少见但坑人的情况：你的服务前面有一层网关或者负载均衡，它把平台的回推请求当成异常流量拦了，因为请求的路径不常见或者请求体格式特殊。这种要看网关的访问日志才能发现。
场景三：短信内容出现乱码，且只出现在部分号码上。这个现象很有迷惑性。乱码跟号码无关，跟编码有关，但为什么只出现在部分号码上？答案往往是那些号码走了不同的通道，而不同通道对编码的支持不一样。有些老通道只认GBK，你发UTF-8过去它就乱码。解决办法是统一按最保守的编码发送，或者在提交时显式指定编码参数并确保平台按此解析。如果平台不支持指定，那就得找对接人确认各通道的编码能力，做通道级的适配。这类问题排查起来最花时间，因为现象不连续，复现困难，只能靠加日志把每次请求的实际编码和通道标识记下来，攒够样本才能定位。
5.3 成本优化与容量规划的实操心得
短信是按条计费的，量大了成本很可观，优化空间主要在三个地方。
一是控制长度。前面说过70字一条，超了按67字拆。假设你的通知短信平均85字，每条要收2份钱，如果把文案压到68字以内，成本直接减半。压缩技巧不是删信息，是换表达：把"您的订单已经发货，预计三天内送达"改成"订单已发货，预计3日内送达"，少了一半字数信息量不减。这种文案打磨值得做，尤其是高频通知类。
二是合并发送。同一个用户短时间内收到多条通知，能不能合成一条发？这在电商、物流场景很常见。合并的前提是不影响用户理解，且有时间窗口。实现上可以在应用层做一个短的聚合窗口，比如5秒内同一用户的多条通知合成一条。这个优化的收益取决于你的业务形态，通知密集的业务能省不少。
三是名单质量。空号、停机号发出去一样计费（部分平台按提交计费而非按送达计费），所以名单清洗是纯赚的。定期用平台的号码状态检测能力筛一遍，把无效号码剔除。这项工作的投入产出比通常很高，尤其是历史积累的名单。
容量规划上，我习惯按峰值的三倍准备通道能力。峰值可能是日常的五到十倍，比如大促当天。临时扩通道要走申请流程，提前两周准备比较稳妥。另外别忘了余额，大促前把余额充到预估用量的1.5倍，因为大促期间充值流程也可能拥堵。
注意：余额告警的阈值不要设成固定金额，要设成"按最近七天日均用量计算的可支撑天数"。固定金额在你业务量增长后会失效，等到发现余额不足时已经晚了。
6. 一些长期维护上的经验
接口对接完不是结束，是一段长期关系的开始。平台侧的接口版本会升级，字段可能增减，返回码可能调整，这些变化通常通过公告或者对接人通知，但你未必每次都能及时看到。所以我建议做两个自检机制。
一个是契约自检。写一个定时任务，每天用固定的测试号码发一条测试短信，走完整链路，验证提交、回执、上行三个方向都正常。这条测试短信的成本一天几分钱，但能在平台侧发生变更时第一时间发现。任务要记录每次的耗时和返回码，形成一条趋势线，耗时突然上升往往预示着平台侧有变化。
另一个是文档对账。每隔几个月把代码里的字段和平台最新文档对一遍，看看有没有新增的必填字段或者废弃的字段。这件事很枯燥，但能避免某天接口突然大面积失败时手忙脚乱。我见过有团队因为平台新增了一个必填的模板版本号字段，导致所有模板短信失败，排查了半天才发现是文档更新了而代码没跟上。
还有一个经常被忽视的点：发送记录的保留周期。短信记录包含手机号和内容，属于个人信息范畴，保留时间不宜过长，按业务需要设一个期限，到期做脱敏或者删除。这件事在合规检查时会被问到，提前做好比事后补要省心得多。保留原始明文的需求通常是客服追溯，可以把追溯窗口设短一些，比如三个月，超出窗口的只保留统计信息不保留明细。
最后说一个心态上的事。短信这个渠道看起来古老，但它的可靠性要求和合规要求比很多新渠道都高，因为它直达用户且不可撤回。对接的时候多花点时间把边界情况想清楚，比上线后被动救火要划算。我自己的习惯是每接一个新平台，先花半天时间把所有返回码整理成表，把每个码对应的处理动作写进代码注释，后面不管是自己维护还是交接给别人，都能少走弯路。
