企业官网建设流程全解析

1. 短信接口对接前必须想清楚的几件事

短信发送这个功能，看起来只是调一个接口的事，但真正在项目里落地过的人都知道，坑远比想象中多。我见过不少团队，代码半天就写完了，结果上线之后被各种问题折腾了一两周——签名审核没过、模板变量对不上、手机号格式校验漏了、并发上来之后连接池爆了。所以这篇内容我不打算一上来就贴代码，而是先把对接短信服务之前必须想明白的几个问题讲透，这样后面写代码的时候你才知道每一行是在解决什么问题。

短信服务本质上是一个典型的"第三方API调用"场景：你的系统作为客户端，通过HTTP协议向服务商的网关发起请求，网关校验身份、校验签名和模板、校验手机号，然后投递给运营商，运营商再下发到用户手机。整条链路上任何一环出问题，用户就收不到短信。而作为调用方，我们能控制的只有"请求构造"和"结果处理"这两段，所以核心工作就是把这两段做扎实。

适合阅读这篇内容的人，我大致分三类：第一类是做Java后端开发，第一次接触短信发送功能，需要一份能直接跑通的参考实现；第二类是老手，之前发过短信但没系统整理过，想看看有没有遗漏的边界情况；第三类是负责技术选型的人，需要了解对接短信服务时有哪些关键决策点。不管你是哪一类，我都建议按顺序读，因为后面的代码实现是建立在前面的设计决策之上的。

还有一个前提要说明：短信服务商有很多家，接口协议大同小异，但参数命名、签名算法、返回结构会有差异。这篇内容以通用的短信发送流程为主线，具体到某个平台的SDK时，思路是完全一致的，你只需要替换掉对应的参数名和签名计算方式即可。我在实际项目里对接过不止一家服务商，切换的时候发现真正需要改的代码其实很少，关键是把抽象层设计好。

2. 短信发送的完整链路与核心概念拆解

2.1 从调用到送达，中间到底经过了什么

很多人以为调了接口短信就发出去了，其实从你的代码到用户手机，中间至少经过四个环节。第一个环节是你的应用构造请求，把手机号、签名、模板编号、模板参数这些信息组装成一个HTTP请求。第二个环节是短信服务商的网关接收请求，做身份认证——通常是通过AccessKey和签名机制来确认"你是谁"。第三个环节是网关做业务校验，包括签名是否已审核通过、模板是否已报备、模板参数是否和模板定义匹配、手机号是否在黑名单里、账户余额是否充足。第四个环节才是提交给运营商通道，由运营商完成实际下发。

理解这个链路的意义在于：当短信发不出去的时候，你能快速定位是哪一环出了问题。比如返回"签名不合法"，那问题在第三环的签名校验；返回"模板参数不匹配"，那是模板变量数量或格式对不上；如果接口返回成功但用户没收到，那大概率是运营商通道的问题，这时候你找服务商客服比改代码有用得多。

2.2 签名、模板、AccessKey这三个东西分别是什么

签名是短信内容开头那个方括号里的东西，比如【某某科技】。它不是随便写的，需要提前在服务商后台提交审核，审核通过后才能使用。签名的本质是告诉用户"这条短信是谁发的"，同时也是运营商做内容合规管理的手段。个人开发者经常卡在这一步，因为签名审核通常需要提供资质证明，个人认证的账户能申请的签名类型比较有限。

模板是短信正文的固定格式，比如"您的验证码是${code}，5分钟内有效。"模板也需要提前报备审核。为什么要用模板而不是直接发任意内容？因为运营商对短信内容有严格的合规要求，模板机制是为了防止垃圾短信和诈骗短信。模板里的变量用占位符表示，调用时传入实际值替换。这里有个容易踩的坑：模板中变量的数量和顺序必须和代码里传的完全一致，多一个少一个都会报错。

AccessKey是你的身份凭证，由AccessKeyId和AccessKeySecret两部分组成。Id相当于用户名，Secret相当于密码，但Secret不直接参与传输，而是用来计算请求签名。这里的安全原则很简单：AccessKeySecret绝对不能硬编码在客户端代码里，也不能提交到代码仓库。我见过有团队把Secret写在Android客户端里，结果被人反编译出来盗刷短信，一晚上损失了好几千块。

2.3 为什么短信接口的签名机制这么设计

短信接口的签名机制，本质上解决的是"如何在不传输密码的前提下证明身份"这个问题。如果每次请求都直接把AccessKeySecret放在参数里传过去，一旦请求被截获，密钥就泄露了。所以主流服务商采用的都是HMAC签名方案：用Secret对请求参数做一次哈希运算，把结果作为签名参数传过去，服务端用同样的Secret做同样的运算，比对结果是否一致。

这个方案的安全性依赖于两点：一是Secret本身不传输，二是签名和具体请求参数绑定，参数被篡改签名就对不上。所以你在实现签名逻辑的时候，参数拼接的顺序、编码方式、大小写都必须严格按照文档来，差一个字符签名就会失败。这也是为什么很多人第一次对接时总是报"签名错误"——不是密钥错了，而是参数拼接的细节没对上。

3. 环境准备与依赖选型：别在第一步就埋雷

3.1 HTTP客户端的选择与理由

Java生态里发HTTP请求的方案很多，从最原始的HttpURLConnection，到Apache HttpClient，再到OkHttp，还有Spring的RestTemplate和WebClient。对接短信接口这种场景，我的建议是优先用服务商官方提供的SDK，因为SDK已经把签名计算、参数编码、重试逻辑这些容易出错的细节封装好了。如果服务商没有Java SDK，或者你想自己控制得更精细，那就用Apache HttpClient或者OkHttp。

为什么不推荐HttpURLConnection？因为它太底层了，连接池、超时、重试这些都要自己管，代码写出来又长又容易漏。为什么不推荐RestTemplate？因为它默认的底层实现经常变，不同Spring Boot版本行为不一致，而且对连接池的配置不够直观。OkHttp的优势是API简洁、连接池管理成熟、超时控制清晰，适合中小规模调用。Apache HttpClient的优势是配置项丰富、社区资料多，适合需要精细调优的场景。

3.2 Maven依赖与版本注意事项

如果你选择用官方SDK，通常只需要引入一个依赖。以通用的短信SDK为例，依赖大概长这样：

<dependency> <groupId>com.example.sms</groupId> <artifactId>sms-sdk-java</artifactId> <version>2.0.0</version> </dependency>

如果你选择自己实现，用OkHttp的话：

<dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency>

这里有个版本坑要提醒：OkHttp 4.x要求Kotlin运行时，如果你的项目是纯Java且不想引入Kotlin依赖，可以用3.14.x版本，功能上完全够用。另外，如果你的项目里已经有其他组件依赖了不同版本的OkHttp，注意用mvn dependency:tree检查一下有没有版本冲突，冲突的表现通常是运行时抛NoSuchMethodError。

3.3 配置项该怎么管理

短信相关的配置至少包括：AccessKeyId、AccessKeySecret、签名名称、模板编号、区域节点（如果有）。这些配置的管理原则是：敏感信息走环境变量或配置中心，非敏感信息走配置文件。AccessKeySecret属于敏感信息，绝对不能写在application.yml里提交到仓库。

我通常的做法是在配置文件里只写占位符，实际值通过环境变量注入：

sms: access-key-id: ${SMS_ACCESS_KEY_ID} access-key-secret: ${SMS_ACCESS_KEY_SECRET} sign-name: 某某科技 template-code: SMS_123456789 region-id: cn-hangzhou

然后在部署脚本或容器编排配置里设置对应的环境变量。这样代码仓库里看不到任何密钥，不同环境（开发、测试、生产）用不同的密钥也不会冲突。如果你用的是配置中心，那就把密钥存在配置中心的加密配置里，效果是一样的。

4. 核心代码实现：从请求构造到结果解析

4.1 请求参数的完整构造过程

短信发送请求的参数可以分为四类：身份类（AccessKeyId）、签名类（Signature、SignatureMethod、SignatureNonce、Timestamp）、业务类（PhoneNumbers、SignName、TemplateCode、TemplateParam）、格式类（Format、Version、Action）。每一类都有它的作用，缺一不可。

身份类告诉服务端你是谁。签名类用来证明这个请求确实是你发的，其中SignatureNonce是一个随机字符串，用来防止重放攻击；Timestamp是请求时间，服务端会校验它和服务器时间的偏差，通常允许15分钟以内。业务类就是短信的具体内容。格式类指定返回格式和API版本。

构造请求的时候，参数拼接顺序很关键。以常见的签名算法为例，需要先把所有公共参数和业务参数按参数名的字典序排序，然后拼接成key=value&key=value的形式，再用AccessKeySecret做HMAC-SHA1运算。这里最容易出错的地方是：参数值必须做URL编码，而且编码方式要和服务端一致（通常是RFC 3986）。我踩过的坑是用了Java默认的URLEncoder，它会把空格编码成+而不是%20，导致签名对不上。

// 参数排序与拼接的核心逻辑 Map<String, String> params = new TreeMap<>(); params.put("AccessKeyId", accessKeyId); params.put("Action", "SendSms"); params.put("Format", "JSON"); params.put("PhoneNumbers", phone); params.put("SignName", signName); params.put("SignatureMethod", "HMAC-SHA1"); params.put("SignatureNonce", UUID.randomUUID().toString()); params.put("SignatureVersion", "1.0"); params.put("TemplateCode", templateCode); params.put("TemplateParam", templateParam); params.put("Timestamp", getTimestamp()); params.put("Version", "2017-05-25"); // 构造待签名字符串 StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : params.entrySet()) { sb.append(percentEncode(entry.getKey())) .append("=") .append(percentEncode(entry.getValue())) .append("&"); } String stringToSign = "GET&" + percentEncode("/") + "&" + percentEncode(sb.substring(0, sb.length() - 1));

4.2 签名计算的每一步在做什么

签名计算是整个对接过程中最核心也最容易出错的部分。我把每一步拆开讲。第一步，构造规范化请求字符串，也就是把所有参数按字典序排好、编码好、拼起来。第二步，构造待签名字符串，格式是HTTPMethod&编码后的路径&编码后的参数串。第三步，用AccessKeySecret加上一个&作为密钥，对待签名字符串做HMAC-SHA1运算。第四步，把运算结果做Base64编码，得到最终的Signature。

为什么要加那个&？这是HMAC-SHA1的标准用法，密钥后面补一个&是为了和某些实现保持一致。为什么用HMAC-SHA1而不是直接SHA1？因为HMAC引入了密钥，没有密钥的人无法伪造签名。为什么最后要Base64？因为HMAC的输出是二进制，直接放在URL里会有编码问题，Base64之后就是可打印字符了。

private String percentEncode(String value) throws UnsupportedEncodingException { return value == null ? null : URLEncoder.encode(value, "UTF-8") .replace("+", "%20") .replace("*", "%2A") .replace("%7E", "~"); } private String sign(String stringToSign, String accessKeySecret) throws Exception { Mac mac = Mac.getInstance("HmacSHA1"); mac.init(new SecretKeySpec((accessKeySecret + "&").getBytes("UTF-8"), "HmacSHA1")); byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8")); return Base64.encodeBase64String(signData); }

4.3 发送请求与超时设置

签名算好之后，把Signature也加到参数里，然后发起HTTP请求。这里的关键是超时设置。短信接口的超时不能设太长，因为用户等验证码是有耐心上限的，通常3到5秒没收到就会点重发。所以连接超时设2秒，读取超时设3秒比较合理。如果服务商响应慢，宁可快速失败让用户重试，也不要让请求挂在那里。

OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(2, TimeUnit.SECONDS) .readTimeout(3, TimeUnit.SECONDS) .build(); HttpUrl url = HttpUrl.parse("https://sms.example.com/") .newBuilder() .addQueryParameter("AccessKeyId", accessKeyId) // ... 其他参数 .addQueryParameter("Signature", signature) .build(); Request request = new Request.Builder().url(url).get().build(); try (Response response = client.newCall(request).execute()) { String body = response.body().string(); // 解析返回结果 }

4.4 返回结果的解析与错误码处理

短信接口的返回通常是JSON格式，包含Code、Message、RequestId、BizId这几个字段。Code为"OK"表示成功，其他值都是失败。BizId是这次发送的回执ID，可以用来查询发送状态。这里要特别注意：接口返回成功不代表用户一定收到，只代表服务商已经受理了。真正的送达状态需要通过回执查询接口或者等回执推送。

错误码的处理策略要分两类：一类是可重试的错误，比如系统繁忙、网络超时，这类可以自动重试；另一类是不可重试的错误，比如签名不合法、模板不存在、手机号格式错误，这类重试多少次都没用，应该直接返回给调用方。我见过有代码对所有错误都无脑重试三次，结果因为签名错误重试了三次，白白浪费了时间和配额。

JSONObject result = JSON.parseObject(body); String code = result.getString("Code"); if ("OK".equals(code)) { String bizId = result.getString("BizId"); return SendResult.success(bizId); } else if (isRetryable(code)) { return SendResult.retryable(result.getString("Message")); } else { return SendResult.fail(code, result.getString("Message")); }

5. 那些文档里不会写的踩坑记录

5.1 签名总是失败？先检查这三个地方

签名失败是对接短信接口时最高频的问题，没有之一。我排查过的案例里，90%以上是以下三个原因之一。第一个原因是参数编码不一致，尤其是空格和特殊字符的处理。Java的URLEncoder默认把空格编码成+，但签名算法要求的是%20，这个差异会导致签名完全对不上。第二个原因是时间戳偏差过大，服务端通常允许15分钟的偏差，如果你的服务器时间没同步，请求会被直接拒绝。第三个原因是参数拼接顺序，必须严格按字典序，TreeMap可以帮你自动排序，但如果你用的是HashMap那就没保证了。

排查方法很简单：把待签名字符串打印出来，和服务商提供的签名示例对比。如果字符串完全一致但签名还是不对，那就是密钥的问题；如果字符串不一致，那就是参数构造的问题。我建议在开发阶段把待签名字符串和最终签名都打到日志里，上线前再关掉。

5.2 模板参数格式的隐藏要求

模板参数的格式要求，文档里通常只写"JSON格式"，但实际使用中有很多隐藏要求。首先，参数值必须是字符串类型，即使你的验证码是数字，也要用引号包起来，写成{"code":"1234"}而不是{"code":1234}。其次，参数名必须和模板里定义的变量名完全一致，大小写敏感。第三，如果模板里有多个变量，JSON里的键值对数量必须和模板变量数量一致，不能多也不能少。

还有一个坑是特殊字符转义。如果你的模板参数里包含引号、反斜杠这些字符，JSON序列化的时候要正确处理，否则服务端解析会失败。用成熟的JSON库（比如Fastjson、Jackson）序列化就没问题，手动拼字符串迟早出事。

5.3 手机号格式校验不能只靠正则

手机号校验看起来简单，但实际项目里要考虑的情况不少。国内手机号是11位，但用户输入的时候可能带空格、带横线、带+86前缀。所以第一步是清洗，把非数字字符去掉，把+86或86前缀去掉。第二步才是用正则校验格式。但即使格式正确，也不代表这个号码能收到短信——空号、停机、黑名单号码都会发送失败。

我的建议是：客户端做基础格式校验，服务端做严格校验，但不要把校验失败当成异常抛给用户，而是给出明确的提示。另外，发送频率要做限制，同一个手机号一分钟内只能发一条，一小时内不超过五条，这是防止被恶意刷短信的基本手段。

5.4 并发场景下的连接池与限流

单条短信发送的代码跑通之后，很多人就直接上线了，结果一到高峰期就出问题。最常见的问题是连接池耗尽。OkHttp默认的连接池是5个空闲连接，如果你的并发量比较大，请求会排队等待。解决办法是适当调大连接池，同时设置合理的超时，避免请求堆积。

OkHttpClient client = new OkHttpClient.Builder() .connectionPool(new ConnectionPool(20, 5, TimeUnit.MINUTES)) .connectTimeout(2, TimeUnit.SECONDS) .readTimeout(3, TimeUnit.SECONDS) .build();

另一个问题是服务商的QPS限制。大多数短信服务商对单个账户有每秒请求数限制，超过就会被限流。所以你的代码里要有令牌桶或者信号量做本地限流，把并发控制在服务商允许的范围内。我通常用Guava的RateLimiter，简单几行代码就能搞定。

6. 从能用到好用：可靠性设计的几个关键点

6.1 重试策略：什么该重试，什么不该重试

重试是提高短信发送成功率的重要手段，但前提是重试对错误类型。我的分类是这样的：网络超时、连接被拒、服务端5xx错误，这些可以重试；签名错误、模板错误、手机号格式错误、余额不足，这些重试没有意义。重试次数建议2到3次，每次间隔递增，比如第一次等1秒，第二次等2秒，避免瞬间大量重试把服务商打挂。

还有一个细节：重试的时候要重新生成SignatureNonce和Timestamp，因为这两个参数是一次性的，重复使用会被服务端拒绝。这一点很多人会忽略，导致重试全部失败。

6.2 异步发送与结果回调

同步发送短信会阻塞调用线程，在高并发场景下不可取。更好的做法是把发送任务丢到线程池或者消息队列里异步执行，调用方立即返回。但异步之后，发送结果怎么通知调用方？两种方案：一种是回调，发送完成后调用预先注册的回调函数；另一种是轮询，调用方拿一个任务ID去查询结果。回调的实时性好但实现复杂，轮询简单但有延迟。验证码场景通常用同步发送就够了，因为用户就在等；营销短信场景适合异步，因为不要求实时性。

6.3 日志与监控：出问题时怎么快速定位

短信发送的日志要记录这些信息：请求时间、手机号（脱敏后）、模板编号、返回码、BizId、耗时。手机号脱敏是必须的，比如只保留前三位和后四位。日志的作用是出问题时能快速定位：是某个模板集中失败，还是某个时间段集中失败，还是某个手机号段集中失败。

监控方面，至少要监控发送成功率和平均耗时。成功率突然下降通常意味着服务商侧有问题或者你的账户被限流了。平均耗时突然上升可能是网络问题或者服务商响应变慢。这些指标配合告警，能在用户投诉之前发现问题。

7. 上线前的检查清单与个人经验

上线之前，我通常会过一遍这个清单：AccessKeySecret是否已经改成环境变量注入、签名和模板是否已经审核通过、手机号校验和频率限制是否已经加上、超时和重试策略是否已经配置、日志是否已经脱敏、监控告警是否已经接入。这个清单看起来简单，但每一条都是踩过坑之后总结出来的。

我个人在实际操作中的体会是，短信功能的技术难度不高，但细节特别多，而且很多细节只有在真实流量下才会暴露。所以我的建议是：开发阶段用测试签名和测试模板跑通流程，上线前用小流量灰度验证，确认没问题再全量。另外，一定要和服务商的技术支持建立联系，遇到返回码看不懂的时候，直接问比查文档快得多。

最后分享一个小技巧：把短信发送封装成一个独立的服务，对外只暴露一个send(phone, templateCode, params)的方法，内部处理签名、重试、限流、日志、监控所有细节。这样业务代码调用起来就一行，后续换服务商或者调整策略也只需要改这一个服务，不会影响到业务层。这个封装思路我在多个项目里用过，效果很稳。