简介这份PDF面向软件工程、计算机相关专业学生及Java邮件开发初学者围绕基于JavaMail的电子邮件系统课程设计展开帮助读者理解邮件客户端与服务器端的整体设计思路。内容系统梳理了SMTP、POP3、IMAP三大邮件通信协议的工作机制并讲解MIME标准对附件与多内容类型的支持同时深入剖析JavaMail API中Session、Store、Folder、Message、Transport等核心类的职责与调用关系覆盖客户端登录、邮件发送、接收下载、邮件夹管理等典型功能的实现要点。资源包为单一PDF文档大小约1.97MB内含完整课程设计报告与配套源文件说明结构清晰便于对照学习。目前已有415人学习下载适合需要完成邮件系统课设、理解协议原理与API用法的读者参考也可作为邮件过滤、搜索、通知及安全传输等扩展功能的设计思路来源。1. 从一份 JavaMail 邮件系统设计文档说起它到底能跑出什么很多人第一次看到「基于 JavaMail 电子邮件系统的设计含源文件」这类标题第一反应是——这不就是大学课设吗发个邮件而已Transport.send()一行代码的事。但真正把一套邮件系统从零搭起来你会发现它远不止「发信」这么简单SMTP 认证怎么配、附件怎么带、HTML 正文里嵌图片怎么处理、收信端用 POP3 还是 IMAP、中文乱码怎么根治、群发时怎么避免被对方服务器当成垃圾邮件拒收——每一个点都能让你卡上半天。这份设计文档加源文件的价值恰恰在于它把「发信 收信 附件 会话管理」这条完整链路串了起来而不是只给你一个孤零零的发送示例。这篇文章面向的是手里已经拿到或准备复现这套 JavaMail 邮件系统的人你可能是在做课程设计的学生也可能是需要给内部系统加一个邮件通知模块的后端开发。我会按「环境怎么搭 → 核心类怎么用 → 收发信怎么落地 → 踩过哪些坑 → 怎么验证和进阶」的顺序把 JavaMail 这套东西讲透。读完你应该能独立跑通一个支持发送纯文本、HTML、带附件邮件并且能用 IMAP 收信解析的最小系统。下面先从依赖和会话配置开始。2. JavaMail 环境搭建与 Session 会话配置从 jar 包到可复用连接2.1 依赖引入javax.mail 与 jakarta.mail 的选择JavaMail 的坐标在 Java EE 时代是javax.mail:javax.mail-api加具体实现com.sun.mail:javax.mail。从 Jakarta EE 9 开始包名整体迁移到jakarta.mail坐标变成com.sun.mail:jakarta.mail。如果你用的是 Spring Boot 2.x 且 JDK 8直接上javax.mail最省事如果是 Spring Boot 3.x 或 JDK 17必须用jakarta.mail否则运行时会抛ClassNotFoundException。这是第一个容易翻车的地方——很多人复制了老教程的依赖编译能过一运行就炸。Maven 里最简依赖如下jakarta.mail这个 artifact 已经包含了 API 和 Sun 的实现不需要再单独引 API 包dependency groupIdcom.sun.mail/groupId artifactIdjakarta.mail/artifactId version2.0.1/version /dependency如果你不用构建工具直接下 jar 包放进WEB-INF/lib或 classpath 也行但要确保jakarta.activation一起带上否则处理附件时会报DataType相关的错。参数上version选 2.0.x 系列即可1.6.x 是javax时代的最后稳定版两者不要混用。2.2 Session 会话认证、超时与调试开关Session是 JavaMail 的核心入口它保存了邮件服务器地址、端口、认证信息等全局配置。很多人图省事在每个发送方法里Session.getInstance()一次结果连接池无法复用高并发下性能很差。正确做法是把Session做成单例或者交给 Spring 容器管理。Properties props new Properties(); // SMTP 服务器地址与端口465 为 SSL587 为 STARTTLS props.put(mail.smtp.host, smtp.example.com); props.put(mail.smtp.port, 465); props.put(mail.smtp.auth, true); // 开启 SSL 加密 props.put(mail.smtp.ssl.enable, true); // 连接超时与读写超时单位毫秒避免网络抖动时线程卡死 props.put(mail.smtp.connectiontimeout, 5000); props.put(mail.smtp.timeout, 5000); props.put(mail.smtp.writetimeout, 5000); // 调试开关生产环境务必关掉否则控制台会打印协议交互细节 props.put(mail.debug, false); Session session Session.getInstance(props, new Authenticator() { Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(userexample.com, 授权码); } });这里几个参数值得展开说。mail.smtp.ssl.enable和mail.smtp.starttls.enable是两回事前者是全程 SSL通常 465 端口后者是先明文连接再升级为 TLS通常 587 端口。选错了会直接连接超时或握手失败。connectiontimeout、timeout、writetimeout这三个超时参数是血泪经验——不设的话对方服务器不响应时你的线程会一直挂着在 Web 应用里很快就把线程池耗光。认证密码那一栏现在主流邮箱服务商都要求用「授权码」而不是登录密码这个授权码在邮箱后台单独生成和登录密码不是一回事填错了会报AuthenticationFailedException。提示mail.debug设为 true 时能看到完整的 SMTP 对话排查认证失败、被拒收时非常有用但排查完记得关掉它会打印 Base64 编码后的认证信息。3. 邮件发送核心MimeMessage 构造与三种正文形态3.1 纯文本与 HTML 正文的构造差异发送邮件的核心类是MimeMessage它继承自Message。最简单的纯文本邮件只需要设置发件人、收件人、主题和内容四要素MimeMessage message new MimeMessage(session); // 发件人第二个参数是显示名称 message.setFrom(new InternetAddress(userexample.com, 系统通知)); // 收件人TO 是直接收件人CC 抄送BCC 密送 message.setRecipient(Message.RecipientType.TO, new InternetAddress(targetexample.com)); message.setSubject(账户激活通知, UTF-8); // 第二个参数指定 MIME 类型和字符集 message.setContent(h3您好/h3p请点击链接激活账户/p, text/html;charsetUTF-8); Transport.send(message);注意setSubject和setContent里的字符集参数。中文乱码问题十有八九出在这里setSubject不传UTF-8时默认用平台编码在 Windows 上就是 GBK收件人用 UTF-8 解码就成乱码。setContent的第二个参数必须写成text/html;charsetUTF-8这种完整形式只写text/html同样会乱码。纯文本邮件把text/html换成text/plain即可。3.2 带附件的复合邮件MimeMultipart 的嵌套结构带附件的邮件本质是一个MimeMultipart容器里面装若干BodyPart正文一个 part每个附件一个 part。这里有个容易搞混的点——如果正文里还要嵌图片比如邮件签名里的 logo需要再套一层multipart/related。先看最常用的「正文 附件」结构// 创建混合容器对应 multipart/mixed MimeMultipart multipart new MimeMultipart(mixed); // 正文部分 MimeBodyPart textPart new MimeBodyPart(); textPart.setContent(请查收本月账单, text/plain;charsetUTF-8); multipart.addBodyPart(textPart); // 附件部分 MimeBodyPart attachPart new MimeBodyPart(); FileDataSource source new FileDataSource(new File(/data/bill.pdf)); attachPart.setDataHandler(new DataHandler(source)); // 用 MimeUtility.encodeText 处理中文文件名 attachPart.setFileName(MimeUtility.encodeText(月度账单.pdf, UTF-8, null)); multipart.addBodyPart(attachPart); message.setContent(multipart); Transport.send(message);MimeMultipart的构造参数决定了邮件的整体结构mixed用于正文加附件related用于 HTML 正文内嵌资源alternative用于纯文本和 HTML 双版本共存。附件文件名一定要用MimeUtility.encodeText编码否则中文文件名在 Outlook 里会显示成一串?UTF-8?B?...?的乱码。FileDataSource直接读文件大附件场景要注意内存占用超过 10MB 的附件建议改用流式处理或直接走网盘链接。3.3 收件人类型与批量发送的正确姿势Message.RecipientType有三个值TO、CC、BCC。群发时如果直接把几十个地址塞进TO收件人能看到彼此的邮箱既不礼貌也可能泄露隐私。正确做法是把真实收件人放BCCTO填自己的地址或一个占位地址。另外setRecipients方法接受数组比循环调用setRecipient效率高InternetAddress[] toList InternetAddress.parse(ax.com,bx.com); message.setRecipients(Message.RecipientType.BCC, toList);需要提醒的是即便用了BCC短时间内向同一服务器投递大量邮件仍可能触发限流。生产环境做批量通知时常见做法是接入专业的邮件推送服务或者自己控制发送速率、加队列削峰。JavaMail 本身不提供队列能力这部分要自己在业务层实现。4. 收信与解析用 IMAP 拉取邮件并提取正文附件4.1 POP3 与 IMAP 的选型对比收信协议主要有两个POP3 和 IMAP。POP3 把邮件下载到本地后通常从服务器删除适合单设备、只读一次的场景IMAP 在服务器上保留邮件并支持文件夹、已读状态同步适合多设备。做邮件系统设计时如果只是「拉取验证码」这类一次性需求POP3 足够如果要做一个完整的邮件客户端或需要同步已读状态必须用 IMAP。下面这张表是选型时的关键差异维度POP3IMAP端口SSL995993邮件存储位置下载到本地保留在服务器文件夹支持仅收件箱完整文件夹树已读/删除状态同步不支持支持部分下载不支持支持只取正文或附件适用场景验证码拉取、归档邮件客户端、多端同步4.2 用 IMAP 拉取并解析邮件内容收信的核心类是Store和Folder。连接、打开收件箱、遍历Message再根据内容类型递归解析。下面这段代码演示了拉取最新一封邮件并提取纯文本正文Properties props new Properties(); props.put(mail.store.protocol, imap); props.put(mail.imap.ssl.enable, true); props.put(mail.imap.host, imap.example.com); props.put(mail.imap.port, 993); Session session Session.getInstance(props); try (Store store session.getStore(imap)) { store.connect(userexample.com, 授权码); // 只读方式打开收件箱避免误改已读状态 try (Folder folder store.getFolder(INBOX)) { folder.open(Folder.READ_ONLY); Message[] messages folder.getMessages(); if (messages.length 0) return; // 取最新一封 Message latest messages[messages.length - 1]; System.out.println(主题 latest.getSubject()); // 递归解析内容 Object content latest.getContent(); if (content instanceof String) { System.out.println(正文 content); } else if (content instanceof Multipart) { Multipart mp (Multipart) content; for (int i 0; i mp.getCount(); i) { BodyPart part mp.getBodyPart(i); if (part.isMimeType(text/plain)) { System.out.println(正文 part.getContent()); } else if (Part.ATTACHMENT.equalsIgnoreCase(part.getDisposition())) { // 附件保存到本地 try (InputStream is part.getInputStream()) { Files.copy(is, Paths.get(/data/recv/ MimeUtility.decodeText(part.getFileName()))); } } } } } }这段代码有几个关键点。folder.open(Folder.READ_ONLY)用只读模式打开避免拉取时把未读邮件标记成已读这在做监控或归档时很重要。getContent()返回的类型是不确定的纯文本邮件返回String复合邮件返回Multipart所以必须做类型判断再递归。附件判断用Part.ATTACHMENT.equalsIgnoreCase(part.getDisposition())注意getDisposition()可能返回 null直接调equals会空指针所以要把常量放前面。附件文件名同样要MimeUtility.decodeText解码否则中文名是乱码。4.3 大附件与部分下载优化IMAP 协议支持FetchProfile可以只拉取邮件头而不下载整个正文和附件这在邮件量大时能显著提速FetchProfile profile new FetchProfile(); profile.add(FetchProfile.Item.ENVELOPE); profile.add(FetchProfile.Item.FLAGS); folder.fetch(messages, profile);先 fetch 信封信息发件人、主题、日期用户点开某封时再按需拉取正文。如果只想要正文不想要附件可以在解析时跳过Part.ATTACHMENT类型或者用part.getInputStream()时限制读取字节数。这些优化在邮件系统设计里属于进阶内容但一旦邮件量上来不做的话内存和带宽都会吃不消。5. 避坑与排查JavaMail 落地时最容易翻车的五个点5.1 认证失败AuthenticationFailedException现象连接能建立但一认证就抛AuthenticationFailedException: 535 Error: authentication failed。原因通常有三个一是用了登录密码而不是授权码现在主流邮箱服务商都要求授权码二是账号没开启 SMTP/IMAP 服务需要在邮箱设置里手动打开三是mail.smtp.auth没设为 true或者Authenticator返回的密码为空。解决顺序是先确认服务已开启再用授权码替换密码最后检查props里auth参数。如果还不行把mail.debug打开看服务器返回的具体错误码535 是认证失败550 是发件人被拒。5.2 中文乱码主题、正文、附件名三处都要管现象收件人看到的主题是乱码或者正文正常但附件名是?UTF-8?B?...?。原因是编码设置不完整。主题要用setSubject(subject, UTF-8)正文的 content type 要写全text/html;charsetUTF-8附件名要MimeUtility.encodeText(name, UTF-8, null)。三处缺一处都会乱码。另外读取邮件时也要对应解码MimeUtility.decodeText用于文件名正文的getContent()一般会自动按声明的字符集解码但如果发件方声明有误可能需要手动用new String(content.getBytes(ISO-8859-1), UTF-8)转一次这是老邮件系统常见的兼容处理。5.3 连接超时线程卡死与超时参数缺失现象程序运行一段时间后线程池耗尽日志里大量线程停在SocketInputStream.read。原因是没设connectiontimeout、timeout、writetimeout对方服务器不响应时连接一直挂着。解决是在Properties里把这三个超时都设上建议 5000 到 10000 毫秒。另外Transport.send()内部会自己建立和关闭连接如果频繁发送建议改用Transport对象复用连接或者用连接池。注意Transport不是线程安全的多线程共享时要加锁或每个线程独立创建。5.4 被判定为垃圾邮件内容与频率双重因素现象邮件发出去了但对方收件箱里找不到垃圾箱里也没有或者直接进垃圾箱。原因分两类内容层面主题含敏感词、正文全是图片、HTML 里带大量外链都会提高垃圾评分频率层面短时间大量发送、收件人频繁退信会导致发件 IP 或域名被拉黑。解决上内容尽量保持文本和 HTML 双版本、控制图片比例、避免夸张营销词频率上做队列限速监控退信率。如果自建邮件服务器还要配 SPF、DKIM、DMARC 记录这部分超出 JavaMail 本身但做邮件系统绕不开。5.5 附件过大内存溢出与服务器拒收现象发送 20MB 以上附件时抛OutOfMemoryError或者服务器返回552 Message size exceeds fixed maximum message size。原因是FileDataSource会把整个文件读进内存且多数邮件服务器对单封邮件大小有限制常见 25MB 或 50MB。解决上大文件不要走邮件附件改成发下载链接如果必须发用流式BodyPart并控制并发。另外附件经过 Base64 编码后体积会膨胀约 33%所以 20MB 的文件实际传输量接近 27MB算大小的时候要把这个系数考虑进去。6. 验证与进阶怎么确认系统真的可靠跑通发送和接收只是第一步要确认这套 JavaMail 邮件系统真的可靠得有一套验证方法。我一般会分三层验证单元层、集成层、压力层。单元层用 GreenMail 这类嵌入式邮件服务器它能在本地起一个 SMTP/IMAP 服务不依赖外部邮箱测试用例里直接断言收到的邮件内容。这样 CI 环境也能跑不担心网络和授权码问题。集成层用真实邮箱服务商发一封到自己的测试邮箱人工确认主题、正文、附件、中文显示都正常。压力层则用队列灌入 1000 封邮件观察发送耗时、失败率、内存占用找出瓶颈。进阶用法上有几个方向值得投入。一是把Session和Transport做成 Spring Bean配合Async做异步发送避免阻塞主业务线程。二是引入模板引擎如 Thymeleaf、Freemarker生成 HTML 正文把邮件内容和代码分离改文案不用重新编译。三是做发送日志和重试机制记录每封邮件的状态失败的进重试队列这对通知类系统是刚需。四是收信端做增量拉取用UIDFolder记录上次拉取的最大 UID下次只拉新邮件避免每次全量遍历。下面是一个用UIDFolder做增量拉取的片段思路是记录上次处理的最大 UID下次只取比它大的UIDFolder uidFolder (UIDFolder) folder; UID[] uids uidFolder.getUIDs(messages[0], messages[messages.length - 1]); long lastUid readLastUidFromDb(); // 从数据库或文件读取 for (int i 0; i uids.length; i) { if (uids[i].uid lastUid) { Message msg uidFolder.getMessageByUID(uids[i].uid); // 处理新邮件 process(msg); lastUid uids[i].uid; } } saveLastUidToDb(lastUid); // 处理完持久化这个模式在邮件量大的场景下能把每次拉取的耗时从几十秒降到几百毫秒。我自己的习惯是任何涉及外部服务的模块上线前一定要把超时、重试、日志三件套配齐JavaMail 尤其如此——它的异常信息有时候很含糊没有足够的日志根本定位不到问题。另外授权码这类敏感信息不要硬编码在代码里走配置中心或环境变量这是安全底线。希望帮到你。本文还有配套的精品资源点击获取