JavaMail邮件系统实战：SMTP发信、IMAP收信与MIME附件解析

简介：这份PDF面向软件工程、计算机专业学生及Java初学者，围绕基于JavaMail的电子邮件系统课程设计展开，帮助读者理解邮件客户端与服务器端的完整设计思路。内容涵盖SMTP、POP3、IMAP三大协议的工作机制，MIME对附件与多内容类型的格式规范，以及JavaMail API中Session、Store、Folder、Message、Transport等核心类的职责与调用关系，并延伸至客户端登录、邮件收发、邮件夹管理、过滤搜索与安全传输等实现要点。资源包共1个PDF文件，约1.97MB，为课程设计报告文档，包含系统分析、总体框图、协议说明与类结构讲解，适合作为课设参考或自学Java邮件开发的入门材料。目前已有415人学习，可帮助读者快速建立邮件系统整体认知，对照报告梳理设计流程与关键知识点。

1. 从一份 2009 年的 JavaMail 课程设计说起：它到底能跑通什么

翻到这份《基于 JavaMail 电子邮件系统的设计（含源文件）》，第一反应不是"又一个课设"，而是它把邮件系统里最容易含糊的那条链路——客户端登录、SMTP 发信、POP3/IMAP 收信、MIME 附件解析——用一套能编译运行的 JSP + Servlet 代码完整串了一遍。它解决的不是"教你写个能发邮件的工具类"这种小打小闹，而是一个带登录模块、收件箱列表、附件上传下载、文件夹管理的 B/S 结构邮件客户端。适合谁？正在做 Java 课程设计、需要一份能讲清协议分层和模块划分的参考实现的人；也适合已经会调Transport.send()但说不清Store、Folder、Message三者关系、想补上"邮件系统整体长什么样"这块认知的开发者。它用的是 JDK 时代的mail.jar+activation.jar，跑在 Tomcat 上，前端是 JSP，这套技术栈今天看确实老，但协议层的东西没过时，坑也还是那些坑。

2. JavaMail 核心类与协议选型：Session、Store、Folder 到底谁管谁

2.1 先分清 SMTP、POP3、IMAP 三者的职责边界

很多人写邮件功能翻车，根源是把"发"和"收"混在一个连接里想。这份设计里把服务器拆成发送服务器（SMTP）和接收服务器（POP3/IMAP），这个拆分是对的，也是理解 JavaMail 的起点。

SMTP 只负责"把邮件从 A 推到 B"，它是推送模型，你连上 SMTP 服务器、投递、断开，事情就结束了。POP3 是拉取模型，客户端主动连上去把邮件下载到本地，下载完服务器上通常就删了（取决于配置），所以它天然不适合多设备同步。IMAP 也是拉取，但邮件留在服务器上，客户端只是拿一份视图，支持只下摘要、选择性下附件、在服务器上建文件夹。这份课设选了 IMAP 作为接收协议，props.put("mail.store.protocol", "imap")，这是它比只写 POP3 的版本更值得看的地方——因为后面那些"文件夹管理""保存到服务器"的功能，只有 IMAP 撑得起来。

MIME 不是协议，是格式规范。RFC822 只允许 ASCII 纯文本，MIME 在它基础上扩展出附件、多部分正文、非 ASCII 编码。你发一个带 Word 附件的邮件，实际发出去的是一个multipart/mixed结构，里面一段是正文，一段是 base64 编码的附件。理解这一点，后面解析附件才不会懵。

2.2 Session 是入口，Store 管收，Transport 管发

JavaMail 的类关系，用一句话概括：Session是全局配置和入口，Store代表接收端的存储空间，Transport代表发送通道，Folder是 Store 里的文件夹，Message是文件夹里的一封邮件。

初始化顺序在课设里写得很清楚，我把它整理成可直接抄的骨架：

// 1. 配置属性：发送走 smtp，接收走 imap Properties props = new Properties(); props.put("mail.transport.protocol", "smtp"); props.put("mail.store.protocol", "imap"); props.put("mail.smtp.class", "com.sun.mail.smtp.SMTPTransport"); props.put("mail.imap.class", "com.sun.mail.imap.IMAPStore"); props.put("mail.smtp.host", hostname); // SMTP 服务器地址 props.put("mail.smtp.auth", "true"); // 多数服务器要求认证 // 2. 拿 Session 实例 Session mailsession = Session.getDefaultInstance(props); // 3. 拿 Store 并连接接收服务器 Store store = mailsession.getStore("imap"); store.connect(hostname, username, password);

参数说明：mail.transport.protocol决定Transport.send()用哪个协议；mail.store.protocol决定getStore()默认返回哪种 Store；mail.smtp.class和mail.imap.class是允许第三方替换实现的钩子，一般不用改，但知道它存在，遇到"类找不到"的报错时能定位。mail.smtp.host是发送服务器地址，注意它和接收服务器地址经常不是同一台。

Session.getDefaultInstance()和Session.getInstance()的区别是个经典坑：前者会缓存第一次的配置，同一个 JVM 里第二次调用如果传了不同 props，可能拿到旧配置。多账户场景一定用getInstance()。

2.3 发信与收信的最小可运行代码

发信部分，课设里用的是Transport.send(msg)静态方法，简单但有局限——它每次新建连接。生产里更常见的是自己拿 Transport 复用连接：

// 构造邮件 MimeMessage msg = new MimeMessage(mailsession); msg.setFrom(new InternetAddress(fromAddr)); msg.setRecipients(Message.RecipientType.TO, InternetAddress.parse(toAddr, false)); msg.setSubject("hello"); msg.setText("How are you"); // 纯文本正文 // 发送 Transport.send(msg);

收信部分，打开 inbox 并读取：

Folder folder = store.getFolder("inbox"); folder.open(Folder.READ_ONLY); // 只读模式，不改服务器状态 System.out.println("总数：" + folder.getMessageCount()); System.out.println("未读：" + folder.getUnreadMessageCount()); Message msg = folder.getMessage(1); // 注意：索引从 1 开始 System.out.println("From: " + msg.getFrom()[0]); System.out.println("Subject: " + msg.getSubject()); System.out.println("Text: " + msg.getText());

这里有两个必须记住的点：folder.getMessage(i)的索引是1-based，不是 0；getText()对纯文本邮件有效，但遇到multipart邮件会返回空或抛异常，得用getContent()判断类型再解析。课设里PMessage类对Message做了二次封装，把getTo()返回的Address[]转成字符串方便 JSP 显示，这个封装思路是对的——原始 API 返回数组，直接丢给页面会很难看。

3. 把课设跑起来：环境、依赖与五个模块的落地顺序

3.1 环境与依赖：mail.jar 和 activation.jar 一个都不能少

这套代码是 JDK 自带 JavaMail 之前的产物，所以必须手动引入两个 jar：mail.jar（JavaMail API 及实现）和activation.jar（处理 MIME 类型和数据源，JavaMail 依赖它）。只加mail.jar会在处理附件时报ClassNotFoundException: javax.activation.DataHandler，这是血泪经验里最常见的一条。

环境清单：

部署时把两个 jar 放进WEB-INF/lib，不要只放 Tomcat 的lib，否则项目换容器就崩。

3.2 五个模块的落地顺序与文件对应

课设把系统分成登录、接收邮件和附件、发送和回复、邮件处理、文件夹管理五个模块，对应 JSP 文件。按依赖关系，落地顺序应该是：

第一步，登录模块（login.jsp）。它负责选服务器、填邮箱地址和密码，验证通过后把用户 ID 存进session变量，后续模块都从这里取。这一步的核心是store.connect()成功与否，失败要给出明确错误，而不是白屏。

第二步，接收邮件和附件模块（showmessage.jsp）。连上 IMAP 后列出邮件，附件要能下载保存到本地。这里的关键是判断邮件是否为multipart：

Object content = msg.getContent(); if (content instanceof Multipart) { Multipart mp = (Multipart) content; for (int i = 0; i < mp.getCount(); i++) { BodyPart part = mp.getBodyPart(i); // 附件通常有文件名，正文没有 if (part.getFileName() != null) { InputStream is = part.getInputStream(); // 保存到本地或转发给下载 } } }

第三步，发送和回复模块（compose.jsp）。编写新邮件、上传附件、发送。附件上传走的是 Servlet 的文件上传，上传到服务器临时目录后再作为MimeBodyPart附加到邮件上。

第四步，邮件处理模块（listonefoldr.jsp）。显示邮件列表、删除选中邮件、显示错误信息。删除要注意：IMAP 下删除只是打标记，得调用folder.expunge()才真正生效。

第五步，文件夹管理。新建、重命名、删除文件夹，全部通过Store和Folder的 API 完成，比如store.getFolder("新文件夹").create(Folder.HOLDS_MESSAGES)。

3.3 用 UML 建模理清模块边界

课设里给了用例图、时序图、协作图、类图、活动图、组件图，这套 UML 不是摆设。用例图把 User 泛化成 Sender 和 Receiver，直接对应到"发送"和"接收"两条主线；时序图把"登录→存 session→发/收"的调用顺序画清楚了，照着它写代码不会漏掉 session 传递这一步；类图里PMessage和MailUserData两个类，前者封装 Message 的显示逻辑，后者管用户信息和邮件操作，职责划分清晰。如果你要改这个课设，先看类图，改哪个类心里有数。

4. 避坑与排查：那些让课设跑不起来的常见问题

4.1 认证失败：535 Authentication failed

现象：store.connect()或Transport.send()抛AuthenticationFailedException，提示 535。

原因：多数 SMTP 服务器要求认证，但代码里没设mail.smtp.auth=true，或者用户名密码传错，或者服务器要求用授权码而非登录密码。

解决：加上props.put("mail.smtp.auth", "true")，并在Session里传入Authenticator；确认用的是邮箱服务商给的授权码。注意Session.getDefaultInstance(props, authenticator)这个重载，别只传 props。

4.2 附件乱码或文件名变成一串编码

现象：收到的附件文件名是=?UTF-8?B?xxx?=这种，或者中文文件名乱码。

原因：MIME 对非 ASCII 文件名要做编码，MimeBodyPart.setFileName()在旧版本不会自动编码。

解决：用MimeUtility.encodeText(fileName)手动编码文件名，读取时用MimeUtility.decodeText(part.getFileName())解码。这是 MIME 规范里 RFC2047 的要求，不是 bug。

4.3 getText() 返回空：multipart 邮件不能直接取正文

现象：msg.getText()对带附件的邮件返回空字符串或抛MessagingException。

原因：带附件的邮件是multipart/mixed结构，getText()只对text/plain单部分有效。

解决：先msg.getContent() instanceof Multipart判断，是则遍历BodyPart，找到text/plain或text/html的那一部分再取内容。别偷懒直接getText()。

4.4 索引越界：getMessage(0) 报错

现象：folder.getMessage(0)抛IndexOutOfBoundsException。

原因：JavaMail 的Folder.getMessage(int)索引从 1 开始，不是 0。

解决：循环从 1 到folder.getMessageCount()。这个坑几乎每个第一次用 JavaMail 的人都踩过。

4.5 删除邮件后还在：忘了 expunge

现象：调用msg.setFlag(Flags.Flag.DELETED, true)后，邮件还在列表里。

原因：IMAP 下删除只是打DELETED标记，需要显式提交。

解决：删除后调用folder.expunge()，或者关闭时用folder.close(true)自动 expunge。注意READ_ONLY模式下不能删除，得用READ_WRITE打开。

5. 进阶技巧：从课设代码到能用的邮件客户端还差什么

课设代码能跑通基本流程，但离"能用"还有距离。第一个要补的是连接复用。Transport.send()每次新建连接，发多封邮件时开销大。常见做法是自己拿Transport：

Transport transport = mailsession.getTransport("smtp"); transport.connect(hostname, username, password); transport.sendMessage(msg, msg.getAllRecipients()); transport.close();

第二个是分页与懒加载。课设里listonefoldr.jsp一次性列出所有邮件，邮件一多页面就卡。IMAP 支持只取邮件头（Folder.fetch()配合FetchProfile），先拿主题、发件人、日期，点开某封再取正文，这个优化对体验提升很明显。

第三个是字符集统一。JSP 页面、邮件正文、附件文件名三处的编码要一致，建议全用 UTF-8，msg.setSubject(subject, "UTF-8")、msg.setText(body, "UTF-8")都显式指定，别依赖默认值。

第四个是异常分类处理。MessagingException是个大类，认证失败、连接超时、文件夹不存在都抛它。按getNextException()或具体子类区分，给用户不同的提示，比统一报"操作失败"有用得多。

验证方法上，我一般会用一个真实邮箱账户，先发一封纯文本给自己，再发一封带中文附件和中文主题的，最后在客户端里收下来，检查主题、正文、附件名三处是否都正常。这三步过了，基本功能就稳了。

从那以后我每次碰 JavaMail，都强制先确认两件事：activation.jar在不在，getMessage的索引是不是从 1 开始。这两个点看着小，但翻车率极高。希望帮到你。

本文还有配套的精品资源，点击获取