叶佳桐做了这么多年后端，我一直觉得短信验证码属于那种“看着简单、做起来全是坑”的功能。用户只看到“输入手机号→收到验证码→填进去成功登录”这一套流程，但站在开发者角度，你面对的是业务校验、厂商对接、模板签名、缓存策略、防刷、回调、幂等、重试、日志排查一整条链路。很多项目第一次做验证码功能时，会想当然地以为“不就是调一下短信接口吗”，结果一联调就发现各种莫名其妙的问题——要么发不出去，要么发重复，要么签名字段对不上，要么测试号码收到了一堆信息，线上却一条都发不出来。
这篇文章把我在实际系统中接入短信验证码的完整过程写透，从需求评估、服务商选型、接口结构设计，到验证码存取、回调处理、联调排障，再到上线后的监控要点，一条线串下来。适合正在做用户注册、登录、安全验证、消息通知的后端开发者和全栈工程师参考，也适合系统还没开始设计、正在评估方案的技术负责人。文章里的代码和思路我尽量用通用伪代码配合情景说明，你拿到自己项目里可以按同样逻辑落地，不一定非要照搬某个SDK。
1. 接验证码前先做的需求推演：短信不是“发出去”就完事
1.1 先从业务场景倒推技术需求
很多开发接到“接入短信验证码”时的第一反应是去翻短信服务商的开发文档，这顺序其实是反的。你首先要搞清楚验证码在系统里到底服务哪些场景，比如：用户注册时校验手机号真实可用、登录时做二次认证、找回密码时验证身份、敏感操作时做操作确认。不同场景对验证码频率、有效期甚至文案都可能有不同要求。
我当时接的这个项目，场景有四种：注册、登录、找回密码、修改绑定手机号。把业务场景列清楚后，才发现有两个被忽略的隐藏需求：
- 找回密码场景下，用户可能没有登录态，需要校验的是“手机号是否在系统内注册过”，没注册的要给出明确提示，而不是直接发验证码。
- 修改绑定手机号场景下，要给“新手机号+旧手机号”两条验证码流程，顺序一错就会出现安全隐患。
这些需求如果不提前梳理，直接开会发号施令“所有场景统一发验证码”，到测试阶段绝对会出幺蛾子。
1.2 把技术约束条件在动手前定下来
业务需求明确之后，马上要定一套技术约束参数。下面这几个指标如果在设计阶段不定清楚，代码写完了再改，成本会成倍增加：
- 验证码有效期：我后来定为5分钟。太短用户会急着输错，太长又不安全。你可以按业务调节，但一定要在配置中心或者常量里留扩展位。
- 同一手机号每日发送上限：一般建议10条左右，特殊活动可临时调白名单。
- 同一IP每小时发送上限：针对攻击者换手机号刷接口的情况，一个IP不能无限请求。
- 同一手机号发送间隔：通常定为60秒，避免用户手滑或恶意反复点击。
- 允许校验错误次数：验证码输入错误达到5次就作废，需要重新获取。
- 图形验证码前置：高频场景或风险时段前要加图片滑块验证，否则短信接口很容易被脚本刷爆，一天烧掉几百块。
这些约束不仅影响防御和费用控制，也直接影响你后面积分/Redis的key设计。如果一开始没想到这些，后面突然说“我们这个验证码老被刷”，那可就只能加班补墙了。
1.3 明确发送成功不等于送达，回调状态必须进设计
我见过不少项目把“短信SDK返回OK”当成“用户一定能收到”。这实际上是两个完全不同的含义。短信服务商返回SDK调用成功，只代表它接收了这条发送请求；最终用户能不能收到，还取决于运营商网关是否下发成功、手机有没有拦截、号码状态是否异常的。部分高质量的短信产品会提供状态回调报告，这个回调在正式项目里必须处理，至少要留一个接收和记录状态变更的接口，否则你排查“用户没收到验证码”只能靠猜，怎么猜都猜不准。
功能设计到这里，你就有了一张进代码前的整体蓝图：一个发送入口，多条业务校验规则，一套验证码存储结构，一个回调接收逻辑，外加一个能查询发送记录的兜底能力。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 服务商接入与账号初始化：AccessKey和模板签名那几道坎
2.1 选服务商不能只看单价，要看这五个硬指标
国内做短信的服务商很多，像阿里云、腾讯云、容联云、七牛之类，甚至还有一堆短信通道代理商。选型时不要只看每条短信几分钱，重点看下面五项：
- 到达率与稳定性：价格再便宜，发出去十条丢两条，验证码业务直接没法用，用户收不到验证码会反复点击，反而推高发送量。
- 审核能力与备案模板效率：服务商对新签名的审核是否及时，模板审核要不要人工介入。有的小服务商审核奇慢，你活动周五上线，模板周四还没过审，项目只能干等着。
- 是否提供状态回调：有的服务商不提供异步报告，你根本拿不到发送后的真实状态，排查问题难度很大。
- SDK和文档质量：文档乱、示例老、接口都不支持新版TLS的服务商，接入成本高到让你怀疑人生。
- 计费和套餐外扣费上限：一定设置好日/月预算限额告警，防止某天接口被刷导致报警甚至收到巨额账单。
我当时的选择落地是：如果有大厂账号就直接用成熟云厂商的短信服务，因为公司内已经有了统一云账号体系，审计和开发文档也都成体系；如果项目比较小众、预算有限也可以考虑专业短信服务商，但务必确认对方支持回调能力和高并发场景稳定度。
2.2 签名与模板的申请逻辑：被驳回大多是因为“看着就不像正规业务”
短信内容不是你想发什么就发什么。在服务商控制台需要先申请“短信签名”和“短信模板”，审核过了才能调用发送接口。签名一般是【XX科技】这种，模板则是“您的验证码为${code}，${minutes}分钟内有效，请勿泄露”。模板里的变量要用服务商指定的占位符，接口调用时再传入真实参数。
第一次做容易在这两个地方翻车：
- 签名被驳回：常