@logto/connector-tencent-sms 版本演进全解析:从 1.0.1 到 1.4.5 的功能迭代与底层实现

原创2026-10-10 21:05:331,938 阅读
文章标签:认证鉴权身份认证单点登录后端前端企业应用

@logto/connector-tencent-sms 版本演进全解析:从 1.0.1 到 1.4.5 的功能迭代与底层实现

本文以 Logto 官方腾讯云短信连接器 @logto/connector-tencent-sms 的 CHANGELOG.md 为主线,逐版本解读该连接器从 1.0.1 到 1.4.5 的完整演进路径:从构建工具切换、Node.js 运行时升级,到模板类型体系(TemplateType)的引入与默认配置补全。通过对照当前仓库中的 连接器源码 与 connector-kit 类型定义,读者可以理解每一次版本号变更背后的真实代码动因,并掌握当前版本(1.4.5)的配置结构、发送流程与 TC3 签名机制。

版本演进总览

@logto/connector-tencent-sms 是 Logto 官方维护的短信连接器,用于通过腾讯云短信服务(Tencent Cloud SMS)实现用户注册、登录、找回密码等场景的短信验证码下发。截至当前仓库,最新版本为 1.4.5。下表完整梳理了 CHANGELOG 记录的全部 14 个版本及其核心变更:

版本 变更类型 核心变更 依赖的 connector-kit 版本
1.4.5 Patch 无功能变更,仅依赖更新 5.1.1
1.4.4 Patch 无功能变更,仅依赖更新 5.1.0
1.4.3 Patch 无功能变更,仅依赖更新 5.0.1
1.4.2 Patch 无功能变更,仅依赖更新 5.0.0
1.4.1 Patch 无功能变更,仅依赖更新 4.7.0
1.4.0 Minor 新增功能:为模板 defaultValue 补全全部 usageType 4.6.0
1.3.1 Patch 无功能变更,仅依赖更新 4.4.0
1.3.0 Minor 运行环境:Node.js 版本要求提升至 ^22.14.0 4.3.0
1.2.1 Patch 安全:为安全更新升级依赖 4.1.1
1.2.0 Minor 工程化:改用 tsup 构建 无 connector-kit 变更
1.1.2 Patch 无功能变更,仅依赖更新 4.0.0
1.1.1 Patch 无功能变更,仅依赖更新 3.0.0
1.1.0 Minor 功能:支持 TemplateType;Node 20 LTS;TypeScript 5.3.3 2.1.0
1.0.1 Patch 无功能变更,仅依赖更新 2.0.0

从整体看,该连接器的版本演进可以划分为三条线索:功能能力扩展(模板类型体系)、运行环境升级(Node.js 版本)、工程构建优化(tsup 构建)以及贯穿始终的 connector-kit 依赖同步升级。

一、功能能力扩展:从 VerificationCodeType 到 TemplateType

1.1.0:引入 TemplateType 支持

CHANGELOG 中 1.1.0 版本记录了两项关键变更:

  • 570a4ea9e: support TemplateType
  • 9089dbf84: upgrade TypeScript to 5.3.3

这次变更的实质,是 Logto 在 @logto/connector-kit 层面重构了短信/邮件验证码的类型体系。在 passwordless.ts 中可以同时看到新旧两套定义:

  • 旧的 VerificationCodeType 枚举仅包含 SignIn、Register、ForgotPassword、Generic、UserPermissionValidation、BindNewIdentifier 与已弃用的 Test 七种取值,并被标记为 @deprecated;
  • 新的 TemplateType 枚举在保留前六种的基础上,新增了 OrganizationInvitation、MfaVerification、BindMfa 三种取值,覆盖了组织邀请、MFA 验证码下发与 MFA 绑定等更丰富的身份认证场景。

sendMessage 函数的数据类型也随之从旧的 VerificationCodeType 切换为 templateTypeGuard(基于 z.nativeEnum(TemplateType) 的 zod 校验器),详见 sendMessageDataGuard。这一变化意味着连接器内部通过 usageType 匹配模板的逻辑(templates.find(({ usageType }) => usageType === type))能够识别更多业务场景。

1.4.0:补全模板默认值中的全部 usageType

CHANGELOG 记录 1.4.0 为 Minor 变更:add full usage types to templates default value。这与 1.1.0 引入的 TemplateType 扩展形成闭环——当 Logto 控制台创建连接器时,constant.ts 中 formItems 的 templates 默认值会一次性给出全部 9 种 usageType 的模板占位:

SignIn、Register、ForgotPassword、OrganizationInvitation、Generic、
UserPermissionValidation、BindNewIdentifier、MfaVerification、BindMfa

这意味着新用户在控制台添加腾讯云短信连接器时,无需手动补全所有场景的模板条目,只需将每种 usageType 对应的 templateCode 替换为腾讯云控制台实际审核通过的模板代码即可。从 schema.ts 的校验逻辑来看,Register、SignIn、ForgotPassword、Generic 四种是必需的(缺失会在配置校验时报错),而组织邀请、MFA 等场景则按需配置。

二、运行环境升级:Node.js 版本要求的变化

CHANGELOG 中有两处与 Node.js 版本直接相关的记录:

  • 1.1.0:use Node 20 LTS for engine requirement,并注明"Logto 通过 Docker 镜像分发,这对用户并非破坏性变更";
  • 1.3.0:bump node version to ^22.14.0,将引擎要求进一步提升到 Node.js 22.14.0。

当前 package.json 的 engines 字段即为 "node": "^22.14.0",与 1.3.0 的变更保持一致。这意味着:

  • 以 npm/pnpm 源码方式本地开发或独立运行该连接器时,需要 Node.js ≥ 22.14.0;
  • 通过 Logto 官方 Docker 镜像使用则无需关心此限制,因为镜像内已内置满足要求的运行时。

三、工程构建优化:tsup 构建与安全依赖升级

1.2.0:改用 tsup 构建

CHANGELOG 记录 1.2.0 为 Minor 变更:

use tsup for building. We've updated some of the packages to use tsup for building. This will make the build process faster, and should not affect the functionality of the packages.

Logto 仓库根目录下的 tsup.shared.config.ts 定义了连接器包的通用构建配置:入口 src/index.ts、输出目录 lib、ESM 格式、启用 sourcemap 并开启 clean。连接器 package.json 中的 build 脚本即 tsup,产出物通过 main/module/exports 统一指向 ./lib/index.js,以 ESM 模块形式对外提供。这次变更纯属工程化改进,不改变连接器的对外行为,因此按语义化版本以 Minor 提升来"引起使用者注意"。

1.2.1:安全更新

1.2.1 是一次典型的安全维护版本:bump dependencies for security update,同步将 @logto/connector-kit 升级至 4.1.1。这类版本通常不包含功能变更,但建议生产环境及时跟进,以修复上游依赖中的已知安全漏洞。

四、当前版本(1.4.5)源码实现剖析

CHANGELOG 中的版本迭代最终沉淀在 1.4.5 的连接器实现中。下面结合源码逐层拆解其工作方式。

4.1 配置结构与校验(schema.ts)

连接器的配置通过 zod 校验器 SmsConfigGuard 定义,包含六个字段:

配置项 类型 必填 说明
accessKeyId string 是 腾讯云 API 密钥 ID
accessKeySecret string 是 腾讯云 API 密钥 Secret
signName string 是 短信签名名称,对所有模板生效
sdkAppId string 是 短信应用(SDK AppID)
region string 是 腾讯云短信 API 地域
templates Template[] 是 场景模板列表,必须覆盖 Register、SignIn、ForgotPassword、Generic

其中 templates 的每个元素由 usageType(枚举字符串)与 templateCode(模板代码)组成,且有一个容易踩坑的硬性约束:校验器通过 refine 强制要求 Register、SignIn、ForgotPassword、Generic 四种 usageType 必须全部出现在模板列表中,否则配置校验直接失败并提示缺失的 usageType。也就是说,即使你的产品只开放"手机号登录"场景,也必须为注册、忘记密码等场景至少补上模板条目(可以指向同一个腾讯云模板代码)。

4.2 发送消息主流程(index.ts)

核心入口是 sendMessage 函数,完整流程如下:

  1. 从调用方拿到 data(包含 to 手机号、type 场景类型、payload 载荷)与配置;
  2. 用 SmsConfigGuard 校验配置,随后按 usageType === type 从 templates 中查找匹配模板,找不到即抛出 TemplateNotFound 错误;
  3. 从 payload 中过滤掉 locale(语言标识不参与短信内容),将剩余参数值统一 String() 转为字符串数组——这是腾讯云短信 API 的硬性要求(index.ts);
  4. 调用 sendSmsRequest 发起 HTTP 请求;
  5. 对响应做双重校验:先判断是否为腾讯云错误响应(Response.Error 结构),再校验 SendStatusSet[0].Code 是否为 ok(大小写不敏感),任一异常都会包装为 ConnectorError 抛出,错误信息中携带 Code、Message 与 RequestId 便于排查。

值得注意的是,发送参数的组装逻辑(http.ts)中,TemplateParamSet 会按模板占位符顺序依次填入参数数组——这正是 README 中要求模板必须使用单一占位符 {1} 的原因:验证码场景只需一个动态参数,多占位符模板无法与 Logto 的载荷结构一一对应。

4.3 TC3-HMAC-SHA256 签名与请求封装(http.ts)

sendSmsRequest 实现了腾讯云 API 3.0(TC3)签名协议,这是连接器与腾讯云服务端通信的关键底层逻辑:

  • 请求端点固定为 sms.tencentcloudapi.com,动作(Action)为 SendSms,版本 2021-01-11;
  • 使用 UTC 日期构造 credentialScope(日期/sms/tc3_request),逐层计算 secretDate → secretService → secretSigning 的 HMAC-SHA256 链,最终得到签名值;
  • Authorization 头携带签名,请求头附带 X-TC-Action、X-TC-Timestamp、X-TC-Version、X-TC-Region;
  • 请求体为 JSON,包含 SmsSdkAppId、SignName、TemplateId、TemplateParamSet、PhoneNumberSet 五个字段。

该封装完全基于 Node.js 内置 node:crypto 实现,未依赖腾讯云官方 SDK,体现了 Logto 连接器"轻依赖、自实现协议"的设计取向。

4.4 测试验证(index.test.ts)

连接器的测试用例 index.test.ts mock 了 sendSmsRequest,验证了 sendMessage 的关键行为:当传入 type: TemplateType.SignIn 与 payload: { code, locale } 时,连接器会调用 sendSmsRequest 并将模板代码、参数数组(已剔除 locale)、手机号以及完整配置(region、sdkAppId、secretId、secretKey、signName)正确透传。结合 mock.ts 中覆盖四种必需 usageType 的 mock 配置,可以确认 4.1 节所述的四模板校验约束在实际运行中确实生效。

五、配置腾讯云短信连接器

在 Logto 控制台的"连接器"页面添加"腾讯云短信服务"(元数据定义见 constant.ts,表单字段与上文 schema 一致)后,配置步骤如下:

  1. 在腾讯云控制台"访问管理 → 访问密钥 → API 密钥"中生成 AccessKey ID 与 AccessKey Secret;
  2. 在短信控制台"应用管理"中获取 sdkAppId;
  3. 在"国内消息"或"国际/港澳台消息"中获取审核通过的签名名称(signName)与模板代码(templateCode),模板内容需包含单一占位符 {1};
  4. 在 region 中填写腾讯云短信 API 支持的地域(如 ap-guangzhou);
  5. 为 templates 数组中的每种 usageType 填入对应的 templateCode,确保 Register、SignIn、ForgotPassword、Generic 四种必填项齐全。

配置界面提供"发送测试"能力:输入手机号并点击发送,可在"保存并完成"之前验证全部配置是否打通。连接器启用后,还需要在 Logto 的登录体验(Sign-in Experience)中开启"手机号注册/登录",短信验证码流程才会真正对终端用户开放。

六、升级路径与维护建议

回顾完整 CHANGELOG,@logto/connector-tencent-sms 的升级策略非常清晰:

  • Patch 版本(如 1.2.1、1.3.1、1.4.1~1.4.5)几乎全部是 connector-kit 依赖的同步升级与安全修复,升级风险极低,建议跟随 Logto 主版本节奏自动更新;
  • Minor 版本中,1.1.0(TemplateType)与 1.4.0(模板默认值补全)直接影响了连接器配置的形态——升级后应检查 templates 配置是否覆盖新的 usageType 集合;1.2.0(tsup)与 1.3.0(Node 22)属于工程/运行时变更,源码方式部署时需保证 Node.js 版本满足 ^22.14.0 要求;
  • 若你的业务用到了组织邀请、MFA 验证码等场景,务必在升级后为对应 usageType 配置腾讯云模板,否则发送消息会命中 TemplateNotFound 错误。

从 1.0.1 到 1.4.5,这个连接器在保持对外"短信验证码下发"能力稳定的同时,通过类型体系扩展、构建优化与依赖治理逐步演化为 Logto 短信体系中的成熟组件。理解 CHANGELOG 背后这些源码级的变化,将帮助你在升级 Logto、排查短信问题时快速定位版本相关的行为差异。

登录后查看全文
logto