1. 邮件通知在项目中的真实定位与方案选型1.1 为什么邮件通知至今没被淘汰做后端项目这些年消息推送的手段换了一茬又一茬短信、站内信、WebSocket、各种推送通道轮番上阵但邮件通知始终稳稳占着一席之地。原因其实很朴素它跨平台、可归档、能承载长文本和附件而且对接收方来说没有必须装某个App的门槛。用户注册验证、密码找回、订单状态变更、系统告警、日报周报这些场景里邮件依然是性价比最高的选择。我在几个中小型项目里都做过邮件通知模块最典型的诉求是系统跑完一个定时任务后把结果发到指定邮箱。这种需求用短信成本高用站内信用户不一定在线邮件刚好卡在中间——异步、可追溯、格式还能做得挺好看。所以当有人问SpringBoot怎么发邮件的时候我一般不会只丢一段代码而是先把整个链路讲清楚因为踩坑的地方往往不在代码本身而在邮箱服务商的配置和网络环境上。1.2 技术选型为什么是SpringBoot JavaMailSenderSpringBoot对邮件发送的封装已经相当成熟核心就是spring-boot-starter-mail这个starter。它底层用的是Jakarta Mail老版本叫JavaMailSpring又在其上包了一层JavaMailSender接口把繁琐的Session、Transport、MimeMessage构造过程都简化了。你只需要在配置文件里填几个参数注入一个Bean就能发信。选它而不是自己手撸Socket或者用第三方HTTP邮件API主要考虑三点。第一是标准化SMTP是通用协议换邮箱服务商基本只改配置不改代码。第二是生态整合SpringBoot的自动配置让JavaMailSender开箱即用还能和Async、线程池、模板引擎无缝配合。第三是可控性发送超时、编码、附件、HTML内容这些细节都能精细控制不像某些封装过度的SDK把参数藏得死死的。至于为什么拿163邮箱举例是因为它在国内个人开发者里普及率高SMTP服务稳定而且免费账号就能开启授权码发信适合做demo和中小项目。需要说明的是下面所有配置和代码都是基于常见实践的合理还原具体参数请以你实际使用的邮箱服务商文档为准。1.3 整体链路拆解一封邮件从代码到收件箱经历了什么很多人写邮件功能时只盯着send()那一行结果一出问题就懵。其实完整链路是这样的应用调用JavaMailSender.send()Spring构造MimeMessage通过SMTP协议连接服务商的邮件服务器比如163的smtp.163.com服务器验证身份后接收邮件再投递到收件方的邮件服务器最终进入对方收件箱。中间任何一环出问题表现都是邮件没收到但原因可能天差地别。所以排查思路必须按链路走先确认配置参数对不对再确认网络能不能连通SMTP服务器端口然后确认身份验证是否通过最后才怀疑是不是被对方判为垃圾邮件。这个顺序能帮你省下大量瞎试的时间后面第4节我会把常见故障整理成速查表。2. 环境准备与163邮箱的关键配置2.1 依赖引入与版本选择在pom.xml里加依赖这是第一步dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency这里有个容易被忽略的点不要手动指定Jakarta Mail的版本交给SpringBoot的依赖管理去决定。我见过有人为了保险手动锁了一个老版本结果和SpringBoot的自动配置打架报出各种NoSuchMethodError。如果你用的是SpringBoot 3.x底层已经是Jakarta Mail 2.x包名从javax.mail变成了jakarta.mail网上很多老教程的import路径是错的复制代码时一定要留意。2.2 163邮箱开启SMTP服务与获取授权码这一步是新手最容易卡住的地方。163邮箱默认是不允许第三方客户端直接发信的你需要手动开启SMTP服务并且用授权码代替登录密码。流程大致是登录网页版邮箱进入设置里的POP3/SMTP/IMAP选项开启SMTP服务按提示完成验证后会生成一串授权码。注意授权码只显示一次务必当场复制保存。它和你平时登录邮箱的密码是两回事配置里填的必须是授权码填登录密码会直接认证失败。我踩过的坑是开了SMTP但忘了保存授权码只能重新生成一次旧的授权码会失效。所以如果你在多个环境开发、测试、生产共用同一个邮箱账号建议每个环境单独生成授权码方便出问题时定位是哪个环境在发信也方便单独吊销。2.3 application.yml核心参数逐项说明配置写对功能就成了一半。下面是一份典型的配置spring: mail: host: smtp.163.com port: 465 username: your_account163.com password: your_authorization_code protocol: smtp default-encoding: UTF-8 properties: mail: smtp: auth: true ssl: enable: true connectiontimeout: 5000 timeout: 5000 writetimeout: 5000逐项拆解一下。host是163的SMTP服务器地址这个基本固定。port这里用的是465对应SSL加密端口163也支持25端口非加密和994端口但25端口在很多网络环境下被限制所以我一般直接上465。username填完整邮箱地址password填授权码。properties里的几个参数是重点。auth: true表示需要身份验证这个必须开。ssl.enable: true配合465端口使用保证传输加密。后面三个timeout参数我强烈建议显式设置默认值在某些网络下会等很久导致接口卡死。设成5000毫秒5秒是个比较平衡的值既能容忍正常网络波动又不会让调用方等太久。提示如果你用的是25端口需要把ssl.enable改成false并可能需要开启starttls.enable: true。但再次强调优先用465端口省心。3. 核心代码实现与发送逻辑拆解3.1 最简发送三行代码背后的封装先看最简单的用法理解Spring帮我们做了什么Autowired private JavaMailSender mailSender; public void sendSimple(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(your_account163.com); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); }SimpleMailMessage适合纯文本、无附件的场景。注意setFrom最好显式设置虽然有些服务商允许省略但显式写出来能避免发件人地址不合法的报错。setTo支持多个收件人传数组即可。这套代码能跑通说明你的基础配置没问题可以进入下一步。3.2 HTML邮件与附件MimeMessage的正确打开方式实际项目里纯文本太少见了大部分要发HTML格式甚至带附件。这时候要用MimeMessage配合MimeMessageHelperAutowired private JavaMailSender mailSender; public void sendHtmlWithAttachment(String to, String subject, String htmlContent, File attachment) throws Exception { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_account163.com); helper.setTo(to); helper.setSubject(subject); helper.setText(htmlContent, true); if (attachment ! null attachment.exists()) { helper.addAttachment(attachment.getName(), attachment); } mailSender.send(message); }MimeMessageHelper的构造函数第二个参数true表示支持多部分multipart带附件必须传true。第三个参数指定编码中文邮件一定要写UTF-8否则标题和正文会乱码。setText的第二个参数true表示内容是HTML不写的话HTML标签会被当纯文本显示出来。注意附件文件名如果是中文某些邮件客户端会显示乱码。稳妥的做法是用MimeUtility.encodeText()对文件名做编码或者干脆用英文文件名。我在一个报表项目里就因为中文附件名被客户投诉过后来统一改成report_20240101.xlsx这种格式世界清净了。3.3 异步发送别让邮件拖垮你的接口邮件发送是典型的IO密集型操作同步发送会让接口响应时间从几十毫秒飙到几秒。所以生产环境一定要异步化。SpringBoot里最简单的做法是加AsyncService public class MailService { Autowired private JavaMailSender mailSender; Async(mailExecutor) public void sendAsync(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(your_account163.com); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }别忘了在启动类或配置类上加EnableAsync并且自定义一个线程池别用默认的Configuration public class AsyncConfig { Bean(mailExecutor) public Executor mailExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(5); executor.setQueueCapacity(100); executor.setThreadNamePrefix(mail-); executor.setRejectedExecutionHandler( new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }线程池参数怎么定邮件发送不是高频操作核心线程2个、最大5个足够应付大多数场景。队列容量给100超出后走CallerRunsPolicy也就是让调用线程自己执行相当于降级为同步至少不会丢任务。这个策略比直接丢弃任务要稳妥。3.4 用模板引擎让邮件内容可维护硬编码HTML字符串是维护噩梦。我一般用Thymeleaf或Freemarker做邮件模板。以Thymeleaf为例把模板放在resources/templates/mail/下然后用TemplateEngine渲染Autowired private TemplateEngine templateEngine; public String buildContent(String templateName, MapString, Object vars) { Context context new Context(); context.setVariables(vars); return templateEngine.process(mail/ templateName, context); }这样运营改文案不用动代码改模板文件就行。变量通过Map传入模板里用th:text或th:utext取值。注意HTML邮件里CSS支持有限别用太花哨的样式内联样式最保险很多邮件客户端会过滤style标签。4. 常见问题排查与避坑经验实录4.1 认证失败、连接超时、邮件进垃圾箱的排查顺序邮件功能的问题表现高度相似但原因五花八门。我整理了一张速查表按出现频率排序现象可能原因排查方向535 Authentication failed用了登录密码而非授权码重新生成授权码并替换配置连接超时 / Connection timed out端口被限制或网络不通换465端口检查防火墙出站规则邮件发送成功但收不到被判为垃圾邮件检查发件人信誉、内容敏感词、SPF记录中文乱码编码未统一为UTF-8检查helper编码和配置文件编码附件名乱码文件名未编码用英文名或MimeUtility编码发送极慢未设超时或未异步加timeout参数改异步发送排查时严格按配置→网络→认证→内容的顺序走别一上来就怀疑代码。我见过太多人代码改了半天最后发现是授权码填错了。4.2 那些文档里不会写的实操心得第一个心得发件人和username保持一致。有些服务商要求setFrom的地址必须和认证账号相同否则拒发。我图省事用过别名结果被163拒了报错信息还很含糊。第二个心得控制发送频率。免费邮箱账号通常有每日发信上限短时间内大量发送会被限流甚至临时封禁。如果是系统告警这种可能突发的场景建议加个简单的令牌桶限流或者接入专业邮件服务。我在一个监控项目里就吃过亏半夜告警风暴把当天额度打满了第二天正常通知全发不出去。第三个心得收件人列表别太大。一封邮件塞几十个收件人容易被判垃圾邮件而且收件人之间能看到彼此地址有隐私问题。正确做法是循环单发或者用密送BCC。MimeMessageHelper支持setBcc这个细节很多人不知道。第四个心得测试时用真实邮箱。有些人用假地址测试发送成功就以为没问题其实SMTP服务器可能只是接收了邮件投递失败是异步返回的。一定要用自己能登录的邮箱验证最好多试几个不同服务商的邮箱看看兼容性。4.3 日志与监控让问题可追溯邮件发送一定要打日志至少记录收件人、主题、发送结果和时间。异步发送时异常不会抛到调用方如果不打日志出了问题你连发没发都不知道。我的做法是封装一层发送成功记info失败记error并带上异常堆栈try { mailSender.send(message); log.info(邮件发送成功, to{}, subject{}, to, subject); } catch (MailException e) { log.error(邮件发送失败, to{}, subject{}, to, subject, e); }更进一步可以把发送记录落库加个状态字段配合定时任务做失败重试。这套组合拳下来邮件模块的可靠性会有质的提升。重试要注意幂等别把同一封邮件发好几遍可以在重试前查一下状态。5. 从能用到好用进阶优化方向5.1 多邮箱服务商切换的配置抽象项目做大后可能开发环境用163生产环境用企业邮箱。这时候把配置抽象出来就很有必要。我的做法是定义一个MailProperties配置类把host、port、username这些做成可切换的profile或者干脆用策略模式封装不同服务商的发送逻辑。核心思路是让业务代码只依赖MailService接口不关心底层用的是哪家SMTP。5.2 发送结果回调与失败重试机制前面提到落库重试这里展开说下设计。表结构大致是id、收件人、主题、内容、状态待发送/成功/失败、重试次数、创建时间、更新时间。发送时先入库状态为待发送发送成功后更新为成功失败则记录失败原因。定时任务扫描失败且重试次数小于3的记录重新发送。重试间隔用指数退避比如1分钟、5分钟、15分钟避免短时间内反复冲击服务商。5.3 安全考量别把授权码写死在代码里最后强调一个安全问题。授权码等同于密码绝对不能硬编码在代码里提交到仓库。正确做法是用环境变量或配置中心注入spring: mail: password: ${MAIL_AUTH_CODE}本地开发时在IDE的运行配置里设环境变量生产环境用配置中心或密钥管理服务。我见过有人把授权码直接写在yml里推到公开仓库结果账号被盗用发垃圾邮件教训很深刻。这个习惯从第一个项目就要养成别等出事再补。整个邮件通知模块做下来代码量其实不大真正花时间的是配置调试和异常处理。把上面这些细节都照顾到你的邮件功能就能从能跑进化到敢上生产。后续如果量级上来了再考虑接入专业的邮件推送服务但那是另一个话题了。