CAS 集成 Mailjet 发送通知邮件:配置、原理与实战
CAS 集成 Mailjet 发送通知邮件:配置、原理与实战
CAS(Apereo CAS)默认通过 SMTP 服务器发送各类通知邮件(如密码重置链接、MFA 令牌、风险登录告警等),但在某些部署场景下,直接使用云邮件服务可以省去自建 SMTP 的运维负担。本文以仓库 Sending-Email-Configuration-Mailjet.md 为主体,结合 cas-server-support-mailjet 模块源码,完整讲解如何让 CAS 改用 Mailjet 发送邮件:从模块引入、参数配置、邮件内容构建到底层调用链与沙箱验证,帮助读者快速落地一套可运行的 Mailjet 邮件通道。
为什么用 Mailjet 替代 SMTP
CAS 的邮件通知能力默认构建在 Spring 的 JavaMailSender(SMTP)之上,需要自行维护 SMTP 主机、端口、账号与 TLS 配置。而 Mailjet 是面向开发者的邮件发送服务,提供 HTTP API 与 SDK 客户端。接入 Mailjet 后,CAS 不再需要配置任何 SMTP 服务器信息,仅需在配置中声明 Mailjet 的 API Key 与 Secret Key,即可通过其事务性邮件接口(Transactional Email API)完成邮件投递,并额外获得点击/打开跟踪(Track Clicks / Track Opens)、模板语言、错误报告等能力。
从源码看,该集成模块同时覆盖了两条通道:
- 邮件通道:配置前缀
cas.email-provider.mailjet.*; - SMS 通道:配置前缀
cas.sms-provider.mailjet.*(同一模块内置,详见 SMS-Messaging-Configuration-Mailjet.md)。
本文聚焦邮件通道,SMS 通道仅在末尾简要说明。
第一步:引入 Mailjet 支持模块
Mailjet 支持由 CAS 模块 cas-server-support-mailjet 提供。使用 WAR Overlay 部署时,在 build.gradle 的依赖中引入:
implementation "org.apereo.cas:cas-server-support-mailjet:${projectVersion}"
模块的描述信息(build.gradle)明确其职责为 “Sends CAS email messages through Mailjet”,依赖的 Mailjet 官方客户端版本在 libs.versions.toml 中锁定为 com.mailjet:mailjet-client:6.0.1。
模块引入后,CAS 会在满足如下条件时自动装配 Mailjet 邮件发送器(见 CasMailjetEmailSenderAutoConfiguration.java):
- 启用了
Notifications特性(CasFeatureModule.FeatureCatalog.Notifications); - 特性模块名为
mailjet(邮件子模块为mailjet-email)。
第二步:配置 Mailjet 凭据与模式
所有邮件相关配置都挂在 cas.email-provider.mailjet 前缀下,对应的配置模型类是 MailjetProperties.java。核心参数如下:
| 配置项 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
cas.email-provider.mailjet.api-key |
String | 是 | 用于向 Mailjet 服务认证的 API Key |
cas.email-provider.mailjet.secret-key |
String | 是 | 用于向 Mailjet 服务认证的 Secret Key |
cas.email-provider.mailjet.bearer-access-token |
String | 是(SMS 场景) | Bearer 访问令牌,源码注释明确“主要用于 SMS 集成” |
cas.email-provider.mailjet.sandbox-mode |
boolean | 否(默认 false) |
沙箱模式开关,见下文说明 |
关于表达式语言支持
api-key、secret-key、bearer-access-token 三个字段均标注了 @ExpressionLanguageCapable,意味着它们支持 CAS 的 Spring Expression Language 值解析。在 MailjetEmailConfiguration.java 中,创建 MailjetClient 时会先通过 SpringExpressionLanguageValueResolver 对配置值做解析,再写入 ClientOptions:
val resolver = SpringExpressionLanguageValueResolver.getInstance();
val options = ClientOptions.builder()
.apiKey(resolver.resolve(casProperties.getEmailProvider().getMailjet().getApiKey()))
.apiSecretKey(resolver.resolve(casProperties.getEmailProvider().getMailjet().getSecretKey()))
.bearerAccessToken(resolver.resolve(casProperties.getEmailProvider().getMailjet().getBearerAccessToken()))
.build();
因此你可以用 #{...} 引用外部属性、或用表达式动态求值来注入凭据,而不必把密钥明文写死在配置文件里。
沙箱模式(sandbox-mode)
沙箱模式是联调阶段非常有用的开关。配置模型的 Javadoc 说明如下:设置为 true 时,消息不会真正投递,但仍会返回完整的消息处理错误信息;若消息处理无错误,响应会遵循正常的响应负载格式,只是省略 MessageID 与 MessageUUID。换言之,它让你在不消耗真实配额、不打扰真实收件人的前提下,验证整条发送链路与参数正确性。
在 MailjetEmailSender.java 中,沙箱开关被显式写入发送请求:
val request = SendEmailsRequest
.builder()
.message(messageBuilder.build())
.sandboxMode(casProperties.getEmailProvider().getMailjet().isSandboxMode())
.advanceErrorHandling(true)
.build();
测试用例 MailjetEmailSenderTests.java 正是以沙箱模式 + 假凭据启动的:
cas.email-provider.mailjet.sandbox-mode=true
cas.email-provider.mailjet.api-key=1234567890
cas.email-provider.mailjet.secret-key=1234567890
建议生产环境务必关闭沙箱模式,避免邮件被静默拦截。
第三步:配置邮件内容与收件人
Mailjet 发送器使用的是 CAS 统一的邮件属性模型 EmailProperties.java,这些属性同样适用于其他邮件通道,通常挂在各功能(如密码重置、MFA 令牌通知)自己的 email 配置节点下:
| 属性 | 必填 | 说明 |
|---|---|---|
from |
是 | 发件人地址 |
subject |
是 | 邮件主题;可写死文本,也可用 #{subject-language-key} 语法引用语言包中的 message key,按当前 locale 解析,解析失败时回退默认值 |
attributeName |
是 | 用于定位收件人邮箱的 Principal 属性名,默认 mail 与 email;多个属性会逐一在 Principal 上查找,可能触发发送多封邮件 |
text |
否 | 邮件正文,支持占位符替换、外部模板文件或 Groovy 脚本(详见下文) |
cc / bcc |
否 | 抄送 / 密送地址列表 |
replyTo |
否 | 回复地址 |
html |
否 | 正文是否按 HTML 渲染(默认 false) |
priority |
否 | 邮件优先级(对应 X-Priority 头),1 为最高,5 为最低,默认 1 |
validateAddresses |
否 | 是否校验所有地址(该行为取决于具体 provider 实现) |
邮件正文的三种构建方式
CAS 提供统一的邮件正文策略(详见 Sending-Email-Configuration.md),Mailjet 通道同样适用:
- 默认占位符模式:正文中的
${...}变量在运行时被替换为对应功能提供的值,例如${url}、${token}; - 外部模板文件:
text指向一个 HTML 等外部文件路径;若扩展名为.gtemplate,则会用 Groovy 的GStringTemplateEngine处理,支持<%= %>表达式与${...}条件拼接;模板还支持按 locale 自动本地化(如EmailTemplate.html对应EmailTemplate_de.html); - Groovy 脚本:
text指向外部 Groovy 脚本,脚本以def run(Object[] args)为入口,接收parameters(参数 Map)、logger、locale三个参数并返回正文文本;也支持内联写法如groovy { return 'This is your email message!' }。
第四步:理解 Mailjet 发送器底层实现
邮件发送核心类是 MailjetEmailSender.java,它实现了 CAS 通知 API 中的 EmailSender 接口(EmailSender.java)。该接口要求实现 send(EmailMessageRequest) 并返回 EmailCommunicationResult,默认 Bean 名为 emailSender,CAS 所有需要发邮件的功能都通过该 Bean 统一调用,因此 Mailjet 通道是全局替换式的:只要该模块被装配,整个 CAS 的邮件出口都会走 Mailjet。
send 方法的调用链(L37-L95)可以拆解为:
- 组装事务性邮件:通过
TransactionalEmail.builder()构建消息,把请求中的收件人集合映射为SendContact,并设置发件人、抄送、密送、主题、优先级;同时固定开启templateLanguage(true)、trackClicks(ENABLED)、trackOpens(ENABLED),并把发件人作为模板错误上报地址; - 处理可选字段:仅当配置了
replyTo时才调用replyTo(...)(FunctionUtils.doIfNotBlank); - 区分正文格式:
html=true时使用htmlPart(body),否则使用textPart(body); - 发送并判定结果:构造
SendEmailsRequest(开启advanceErrorHandling),调用request.sendWith(mailjetClient);逐条检查返回的SentMessageStatus,对ERROR状态的 message 聚合打印错误明细,只要存在一条SUCCESS即认为整体发送成功,最终包装为EmailCommunicationResult返回给上层。
值得一提的是,主题字符串会先经过 EmailSender.determineEmailSubject 处理:先对 ${...} 做上下文替换,若命中 #{...} 语言键语法,则从 MessageSource 中按当前 locale 取翻译文本,最后再做一次 Spring 表达式解析。
Bean 装配与热刷新
MailjetEmailConfiguration.java 负责装配两个 Bean:
mailjetEmailClient:MailjetClient实例,受@RefreshScope保护,配置热更新后凭据可动态刷新;emailSender:EmailSender实现(即MailjetEmailSender),注入mailjetEmailClient、messageSource与CasConfigurationProperties。
两者均标注 @ConditionalOnMissingBean,允许高级用户用自己的自定义 Bean 覆盖默认实现。
验证与健康检查
集成是否生效,可以从以下两个角度验证:
- 单元测试视角:MailjetEmailSenderTests.java 以沙箱模式启动 Spring 上下文,构造带
email属性的 Principal 和EmailMessageRequest,断言emailSenderBean 存在且调用send不抛异常(由于凭据为假,isSuccess()为false)。这组测试证明了“配置 + 自动装配 + 发送调用”全链路是可实例化、可调用的; - 运行时视角:CAS 为邮件功能暴露了
health端点及mailHealthIndicator健康指示器(见 Sending-Email-Configuration.md),可结合 Spring Boot Actuator 观察邮件通道的健康状态。
附:同模块的 SMS 通道
cas-server-support-mailjet 模块同时注册了 MailjetSmsConfiguration(MailjetSmsConfiguration.java),对应的 MailjetSmsSender.java 通过 Mailjet 的 SmsSend REST 资源发送短信。SMS 配置前缀为 cas.sms-provider.mailjet(见 SmsProvidersProperties.java),其中 bearer-access-token 是主要认证凭据;测试用例 MailjetSmsSenderTests.java 展示了最小配置:
cas.sms-provider.mailjet.bearer-access-token=test
cas.sms-provider.mailjet.secret-key=test
需要说明的是:SMS 通道与本文邮件主题无关,属于同一模块的附带能力,实际使用时请以 SMS-Messaging-Configuration-Mailjet.md 为准。
小结
接入 Mailjet 邮件通道,只需三步:在 Overlay 中引入 cas-server-support-mailjet、配置 cas.email-provider.mailjet.api-key 与 secret-key、为具体功能配置好 from/subject/收件人属性。开发联调阶段建议开启 sandbox-mode=true 验证链路,生产环境关闭沙箱并妥善保管凭据(善用 Spring 表达式注入)。底层上,MailjetEmailSender 通过 Mailjet 官方客户端的事务性邮件 API 完成投递,CAS 所有基于 EmailSender 的通知功能(密码重置、MFA 令牌、风险告警等)将自动切换到该通道,无需逐一改动业务代码。