邮件、验证码与第三方服务接口集成

生成并消费一次性验证码,准备邮件发送,并限制外部接口的等待时间

🎯 引言

学完这篇文章,你能通过邮件服务发送验证码,并为验证码验证与外部接口调用设置期限和失败处理。

✉️ 配置邮件发送服务

Node.js 可以使用 Nodemailer 发送邮件。它连接邮件服务商提供的 SMTP 服务,SMTP 是应用提交邮件的协议。

安装本节需要的依赖:

npm install nodemailer@10.2.1

先从已开通的邮件服务获取 SMTP 主机、账号、密码和允许的发件地址,保存为环境变量。新建 mail.mjs:

mail.mjs
import nodemailer from 'nodemailer';

export const mailer = nodemailer.createTransport({
    host: process.env.SMTP_HOST,
    port: 465,
    secure: true,
    auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASSWORD },
    connectionTimeout: 5000,
    socketTimeout: 10000
});

host 指邮件服务器,auth 用于登录邮件服务。465 配合 secure: true 建立加密连接;如果服务商要求其他端口,按其配置设置。两个 timeout 分别限制建立连接和套接字空闲等待时间,避免服务故障时无限等待。


🔢 生成一次性验证码

服务端通过安全随机数生成六位验证码:

send-code.mjs
import { randomInt } from 'node:crypto';
import { mailer } from './mail.mjs';

const code = String(randomInt(0, 1_000_000)).padStart(6, '0');

结果是六位数字字符串,可能以 0 开头,因此以字符串保存和比较。它只用于这次身份验证,不写入日志,也不通过申请验证码的 HTTP 响应返回给客户端。


📤 通过邮件发送

在 send-code.mjs 继续添加:

send-code.mjs
const result = await mailer.sendMail({
    from: process.env.MAIL_FROM,
    to: process.env.MAIL_TO,
    subject: '登录验证码',
    text: `你的验证码是 ${code},5 分钟内有效。`
});
console.log(result.messageId);

MAIL_FROM 是服务商允许的发件地址,MAIL_TO 是这次练习的收件地址。运行 node --env-file=.env send-code.mjs 会实际发送邮件;成功后终端显示邮件编号。

返回编号表示服务接受了提交,不保证邮件已进入收件箱。被拒绝、退信或垃圾邮件分类还需要查看服务商的投递结果。正式接口要校验收件地址、限制发送频率,不能公开提供任意收件人发送能力。


🗃 验证码必须与服务端记录对应

正式验证码接口需要在发送前保存验证记录。数据库或共享缓存记录以下信息:

信息用途示例规则
接收邮箱将验证码绑定到接收者只验证这次申请的邮箱
用途区分登录和重置密码登录码不能用于重置
校验值验证提交内容保存带服务端秘密密钥的校验值,避免明文保存
到期时间拒绝过期码5 分钟后过期
尝试次数限制猜测累计 5 次错误后失效
已使用状态避免重复登录成功后立即失效

六位码组合有限,除了单码尝试次数,还应按邮箱和请求来源限流。普通摘要在记录泄露后容易被穷举,因此校验值需要服务端秘密参与计算,密钥与记录分开管理。


✅ 验证接口怎样返回结果

客户端提交邮箱、验证码和约定的用途,例如登录接口:

POST /auth/code-login HTTP/1.1
Content-Type: application/json

{"email":"reader@example.com","code":"123456"}

服务端查对应记录,检查用途、期限、次数,再验证校验值。全部通过后作废这份验证码,创建登录会话并返回成功;不通过则返回统一的“验证码无效或已过期”,不透露邮箱是否注册。

检查和作废必须一起完成,避免两个并发请求都使用成功。可以用数据库事务或缓存提供的原子操作实现;使用认证服务提供的验证码能力时,调用它的发送和校验接口,由服务管理这些状态。

前面的发送脚本只完成邮件投递,正式登录接口还需要按这里的规则保存并消费记录。


🌐 外部 HTTP 请求设置超时

调用第三方接口时,固定服务端允许的地址。下面调用路由篇的本机健康接口,便于验证成功和失败:

health-client.mjs
const response = await fetch('http://127.0.0.1:3000/health', {
    signal: AbortSignal.timeout(1000),
    redirect: 'error'
});
if (!response.ok) throw new Error('外部接口返回失败');
const data = await response.json();
if (data.status !== 'ok') throw new Error('外部响应格式不符合约定');
console.log(data.status);

先运行 routing-server.mjs,再运行 node health-client.mjs,应输出 ok。停止服务后请求会失败;超过一秒仍未完成时会取消等待。不要把客户端提交的任意 URL 直接作为服务端请求目标。


🛑 超时后不要盲目重试

超时只说明没有及时收到结果,对方可能已经发送邮件或创建记录。需要修改外部状态的调用,应使用服务商支持的请求标识或幂等机制,确认重试不会重复执行。

接入 Webhook,也就是第三方主动通知你的接口时,按对方协议验证签名并记录事件 ID。同一个已处理通知再次到达,可以确认接收,但不重复执行业务。


❓ 知识问答

Q1:邮件成功提交就可以向用户承诺已送达吗?

不可以,还需根据投递结果判断;页面可提示“已提交发送,请检查收件箱”。

Q2:发送失败后原来的验证码怎么办?

应撤销未能正常交付的申请或按统一重试策略处理,避免不断产生互相覆盖的有效记录。

Q3:验证码只检查相等够吗?

还要检查接收者、用途、期限、尝试次数和是否已使用。


🧪 小练习

先验证本机健康接口成功与停止后的失败;使用自己的测试邮箱完成邮件投递,并记录服务接受与实际收到的区别。

// 请在这里记录结果