Quick SMS

让发送短信变得更简单——同时覆盖国内与国际，面向 SaaS 多租户。

多供应商短信聚合 SDK。不必再为每家厂商单独啃文档、写签名与 HTTP 工具；用统一的 SmsClient / SmsWebhookHandler 完成发信、回执、上行与状态查询。

• 版本：1.0.1
• 坐标：com.whaleal:sms-all
• GitHub：whaleal-dev/quick-sms
• 官网：whaleal.com
• 维护者：恒哥 · QQ 群：短信网关 1021755322

如果本项目帮到了你，欢迎 Star 支持。

---

为什么做 Quick SMS

日常开发里短信发送极其常见，但第三方短信服务商众多，各家协议、签名、模板规则不同。接入一家就要读一遍文档、写一遍工具类；换通道或做多租户时，凭证与回调又变成新的负担。

Quick SMS 的目标是：

• 统一 API：一行 sendText / sendTemplate 搞定常见场景
• 国内 + 国际：不止国内云厂商，也覆盖 Twilio、Vonage 等主流国际通道
• SaaS 友好：不强制 yml，凭证在调用时动态传入，适合多租户
• 网关级能力：回执 / 上行 / 状态查询 SPI、通道 failover、Webhook 安全、限流黑名单

📚 完整文档： 文档站 · 源码 docs-site/ · Markdown 速查 docs/

---

不想自己维护通道？用托管平台

Whaleal SMS 是同一套引擎的托管交付形态：把你在多家 CPaaS 的账号收进一个后台，向上暴露一套 HTTP API。

	Quick SMS（本仓库）	Whaleal SMS（平台）
形态	开源 SDK，嵌进你的进程	托管 SaaS，控制台 + HTTP API
聚合与路由	代码里配置 failover	控制台点选绑定，权重/优先级实时可调，不用发版
观测	自接 SmsMetrics	全渠道统一日志、报表、路由链可视化
资费	短信费付给你的 CPaaS	同上，平台不经手资费（BYOL，纯订阅不按条计费）

• 平台总览与选型：文档站 · Whaleal SMS 云平台
• 五步接入：接入方式总览 · 控制台各页说明：控制台使用指南
• 开放 API：接口参考 · 基址 https://smsapi.whaleal.com/open/v1
• 已上线与规划中的能力：能力路线图

平台是叠加的管理层，不是 CPaaS 替代品：不售卖短信、不经手资费、不承诺送达、不改变底层链路。你的供应商合同、号码与资费全部保留。

---

特性一览

能力	说明
多厂商聚合	国内约 24 家 + 国际约 9 家，SPI 扩展
快捷发信	sendText / sendTemplate 一行发送
按通道内容	contentByProvider / templateIdByProvider（参考 easy-sms）
动态凭证	请求级 SmsCredentials，秘钥不落盘
通道容灾	顺序 / 随机 failover
回执 · 上行 · 查状态	统一 Webhook 门面 + 各厂商 Parser/Fetcher
安全与治理	Webhook 签名防重放、黑名单、限流、HTTP 代理
可观测性	内置 MetricsCollector；可选 Micrometer（sms.send）
模块可选	starter 不带厂商 jar；sms-all 一键全量

---

支持厂商一览

国内（sms-providers-cn）

厂商	枚举 / code
阿里云	ALIYUN / aliyun
腾讯云	TENCENT / tencent
华为云	HUAWEI / huawei
云片	YUNPIAN / yunpian
创蓝 / 253	CHUANGLAN / chuanglan
容联云	CLOOPEN / cloopen
七牛云	QINIU / qiniu
螺丝帽	LUOSIMAO / luosimao
SUBMAIL	SUBMAIL / submail
天翼云	CTYUN / ctyun
网易云信	NETEASE / netease
百度云	BAIDU / baidu
助通	ZHUTONG / zhutong
短信宝	SMSBAO / smsbao
互亿无线	HUYI / huyi
聚合数据	JUHE / juhe
云之讯	YUNZHIXUN / yunzhixun
SendCloud	SENDCLOUD / sendcloud
华信	HUAXIN / huaxin
火山引擎	VOLCENGINE / volcengine
中国移动 / 电信 / 联通	CHINA_*
自定义 HTTP	CUSTOM_HTTP
Mock（本地）	MOCK

国际（sms-providers-intl）

厂商	枚举
Twilio	TWILIO
Vonage	VONAGE
MessageBird	MESSAGEBIRD
Plivo	PLIVO
Infobip	INFOBIP
Amazon SNS	AWS
阿里云国际	ALIYUN_INTERNATIONAL
腾讯云国际	TENCENT_INTERNATIONAL
华为云国际	HUAWEI_INTERNATIONAL

凭证字段、模板 vs 内容、回调样例见 厂商接入说明。

---

30 秒上手

Maven 引入依赖

坐标：com.whaleal:sms-all:<version>（Java 包名仍为 com.whaleal...，不变）。

发到 Maven Central 后，只需依赖（无需 <repositories>、无需 settings.xml）：

<!-- 推荐：国内 + 国际全量 -->
<dependency>
  <groupId>com.whaleal</groupId>
  <artifactId>sms-all</artifactId>
    <version>1.0.1</version>
</dependency>

或按需：sms-spring-boot-starter + sms-providers-cn / sms-providers-intl。

推送分支 release-x.y.z 会自动发布到 Maven Central。查版本：Central Search · 发布说明见 CI / CD。

本地开发：源码 mvn install

git clone https://github.com/whaleal-dev/quick-sms.git
cd quick-sms
mvn clean install -DskipTests

业务项目直接依赖 com.whaleal:sms-all:1.0.1（与根 pom 版本一致）即可。需 JDK 21。

纯 Java（无需 yml）

SmsClient client = SmsClients.builder()
        .provider(SmsProviderType.YUNPIAN)
        .build();

SmsSendResult result = client.sendText(
        "13800138000",
        "【签名】您的验证码是 1234",
        SmsCredentials.builder().apiKey("your-apikey").build());

System.out.println(result.isSuccess() + " " + result.getMessageId());

Spring Boot

@RestController
@RequiredArgsConstructor
public class SmsController {
    private final SmsClient smsClient; // 默认 MOCK，可自定义 @Bean

    @PostMapping("/send")
    public SmsSendResult send(@RequestParam String phone) {
        return smsClient.sendText(phone, "【QuickSMS】hello",
                SmsCredentials.builder().apiKey("your-apikey").build());
    }
}

设计约定： Quick SMS 不强制 yml，凭证在代码 / 请求中传入，更适合多租户与配置中心。

更多步骤：

• Spring Boot 集成
• JavaSE / 纯 Java 集成
• 进阶能力
• API 详解

---

模块结构

quick-sms/
├── sms-api                 # 门面、SPI、DTO、枚举
├── sms-core                # SPI 加载、签名/指标/策略工具
├── sms-runtime             # 适配器、Mock、SmsClients
├── sms-providers-cn        # 国内厂商
├── sms-providers-intl      # 国际厂商
├── sms-spring-boot-starter # 自动配置（不带厂商）
├── sms-all                 # starter + cn + intl
├── docs-site/              # Docusaurus 文档站（GitHub Pages）
├── docs/                   # Markdown 速查（与文档站内容互补）
└── examples/               # 示例代码

场景	依赖
只要国内	starter + sms-providers-cn
只要国际	starter + sms-providers-intl
全量网关	sms-all
纯 Java	sms-runtime + 所需 providers

---

文档导航

公开站点：https://whaleal.com/quick-sms/（出站 / 入站 / Report / Webhook 等概念见「短信概念」）。

文档	内容
前言	设计理念与适用场景
Spring Boot 快速开始	依赖、Bean、发信、Webhook Controller
JavaSE 快速开始	Builder、无 Spring 用法
进阶配置	Failover、限流、安全、指标、代理
API 详解	核心类型与错误码
厂商接入	各厂商凭证与回调
CI / CD	自动构建与发布到 Maven Central
文档站维护	本地预览与 Pages 发布
示例	可复制代码
变更记录	版本说明

---

构建

mvn clean test package

Java 21 · Spring Boot 3.4.x

---

社区交流

群名称	群号
短信网关	1021755322

扫一扫加入群聊

---

仓库与发布

源码仓库： github.com/whaleal-dev/quick-sms

完整流程见 CI / CD 说明。

场景	触发	Workflow	Secrets
构建测试	PR / push main、release-*	ci.yml	无
发布 Maven Central	分支 release-*	publish-maven-central.yml	见下

git checkout -b release-1.0.1 && git push -u origin release-1.0.1

需配置 Secrets：MAVEN_CENTRAL_USERNAME、MAVEN_CENTRAL_PASSWORD、MAVEN_GPG_PRIVATE_KEY、MAVEN_GPG_PASSPHRASE。命名空间须为 com.whaleal。

消费方引入方式见 Maven 引入依赖。

---

贡献与规范

协作、作者、PR 见工作区 conventions/。

维护者：恒哥 [恒哥]

许可证

Copyright © 2026 whaleal-dev · whaleal.com

基于 Apache License 2.0 发布。