上周有个朋友在群里甩了张报错截图问若依RuoYi单应用版本里发邮件本地跑得好好的一上测试环境就535 Authentication failed改了半天配置也没动静。这场景太典型了——Java 生态里发送邮件这件事代码本身十分钟能写完真正花时间的是配置对齐、异常兜底和上线后的稳定性治理。若依单应用也就是那个大家熟悉的单体后台管理框架本身已经把邮件工具类放在了公共模块里看起来开箱即用但真到业务里做验证码、告警通知、报表推送坑一个接一个。这篇内容就是围绕若依单应用发送邮件这条线把从依赖引入、SMTP 参数选择、服务封装、异步线程池、失败重试到线上排错的全过程捋一遍。适合两类人看一是刚接手若依项目、需要在业务模块里加个发邮件功能的后端同学二是已经把邮件发出去、但被超时、乱码、进垃圾箱这些问题反复折腾的开发者。我不打算只贴几行JavaMailSender的调用代码那样网上到处都是重点放在为什么这么配参数怎么算出来出问题往哪查这些文档里通常不写的东西上。下面按依赖配置、代码落地、稳定性治理、故障排查四个层面展开中间会穿插可以直接抄的配置和代码也会说清楚哪些做法是我踩过坑之后改掉的。1. 先把需求拆开若依单应用发邮件到底在解决什么问题1.1 单应用形态和微服务形态的差别在哪若依这套框架有单体版和微服务版两条线邮件能力的落点完全不同。微服务版通常会单独拆一个消息通知服务邮件只是其中一种通道跟短信、站内信并列通过消息队列解耦而单应用版本没有这层中间件业务模块比如用户注册、订单提醒、定时任务告警直接调用公共模块里的工具类同步或异步地把邮件扔出去。这个差异决定了三件事。第一代码位置邮件相关的能力应该收在公共模块里比如ruoyi-common下的工具包让所有业务模块都能引用而不是每个模块各写一套。第二资源占用单应用里邮件发送和 Web 请求共享同一个 JVM如果同步发送一封邮件平均耗时 1 秒左右接口响应时间直接翻倍所以异步几乎是必选项。第三耦合度单应用里业务代码和邮件发送贴得很近容易写成发完邮件再返回结果一旦邮件服务商抖动主流程跟着挂所以调用边界要划清楚。我见过不少项目把发邮件直接写在 Controller 里try-catch包一层就当异步了实际上还是同步阻塞。这种写法在用户量小的时候看不出问题日活一上来接口超时告警就开始响。1.2 从能发出去到发得稳的四个层次我把邮件能力分成四层每一层的成本和收益差别很大建议按需推进别一上来就堆全套。第一层是能发出去配好 SMTP能用SimpleMailMessage发纯文本。这一层半天能搞定但只适合内部告警这种不在乎排版的场景。第二层是发得好看改用MimeMessageHelper支持 HTML、内联图片、附件再把内容抽成模板文件。这层大概需要一天收益是运营和产品能自己改文案不用每次都找你发版。第三层是发得快加异步线程池、批量发送、收件人分组。这层的核心是别让邮件拖慢主业务通常是必做项。第四层是发得稳失败重试、频率限制、发送记录落库、指标监控。这层最容易被跳过,但恰恰是上线三个月后救命的東西。举个真实场景某次邮件服务商侧限流,大量发送返回421如果没有重试和记录,你根本不知道哪些用户没收到验证码,只能人工补发。注意不要在第一层就纠结要不要上消息队列。单应用场景下,一个配置合理的线程池 一张发送记录表,足够撑住绝大多数业务量,引入 MQ 反而增加运维负担。2. 依赖与账号配置先把通道打通2.1 依赖引入与版本对齐这个坑若依单应用基于 Spring Boot发邮件用官方 starter 就行不需要自己拼 JavaMail 的依赖。但这里有个非常隐蔽的版本问题Spring Boot 2.x 用的是javax.mail包名Spring Boot 3.x 全面切到jakarta.mail。如果你的项目是 2.x却从网上抄了一段 3.x 的代码编译期可能不报错因为 IDE 自动补全拉错了包运行期直接NoClassDefFoundError。!-- Spring Boot 2.x 项目引入 starter 即可JavaMail 实现由 Spring 管理 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency引入之后先执行一次mvn dependency:tree | grep mail确认实际拉到的实现包是com.sun.mail:javax.mail还是org.eclipse.angus:jakarta.mail。这一步花两分钟能省掉后面半小时的排查。另外如果你在公共模块里封装了邮件工具类注意把 starter 的依赖范围写对业务模块引用公共模块时能传递到就行不要在多个模块里重复声明版本号。2.2 SMTP 参数怎么选端口、加密方式和授权码这一段是新手最容易懵的地方。邮箱服务商给的文档往往只写服务器地址、端口、SSL 开启但没说清端口和加密方式的对应关系。端口加密方式说明适用场景25无 / STARTTLS传统端口大量云主机默认封禁出站 25内网自建邮件服务465隐式 SSLSMTPS连接建立即加密大多数公网邮箱服务商推荐587STARTTLS先明文连接再升级加密部分企业邮箱、国际服务商选择逻辑很简单优先试 465 ssl.enabletrue不通再换 587 starttls.enabletrue。千万不要同时把 ssl 和 starttls 都设成 true某些实现会直接抛握手异常报错信息还特别模糊只说 Could not connect。还有一个概念要分清登录密码和授权码不是一回事。主流邮箱服务商对第三方客户端普遍要求使用客户端授权码或应用专用密码这个东西是登录网页版邮箱后在安全设置里单独生成的跟你的登录密码完全不同。用登录密码去连 SMTP返回的就是开头那位朋友遇到的535。2.3 application.yml 配置与几个必调的参数若依的配置文件在ruoyi-admin/src/main/resources/application.yml邮件配置追加在spring节点下。spring: mail: host: smtp.example.com port: 465 username: no-replyexample.com # 授权码里有特殊字符时务必加引号否则 YAML 解析会出问题 password: Abc123#xyz default-encoding: UTF-8 properties: mail: smtp: auth: true ssl: enable: true # 三个超时缺一不可单位毫秒 connectiontimeout: 5000 timeout: 8000 writetimeout: 8000这里有几个必须手动调的地方。default-encoding不写默认是平台编码中文主题在某些环境会变问号。三个 timeout 如果不设底层用的是无限等待一旦对端不响应你的异步线程会被永久占住线程池很快被打满——这个故障模式非常隐蔽表现出来是邮件功能突然全部卡住重启就好实际是线程泄漏。connectiontimeout管建立连接timeout管读超时writetimeout管写超时三个值建议设成 5 到 8 秒这个量级既给了网络波动余量又不至于卡太久。提示密码里包含、#、:这类字符时YAML 里不加引号会被截断或解析错误。我习惯统一给 password 加双引号养成习惯就不会踩。另外若依支持配置文件加密比如集成 Jasypt如果团队有这个规范密码字段要走加密流程不要明文提交到代码仓库。3. 代码落地服务封装与业务调用3.1 一个够用的 MailService 骨架若依自带MailUtils之类的工具类不同版本路径略有差异核心都是对JavaMailSender的再封装。但框架自带的通常只覆盖纯文本发送业务里真正需要的是 HTML 附件 内联图片这几种组合。我一般会在公共模块里再抽一层MailService把常用场景收口。Service public class MailService { Resource private JavaMailSender mailSender; /** 发送 HTML 邮件支持附件 */ public void sendHtml(String to, String subject, String html, MapString, File attachments) throws MessagingException { MimeMessage message mailSender.createMimeMessage(); // 第二个参数 true 表示 multipart有附件时必须开 MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(fromAddress); helper.setTo(to); helper.setSubject(subject); helper.setText(html, true); if (attachments ! null) { for (Map.EntryString, File e : attachments.entrySet()) { helper.addAttachment(e.getKey(), e.getValue()); } } mailSender.send(message); } }MimeMessageHelper构造时那个encoding参数别省它决定了主题和正文的编码方式。很多中文乱码问题就出在这helper 用默认编码构造主题走 Base64 编码时用了平台字符集收件箱里显示成一串问号。setText(html, true)的第二个参数是html标志忘了写就是纯文本渲染页面上会看到一堆标签。3.2 模板化别再用字符串拼接正文了纯 Java 字符串拼 HTML 的问题是维护成本极高。改一个表格样式要发版中文内容里混着号看得人眼花还容易漏掉转义导致内容被截断。我的做法是把模板放到resources/templates/mail/下用 Thymeleaf 渲染若依本身已经依赖了 Thymeleaf 的话几乎零成本。Resource private TemplateEngine templateEngine; public String renderTemplate(String templateName, MapString, Object vars) { Context context new Context(Locale.CHINA, vars); return templateEngine.process(mail/ templateName, context); }模板文件mail/verify-code.html里直接用${code}、${expireMinutes}这种占位符。这样做的好处是运营改文案只需要改 HTML 文件不用碰 Java 代码变量注入自动做转义用户填的内容里带尖括号也不会破坏页面结构。注意模板里不要引用外网 CDN 的 CSS 和图片。很多邮箱客户端会拦截外部资源用户看到的是没有样式的裸文本。样式尽量内联写在标签的style属性里。3.3 异步发送线程池参数是要算出来的同步发送是绝对不能接受的。一封邮件从建立连接到收到服务端响应正常 800 毫秒到 2 秒网络差的时候更久。放到接口里用户点一下发送验证码转圈三秒体验直接崩。异步方案是Async配上自定义线程池。线程池参数别拍脑袋我给个估算方法假设日均发信 5000 封集中在工作日的 2 个小时内早 9 点到 11 点峰值 QPS 大约是 5000 ÷ 7200 ≈ 0.7考虑突发流量放大 3 倍按 2 QPS 算。单个任务平均耗时 1.5 秒那么需要的线程数是 2 × 1.5 3留 2 到 3 倍余量核心线程数取 8 比较合适。Configuration EnableAsync public class MailAsyncConfig { Bean(mailExecutor) public ThreadPoolTaskExecutor mailExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(8); executor.setMaxPoolSize(16); executor.setQueueCapacity(500); executor.setKeepAliveSeconds(60); executor.setThreadNamePrefix(mail-); // 队列满时由调用线程执行形成天然背压避免静默丢弃 executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }这里几个决策说一下理由。线程名前缀mail-是给排查用的线上jstack一把就能看出邮件线程卡在哪。拒绝策略选CallerRunsPolicy而不是直接丢弃是因为邮件的业务价值高于响应时间——宁可让调用方慢一点也别让通知悄悄消失当然如果你的场景是营销邮件丢弃更合理。队列容量 500 是个折中值太大导致任务积压时间过长用户收到验证码时早就过期了太小又起不到缓冲作用。还有个大坑Async标注的方法必须通过代理调用才生效。同一个类里 A 方法调用 B 方法B 上的Async会被忽略仍然同步执行。我见过有人把sendMail和register写在同一个 Service 里测了半天发现根本没异步。事务边界也要注意。异步方法跑在独立线程里拿不到原线程的事务上下文。所以正确做法是主流程先把数据落库、提交事务再把已经组装好的参数传给异步方法不要在异步方法里再去查刚插入还没提交的数据查不到的。3.4 批量发送与收件人处理群发场景有两个常见误区。第一是把几十个收件人全塞进To字段收件人之间互相能看到邮箱地址这是隐私事故。正确的做法是用Bcc密送或者干脆逐个发送。第二是一次性传几百个地址导致邮件命令过长被服务端拒绝报552之类的错误。我的做法是分批每批 30 到 50 个地址批与批之间 sleep 一小会儿。发送速率要控制主流邮箱服务商对单账号都有频率限制短时间大量发送很容易触发限流甚至临时封禁发信权限。public void sendBatch(ListString recipients, String subject, String html) { int batchSize 40; for (int i 0; i recipients.size(); i batchSize) { ListString batch recipients.subList(i, Math.min(i batchSize, recipients.size())); try { doSend(batch, subject, html); Thread.sleep(500); } catch (Exception e) { log.warn(批次发送失败, index{}, size{}, i, batch.size(), e); } } }注意异常要按批捕获不能一个批次失败就中断整个循环。同时把失败的批次记录下来后面走补发流程。4. 稳定性治理重试、限流、可观测性4.1 失败重试怎么做才不出事无脑重试是灾难。如果账号密码错了535重试一百次也没用只会把账号触发风控如果对端限流421立即重试等于火上浇油。所以第一步是错误分类。可重试的连接超时、读超时、421服务不可用、450邮箱暂时不可用、451本地错误。不可重试的535认证失败、550邮箱不存在、553地址格式错误、554内容被拒。策略上我用指数退避间隔 30 秒、2 分钟、10 分钟最多三次。实现层面轻量方案是内存里的延迟队列简单但重启丢任务稳妥方案是落一张发送记录表用若依自带的定时任务Scheduled或 Quartz扫描待重试的记录。CREATE TABLE sys_mail_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, to_addr VARCHAR(200) NOT NULL COMMENT 收件人, subject VARCHAR(200) NOT NULL, content MEDIUMTEXT COMMENT 正文快照, status TINYINT DEFAULT 0 COMMENT 0待发 1成功 2失败 3放弃, retry_count INT DEFAULT 0, next_retry_at DATETIME COMMENT 下次重试时间, error_msg VARCHAR(500), create_time DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_status_retry (status, next_retry_at) ) COMMENT 邮件发送记录;这个表还有额外价值客服反馈没收到验证码时你能立刻查到是发送失败、被退回还是对方邮箱把邮件扔进垃圾箱了。4.2 限流与收发名单控制限流分两个维度。按收件人限流比如同一个邮箱 60 秒内只能收一封验证码邮件——这个用 Redis 存一个带过期时间的 key 就行setIfAbsent(key, 1, 60, TimeUnit.SECONDS)返回 false 就直接拒绝既防刷也防用户狂点。按全局限流控制每秒发信量不超过服务商给的配额。简单实现用 Guava 的RateLimiter单机够用集群部署就得换 Redis 令牌桶否则 N 台机器各限各的总量还是超。另外强烈建议加一层环境隔离。测试环境配一个域名白名单只允许发往公司内部邮箱其他地址一律拦截并打日志。这个机制能防住测试环境定时任务跑飞了给真实用户群发测试邮件这种事故——我亲眼见过一次虽然内容无害但善后处理花了不少时间。4.3 可观测性日志、指标和脱敏邮件发送的日志要包含几个关键字段收件人脱敏后、主题、耗时、结果、错误码。脱敏规则很简单保留首字符和域名比如z***example.com既能定位问题又不泄露完整信息。指标方面如果项目已经接了 Prometheus可以打三个核心指标发送总数、失败数按错误码打标签、发送耗时 P95。P95 超过 3 秒就该看看是不是网络或者服务商侧的问题了。没接监控的话至少做个日终统计任务把当天的发送量、成功率算出来发到运维群异常时人工介入。链路追踪这块异步线程会丢 MDC 上下文导致日志里的 traceId 是空的。解决办法是在提交任务时手动把 MDC 内容传过去在异步方法开头MDC.setContextMap()结束时MDC.clear()否则线程复用会把上一个请求的上下文带过来日志串得一塌糊涂。5. 常见问题排查实录5.1 认证与协议类错误对照错误码典型原因处理方向535用户名密码/授权码错误确认用的是授权码而非登录密码账号是否开了 SMTP 服务550收件人不存在或被拒校验地址拼写确认对方域名可收信553发件人地址格式非法检查setFrom的地址是否符合规范554内容被判定为垃圾邮件检查正文关键词、链接数量、是否含图片过多421服务不可用或连接数超限降低并发稍后重试451服务端临时错误重试即可Could not connect端口被墙或被云厂商封禁换 465/587检查安全组出站规则排查顺序建议先用命令行工具单独验证账号能不能连上排除代码问题再在代码里打开 JavaMail 的 debug 模式spring.mail.properties.mail.debugtrue能看到完整的协议交互过程非常直观。5.2 中文乱码与附件名乱码主题乱码基本是编码没指定。MimeMessageHelper构造时传UTF-8default-encoding也设成 UTF-8两处都对了才不会出问题。附件名乱码更麻烦一点尤其是收件方用某些老版本客户端时。稳妥写法是对文件名做一次编码处理String encodedName MimeUtility.encodeText(fileName, UTF-8, B); helper.addAttachment(encodedName, file);正文里的中文如果是通过模板渲染的还要确认模板文件本身的存储编码是 UTF-8。有些编辑器默认存成 GBK本地看没问题打包后就读成乱码了。检查方法是看编译后的target/classes/templates目录里文件的实际编码。5.3 超时、卡死和线程泄漏邮件功能突然卡住重启就好这个现象九成是超时没配导致线程被占死。排查方法很直接jstack导出线程栈搜mail-前缀的线程看它们卡在哪个方法上。如果都卡在SocketInputStream.read那就是对端不响应而你的timeout没设。还有一种情况是 DNS 解析慢。SMTP 服务器地址如果用域名每次建立连接都要解析某些环境下 DNS 超时能到十几秒。解决办法是在本机 hosts 里写死 IP或者确认内网 DNS 稳定。连接池要不要上Spring Boot 官方 starter 不带连接池需要额外引入commons-pool2并配置mail.smtp相关属性。我的建议是日发信量低于一万、发送不密集的场景别上池每次新建连接更简单可靠高频发送才考虑而且上池之后要重点监控连接泄漏。5.4 邮件进垃圾箱的几条实战经验这个问题最让人头疼因为没有明确报错只能靠用户反馈。几个能自己控制的方向发件人地址和实际发信域名保持一致别用no-replya.com的身份去发b.com的邮件。正文里避免大量短链接和夸张的营销词汇图片和文字的配比要合理纯图片邮件几乎必进垃圾箱。批量发送控制速率短时间同一个 IP 发太多容易被标记。如果业务重要找服务商配置好发信域名的验证记录这个环节通常需要运维配合。还有个小技巧新接入的邮箱账号先做预热别一上来就日发几千封。头几天每天发几十封逐步加量账号信誉度会好很多。最后分享一个我在实际项目里的习惯。邮件这种发出去就完事的能力最怕的是没人管。我会在发送记录表上加一个每日汇总的定时任务把失败率超过 5% 的情况直接推到运维群同时附上前十条失败原因。这套东西加起来不到一百行代码但过去一年里帮我提前发现过两次服务商侧的限流策略变更省掉了大量被动排查的时间。至于线程池参数先按估算值配上线后观察一周的实际耗时分布再调整比一次性追求最优靠谱得多。