現(xiàn)郵件發(fā)送：Servlet+JavaMail從零搭建)
1. 項(xiàng)目概述1.1 這個(gè)需求背后的真實(shí)場(chǎng)景說到Java Web發(fā)郵件很多剛?cè)胄械耐瑢W(xué)第一反應(yīng)是拿個(gè)Spring Boot項(xiàng)目加個(gè)starter填幾個(gè)配置一個(gè)JavaMailSender注入進(jìn)來就能跑了。但如果你還在學(xué)原生Servlet、JSP的老一套技術(shù)?；蛘吣闼陧?xiàng)目有盡量不引入框架依賴的約束那原生Java Web實(shí)現(xiàn)郵件發(fā)送這個(gè)需求就會(huì)突然變得不那么輕松。我這次做的東西就是在這個(gè)背景下展開的一個(gè)純Servlet JavaMail API實(shí)現(xiàn)的郵件發(fā)送功能頁面提交表單后端接到請(qǐng)求后通過SMTP協(xié)議把郵件發(fā)出去。沒有Spring沒有Maven插件沒有一堆自動(dòng)配置每一步都手動(dòng)拼起來。這種做法的價(jià)值在于它能讓你真正理解一封郵件從瀏覽器表單到對(duì)方收件箱之間到底經(jīng)歷了哪些環(huán)節(jié)而不是被框架的黑盒隱藏起來。這套代碼適合誰參考三類人第一類是正在學(xué)Java Web、想搞明白Servlet如何承接請(qǐng)求并完成任務(wù)的同學(xué)第二類是在校做課程設(shè)計(jì)、需要一個(gè)完整可演示的郵件發(fā)送模塊的開發(fā)者第三類是工作中遇到了不能用框架、必須原生實(shí)現(xiàn)這種約束需要快速落地的工程師?？赐赀@篇文章你能拿到可以直接跑起來的源碼也能明白文件編碼問題、SMTP認(rèn)證失敗、端口不通這些坑是怎么踩出來的。1.2 準(zhǔn)備聊哪些內(nèi)容文章會(huì)分為這樣幾個(gè)部分先說郵件發(fā)送涉及的基礎(chǔ)知識(shí)——SMTP協(xié)議是什么、JavaMail API和它的依賴關(guān)系然后講我如何規(guī)劃項(xiàng)目結(jié)構(gòu)和關(guān)鍵配置接著給出完整源碼逐段拆解發(fā)送邏輯再聊Servlet如何接入Http請(qǐng)求以及JSP頁面上的表單細(xì)節(jié)最后把實(shí)際開發(fā)中遇到的典型問題和排查思路整理成清單。每個(gè)段落都會(huì)附帶我在動(dòng)手過程中的實(shí)際操作記錄和經(jīng)驗(yàn)體會(huì)不是純理論都是可復(fù)現(xiàn)的步驟。2. 郵件發(fā)送的核心機(jī)制與JavaMail選型2.1 SMTP協(xié)議到底是干什么的郵件發(fā)送這件事本質(zhì)上就是你的程序作為郵件客戶端把一封構(gòu)造好的郵件扔給一臺(tái)SMTP服務(wù)器再由這臺(tái)服務(wù)器負(fù)責(zé)把郵件投遞到收件人的郵件服務(wù)器上。整個(gè)過程遵循SMTP協(xié)議——Simple Mail Transfer Protocol簡(jiǎn)單郵件傳輸協(xié)議。它定義了兩臺(tái)服務(wù)器之間、客戶端與服務(wù)器之間的對(duì)話規(guī)則。你可以把SMTP服務(wù)器想象成一個(gè)快遞中轉(zhuǎn)站。你寫好了包裹郵件填好了收件人地址收件郵箱然后把它交給中轉(zhuǎn)站SMTP服務(wù)器中轉(zhuǎn)站根據(jù)地址去投遞。如果收件人郵箱恰好也在同一家中轉(zhuǎn)站的管轄范圍那它直接投進(jìn)對(duì)方信箱如果不在它會(huì)轉(zhuǎn)交給下一個(gè)中轉(zhuǎn)站。發(fā)郵件這個(gè)動(dòng)作從用戶視角看只是點(diǎn)了發(fā)送按鈕但背后經(jīng)歷了至少一次TCP連接、一次身份認(rèn)證通常需要、一次郵件數(shù)據(jù)傳輸。第三方免費(fèi)郵箱提供的SMTP服務(wù)器通常會(huì)在服務(wù)器上開一個(gè)認(rèn)證機(jī)制。你用自己的郵箱賬號(hào)去登錄對(duì)方服務(wù)器通過驗(yàn)證之后才允許發(fā)信。這也是為什么實(shí)際開發(fā)中你幾乎不可能只寫代碼就能把郵件發(fā)出去——你必須有一個(gè)真實(shí)的、開啟了SMTP服務(wù)權(quán)限的郵箱賬戶。大多數(shù)主流郵箱廠商默認(rèn)不開放這個(gè)功能需要你手動(dòng)在設(shè)置里開啟SMTP/POP3/IMAP服務(wù)然后生成一個(gè)授權(quán)碼而非直接使用登錄密碼。這個(gè)細(xì)節(jié)非常關(guān)鍵我第一次測(cè)試時(shí)用賬號(hào)密碼直接認(rèn)證服務(wù)器返回535錯(cuò)誤查了半天才意識(shí)到要用授權(quán)碼。2.2 JavaMail API的結(jié)構(gòu)與依賴Java原生發(fā)郵件依賴的核心API是javax.mail包這是JavaEE規(guī)范中JavaMail的一部分。它不是JDK自帶的需要額外引入兩個(gè)JAR包mail.jar提供Session、Message、Transport等主要類activation.jar處理MIME類型數(shù)據(jù)的輔助包比如附件、圖片內(nèi)嵌這類二進(jìn)制的數(shù)據(jù)如果你的項(xiàng)目用Maven管理依賴引入這兩個(gè)坐標(biāo)就行但如果是原生Servlet項(xiàng)目、沒有Maven那你得手動(dòng)把JAR包放在WEB-INF/lib目錄下。我在開發(fā)時(shí)使用的是最傳統(tǒng)的手動(dòng)部署方式——自己在本地下載了mail.jar和activation.jar放在lib目錄然后讓Tomcat在啟動(dòng)時(shí)加載它們。這種方式的好處是完全可控不用依賴網(wǎng)絡(luò)構(gòu)件倉庫對(duì)課程設(shè)計(jì)或者內(nèi)網(wǎng)開發(fā)環(huán)境非常友好。JavaMail API工作的核心對(duì)象有三個(gè)Session整個(gè)郵件會(huì)話的配置中心持有服務(wù)器地址、端口、認(rèn)證開關(guān)、網(wǎng)絡(luò)超時(shí)這些參數(shù)MimeMessage代表一封郵件負(fù)責(zé)組裝發(fā)件人、收件人、主題、正文、附件Transport真正把MimeMessage發(fā)給SMTP服務(wù)器并完成數(shù)據(jù)傳輸?shù)耐ǖ肋@三者的關(guān)系可以簡(jiǎn)化理解為一個(gè)類似快遞流程你(Session)約好了快遞公司SMTP服務(wù)器的規(guī)矩填好快遞單MimeMessage然后交給快遞員Transport帶走。在后面的代碼部分你就能看到這三者依次登場(chǎng)。2.3 為什么不用第三方SDK而自己寫現(xiàn)在很多云服務(wù)商提供了HTTP接口發(fā)郵件的SDK比如通過API密鑰調(diào)用發(fā)信接口代碼量更小、送達(dá)率也更高。那為什么我這次堅(jiān)持用原生JavaMail原因很簡(jiǎn)單題目要求是原生JavaWeb實(shí)現(xiàn)這是技術(shù)學(xué)習(xí)路徑上必須走的一步。用云服務(wù)商的SDK屏蔽了底層的SMTP交互學(xué)習(xí)價(jià)值大打折扣。而手工寫JavaMail代碼你能看清SMTP服務(wù)器的連接是Socket層面的TCP通信郵件內(nèi)容本質(zhì)上是MIME格式的文本數(shù)據(jù)附件是多段MIME結(jié)構(gòu)拼接起來的這些底層認(rèn)知對(duì)于將來調(diào)試復(fù)雜的郵件問題——比如附件格式錯(cuò)亂、郵件被識(shí)別為垃圾內(nèi)容——會(huì)提供很大的幫助。當(dāng)然如果項(xiàng)目上線到生產(chǎn)環(huán)境我的建議還是優(yōu)先用成熟的郵件服務(wù)商或者企業(yè)內(nèi)部郵件服務(wù)器原生JavaMail更適合學(xué)習(xí)和可控的自建場(chǎng)景。后者在投遞成功率、反垃圾評(píng)分上靠的是背后整個(gè)基礎(chǔ)設(shè)施的積累。3. 項(xiàng)目結(jié)構(gòu)和基礎(chǔ)配置準(zhǔn)備3.1 項(xiàng)目目錄怎么組織我這次的項(xiàng)目結(jié)構(gòu)完全按照Servlet規(guī)范的標(biāo)準(zhǔn)布局來沒有多余的花架子。核心文件有這些mail-demo/ ├── src/ │ └── com/example/mail/ │ ├── MailSender.java // 郵件發(fā)送核心邏輯 │ ├── SendMailServlet.java // 接收表單請(qǐng)求的Servlet │ └── MailConfig.java // 郵件配置常量服務(wù)器、賬號(hào)、授權(quán)碼 ├── web/ │ ├── WEB-INF/ │ │ ├── lib/ │ │ │ ├── mail.jar │ │ │ └── activation.jar │ │ └── web.xml │ └── sendMail.jsp // 發(fā)送頁面這個(gè)結(jié)構(gòu)是手動(dòng)建出來的沒有用IDE的Web項(xiàng)目向?qū)?。之所以手?dòng)搭是因?yàn)楹芏喑鯇W(xué)者在IDE里點(diǎn)新建Dynamic Web Project時(shí)會(huì)面臨各種版本兼容的選項(xiàng)錯(cuò)誤反而不如自己動(dòng)手創(chuàng)建目錄、自己寫web.xml來得清晰。當(dāng)然你在IDEA里用Project Structure新建Web項(xiàng)目也是可以的只要保證最終部署出來的目錄結(jié)構(gòu)滿足Servlet規(guī)范即可。還有一點(diǎn)要提前說清楚WEB-INF目錄下的東西是Web容器保護(hù)的外部不能通過URL直接訪問。所以mail.jar和activation.jar放在WEB-INF/lib下能被Tomcat自動(dòng)加載而用戶無法通過http://ip:8080/mail-demo/mail.jar下載到它。這個(gè)機(jī)制是Servlet規(guī)范定義的保證依賴庫的私密性。3.2 需要的JAR包怎么獲取前面提到的兩個(gè)JAR包獲取途徑很常規(guī)。mail.jar可以在Oracle官網(wǎng)的JavaMail頁面下載也可以從Maven中央倉庫直接下載jar包文件。activation.jar同樣可以在Maven中央倉庫獲取搜索javax.activation即可。需要注意的是版本問題JavaMail版本建議選1.4.7這是公認(rèn)穩(wěn)定且資料多的版本activation建議選1.1.1。高版本的jakarta.mail是另一套命名空間jakarta.mail包跟傳統(tǒng)的javax.mail不兼容如果項(xiàng)目還是老式Servlet容器Tomcat 8/9那用javax.mail的命名空間就夠了不用追新。如果你用的是Maven直接在pom.xml中配置dependency groupIdjavax.mail/groupId artifactIdmail/artifactId version1.4.7/version /dependency dependency groupIdjavax.activation/groupId artifactIdactivation/artifactId version1.1.1/version /dependency這里有一個(gè)容易踩的坑不同版本的mail.jar依賴的activation.jar版本可能不同如果不匹配運(yùn)行時(shí)會(huì)出現(xiàn)ClassNotFoundException: com.sun.activation.registries.MailcapFile這類錯(cuò)誤。我自己的做法是干脆兩個(gè)JAR都從同一個(gè)來源下載比如Maven倉庫中的配套版本避免版本錯(cuò)位。3.3 關(guān)鍵配置參數(shù)解釋在做郵件發(fā)送之前先要摸清你選擇的郵箱服務(wù)商提供的基礎(chǔ)參數(shù)。不同的郵件服務(wù)商SMTP服務(wù)器地址和端口可能不一樣常見的配置模式有普通SSL加密模式smtp.xxx.com端口465需要開啟SSL升級(jí)TLS模式smtp.xxx.com端口587需要STARTTLS我實(shí)際操作時(shí)優(yōu)先使用465端口SSL模式因?yàn)?87端口在有些服務(wù)器環(huán)境下會(huì)被運(yùn)營(yíng)商封鎖或者郵件服務(wù)商默認(rèn)不允許非加密連接。465這種SSL直連模式更省事只需要在Properties設(shè)置mail.smtp.ssl.enabletrue即可。除了服務(wù)器和端口還要準(zhǔn)備好你的完整郵箱地址作為發(fā)件人地址授權(quán)碼在郵箱設(shè)置中開啟SMTP后生成的一串獨(dú)立密碼收件人郵箱測(cè)試時(shí)最好用另一個(gè)不同域名下的郵箱這樣能驗(yàn)證跨服務(wù)器投遞是否正常我給項(xiàng)目加了一個(gè)MailConfig類來統(tǒng)一存放這些常量避免在代碼里到處寫死。這個(gè)問題雖然簡(jiǎn)單但做得好不好直接影響后面維護(hù)的體驗(yàn)——我見過不少項(xiàng)目把郵箱密碼散落在七八個(gè)類里改一次授權(quán)碼要全局搜索非常痛苦。4. 核心代碼實(shí)現(xiàn)詳解4.1 MailSender類——郵件發(fā)送的骨架先給出這個(gè)類的完整代碼這是整個(gè)項(xiàng)目中最核心的部分package com.example.mail; import java.util.Properties; import javax.mail.Authenticator; import javax.mail.Message; import javax.mail.MessagingException; import javax.mail.PasswordAuthentication; import javax.mail.Session; import javax.mail.Transport; import javax.mail.internet.InternetAddress; import javax.mail.internet.MimeMessage; public class MailSender { public static void send(String to, String subject, String content) throws MessagingException { Properties props new Properties(); // SMTP服務(wù)器地址 props.put(mail.smtp.host, MailConfig.SMTP_HOST); // 端口 props.put(mail.smtp.port, MailConfig.SMTP_PORT); // 是否開啟認(rèn)證 props.put(mail.smtp.auth, true); // 是否開啟SSL props.put(mail.smtp.ssl.enable, true); // 設(shè)置超時(shí)時(shí)間避免服務(wù)器無響應(yīng)時(shí)客戶端卡死 props.put(mail.smtp.connectiontimeout, 10000); props.put(mail.smtp.timeout, 10000); Session session Session.getInstance(props, new Authenticator() { Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(MailConfig.USERNAME, MailConfig.AUTH_CODE); } }); // 打開調(diào)試模式方便觀察SMTP協(xié)議交互過程 session.setDebug(true); MimeMessage message new MimeMessage(session); message.setFrom(new InternetAddress(MailConfig.USERNAME)); message.addRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject, UTF-8); message.setContent(content, text/html;charsetUTF-8); Transport.send(message); } }這段代碼里值得逐行解釋的地方不少。先看Session.getInstance(props, authenticator)這一行props里配置了連接SMTP的所有參數(shù)而Authenticator是JavaMail用來獲取認(rèn)證憑據(jù)的接口。注意看我在這里返回的不是郵箱的登錄密碼而是AUTH_CODE授權(quán)碼。這個(gè)設(shè)計(jì)是JavaMail API的標(biāo)準(zhǔn)用法——通過PasswordAuthentication封裝用戶名和密碼/授權(quán)碼Transport在連接服務(wù)器時(shí)會(huì)自動(dòng)使用這組憑據(jù)做認(rèn)證。再看message.setSubject(subject, UTF-8)。這個(gè)方法的重載形式很多如果你直接調(diào)用setSubject(subject)主題會(huì)按默認(rèn)編碼處理中文大概率變成亂碼。我特意指定了UTF-8確保中英文都能正確編碼。同理正文通過setContent(content, text/html;charsetUTF-8)設(shè)置告訴收件人的郵件客戶端這是一封HTML格式、UTF-8編碼的郵件。如果你想要純文本格式把第二個(gè)參數(shù)改成text/plain;charsetUTF-8就行。還有一個(gè)容易被忽略的細(xì)節(jié)session.setDebug(true)。這行代碼平時(shí)沒存在感但當(dāng)你遇到郵件發(fā)不出去這種問題需要排查時(shí)它會(huì)幫你打印出客戶端和SMTP服務(wù)器之間的完整對(duì)話過程——包括DNS解析、TCP連接、EHLO指令、AUTH LOGIN認(rèn)證、MAIL FROM指令、RCPT TO指令、DATA指令以及服務(wù)器的每個(gè)響應(yīng)碼。我第一次排查認(rèn)證失敗問題時(shí)就是依靠這個(gè)輸出看到了服務(wù)器返回的錯(cuò)誤碼才定位到授權(quán)碼的問題。上線部署時(shí)記得把setDebug改成false否則會(huì)產(chǎn)生大量日志輸出。4.2 MailConfig類——統(tǒng)一管理配置有經(jīng)驗(yàn)的人寫代碼不會(huì)把配置參數(shù)分散在業(yè)務(wù)代碼里。我單獨(dú)抽了個(gè)MailConfig類package com.example.mail; public class MailConfig { // SMTP服務(wù)器地址 public static final String SMTP_HOST smtp.yourmailservice.com; // 端口SSL加密連接常用465 public static final String SMTP_PORT 465; // 發(fā)件人郵箱地址 public static final String USERNAME your_accountexample.com; // 授權(quán)碼不是登錄密碼 public static final String AUTH_CODE xxxxxxxxxxxxxx; }這個(gè)類的作用不言自明當(dāng)你的部署環(huán)境切換時(shí)比如從測(cè)試郵箱切換到公司內(nèi)部郵件服務(wù)器只需要改這一個(gè)文件當(dāng)授權(quán)碼過期需要替換時(shí)也只需要改這一個(gè)地方。這里有個(gè)建議如果你要把項(xiàng)目推到Git倉庫上務(wù)必在.gitignore中排除這個(gè)文件或者在提交前將真實(shí)授權(quán)碼替換成占位符——否則授權(quán)碼泄露別人就能用你的郵箱發(fā)郵件輕則被當(dāng)作垃圾郵件源重則影響郵箱安全。4.3 SendMailServlet——接收請(qǐng)求的核心入口Servlet在Java Web開發(fā)中扮演的角色就是接受HTTP請(qǐng)求、執(zhí)行業(yè)務(wù)邏輯、返回響應(yīng)視圖。我這里創(chuàng)建了一個(gè)SendMailServlet只負(fù)責(zé)接收頁面表單的POST請(qǐng)求并調(diào)用MailSenderpackage com.example.mail; import java.io.IOException; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; WebServlet(/sendMail) public class SendMailServlet extends HttpServlet { private static final long serialVersionUID 1L; Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { request.setCharacterEncoding(UTF-8); response.setContentType(text/html;charsetUTF-8); String to request.getParameter(to); String subject request.getParameter(subject); String content request.getParameter(content); if (to null || to.trim().isEmpty() || subject null || subject.trim().isEmpty()) { request.setAttribute(message, 收件人、主題不能為空); request.getRequestDispatcher(sendMail.jsp).forward(request, response); return; } try { MailSender.send(to.trim(), subject.trim(), content); request.setAttribute(message, 郵件發(fā)送成功); } catch (Exception e) { e.printStackTrace(); request.setAttribute(message, 郵件發(fā)送失敗 e.getMessage()); } request.getRequestDispatcher(sendMail.jsp).forward(request, response); } }注意編碼問題我在doPost第一行就設(shè)置了request.setCharacterEncoding(UTF-8)。這個(gè)調(diào)用必須在讀取任何請(qǐng)求參數(shù)之前執(zhí)行否則Tomcat會(huì)按默認(rèn)的ISO-8859-1來解碼POST請(qǐng)求體中文表單提交就會(huì)出現(xiàn)亂碼。這個(gè)細(xì)節(jié)初學(xué)者特別容易踩坑——我見過很多人在頁面已經(jīng)設(shè)置了UTF-8但后臺(tái)收到的參數(shù)依然是亂碼的情況原因就是漏了這行。另外我做了基本的非空校驗(yàn)只校驗(yàn)了收件人和主題沒對(duì)郵箱格式做正則校驗(yàn)。正常開發(fā)中收件人格式校驗(yàn)是很基本的——郵箱里注入垃圾內(nèi)容導(dǎo)致發(fā)信失敗事小如果將來做批量發(fā)送功能格式錯(cuò)誤可能引發(fā)異常退信。后面在升級(jí)篇中我會(huì)展示一個(gè)簡(jiǎn)單的驗(yàn)證方式。4.4 sendMail.jsp——前端提交界面最后需要一個(gè)交互頁面。我這里用JSP實(shí)現(xiàn)通過簡(jiǎn)單的HTML表單提交數(shù)據(jù)% page contentTypetext/html;charsetUTF-8 languagejava % html head title郵件發(fā)送/title style body { font-family: Microsoft YaHei, sans-serif; background: #f5f5f5; } .container { width: 600px; margin: 50px auto; background: #fff; padding: 30px; border-radius: 8px; } label { display: block; margin-top: 15px; font-weight: bold; } input[typetext], textarea { width: 100%; padding: 8px; margin-top: 5px; border: 1px solid #ccc; border-radius: 4px; } textarea { height: 120px; } button { margin-top: 20px; padding: 10px 30px; background: #409eff; color: #fff; border: none; border-radius: 4px; cursor: pointer; } /style /head body div classcontainer h2發(fā)送郵件/h2 p stylecolor: red;${message}/p form actionsendMail methodpost label收件人郵箱/label input typetext nameto placeholdersomeoneexample.com label郵件主題/label input typetext namesubject placeholder郵件主題 label郵件內(nèi)容/label textarea namecontent placeholder請(qǐng)輸入郵件正文內(nèi)容/textarea button typesubmit發(fā)送/button /form /div /body /html表單的提交方式必須是post因?yàn)猷]件發(fā)送會(huì)改變服務(wù)器狀態(tài)而且郵件主題和正文可能包含較長(zhǎng)的內(nèi)容POST在數(shù)據(jù)大小限制和語義上都更合適。表單的action指向sendMail這個(gè)映射在Servlet代碼中是通過WebServlet(/sendMail)注解定義的——如果用低版本的Servlet容器注解可能不支持你需要再去web.xml里聲明Servlet映射我這次使用的是Servlet 3.0直接走注解。頁面上用了${message}來顯示后端返回的結(jié)果這要求JSP默認(rèn)支持EL表達(dá)式。大部分Tomcat配置都是支持的如果顯示原樣${message}那是開了忽略EL的配置可以在JSP頂部加% page isELIgnoredfalse %解決。5. 部署運(yùn)行與完整驗(yàn)證流程5.1 部署到Tomcat部署過程我是這樣操作的先確保本地已經(jīng)安裝了Tomcat 8或9然后把整個(gè)項(xiàng)目導(dǎo)出為WAR包或者直接把項(xiàng)目目錄丟到Tomcat的webapps目錄下。如果你用的是IDEA可以在Run Configuration里配置Tomcat Server把項(xiàng)目部署到Tomcat后點(diǎn)擊運(yùn)行。啟動(dòng)過程中有幾點(diǎn)要特別注意Tomcat啟動(dòng)時(shí)會(huì)在日志中打印部署信息如果WEB-INF/lib下的JAR包沒有正確加載你會(huì)看到ClassNotFoundException異常那多半是lib目錄路徑不對(duì)或者JAR包缺失如果出現(xiàn)端口占用檢查是否有其他Tomcat實(shí)例在運(yùn)行可以在conf/server.xml中改端口瀏覽器訪問路徑通常是http://localhost:8080/mail-demo/sendMail.jsp這里mail-demo是你的上下文路徑也就是WAR包名或項(xiàng)目名啟動(dòng)完成后頁面能正常顯示就可以開始測(cè)試發(fā)送了。5.2 功能驗(yàn)證步驟我的驗(yàn)證流程是這樣的開兩個(gè)郵箱一個(gè)作為發(fā)件方一個(gè)作為收件方兩個(gè)郵箱都用不同域名這樣才能檢驗(yàn)跨服務(wù)器投遞。然后我在頁面上分別填寫收件人recipientotherdomain.com主題JavaMail原生發(fā)送測(cè)試內(nèi)容h2這是HTML內(nèi)容/h2p這是一封來自原生JavaWeb項(xiàng)目的郵件。/p點(diǎn)擊發(fā)送后如果頁面顯示郵件發(fā)送成功再去看收件方郵箱是否收到。為了確認(rèn)整個(gè)鏈路完整我在MailSender中開著setDebug(true)控制臺(tái)會(huì)打印出一大段SMTP協(xié)議交互日志。關(guān)鍵的日志片段類似DEBUG SMTP: Connected to host: smtp.xxx.com, port: 465 DEBUG SMTP: AUTH LOGIN command mixed with SSL DEBUG SMTP: Use 8bit NTLM DEBUG SMTP: AUTH LOGIN succeeded DEBUG SMTP: MAIL FROM:your_accountexample.com DEBUG SMTP: RCPT TO:recipientotherdomain.com DEBUG SMTP: DATA當(dāng)看到AUTH LOGIN succeeded和RCPT TO成功返回時(shí)基本可以判斷郵件已經(jīng)進(jìn)入投遞流程。等收件方郵箱收到郵件說明整個(gè)鏈路是通的。5.3 控制臺(tái)日志怎么看很多同學(xué)面對(duì)一大段Debug日志會(huì)發(fā)懵我在這里簡(jiǎn)單說一下怎么看。SMTP協(xié)議的命令都是有跡可循的220開頭的行服務(wù)器打招呼說明TCP連接成功250開頭的行請(qǐng)求被接受比如EHLO、MAIL FROM、RCPT TO成功334開頭的行服務(wù)器要求提供認(rèn)證信息用戶名/密碼235開頭的行認(rèn)證成功535開頭的行認(rèn)證失敗常見原因是授權(quán)碼錯(cuò)誤554開頭的行發(fā)送被拒絕可能是內(nèi)容觸發(fā)反垃圾策略把這幾個(gè)狀態(tài)碼記住絕大多數(shù)郵件發(fā)送問題都能在日志中直接定位。我也是用這個(gè)方法調(diào)通了整個(gè)項(xiàng)目后面要分享的幾個(gè)坑也全都靠日志才排查清楚。6. 常見問題與排查技巧實(shí)錄6.1 授權(quán)碼錯(cuò)誤的經(jīng)典報(bào)錯(cuò)第一次測(cè)試時(shí)我在發(fā)件人配置中填了真正的郵箱登錄密碼結(jié)果控制臺(tái)打出如下錯(cuò)誤javax.mail.AuthenticationFailedException: 535 Error: authentication failed排查步驟很簡(jiǎn)單先確認(rèn)郵箱是否已開啟SMTP服務(wù)再確認(rèn)授權(quán)碼是否有效。多數(shù)郵箱開啟SMTP服務(wù)后會(huì)明確提示授權(quán)碼僅顯示一次, 需要妥善保存如果遺忘了只能重新生成。把配置里的AUTH_CODE換成新授權(quán)碼問題就解決了。這是一個(gè)很多人會(huì)犯的錯(cuò)誤因?yàn)榈卿浢艽a和授權(quán)碼是兩個(gè)不同的東西登錄密碼只能在網(wǎng)頁Web端使用授權(quán)碼是專門提供給第三方客戶端使用的。所以拿到一個(gè)發(fā)不出去郵件的報(bào)錯(cuò)先別慌著改代碼先檢查認(rèn)證憑據(jù)。6.2 端口不通的排查記錄另一次測(cè)試中我配置了SMTP端口為25這是SMTP協(xié)議的默認(rèn)端口但在部分網(wǎng)絡(luò)環(huán)境下25端口會(huì)被ISP封鎖日志顯示連接超時(shí)java.net.ConnectException: Connection timed out: connect排查方法是先用telnet smtp.xxx.com 25測(cè)試端口連通性。如果telnet連接不了果斷換成465或587端口。服務(wù)器防火墻規(guī)則、云服務(wù)商安全組這些網(wǎng)絡(luò)層面因素都可能導(dǎo)致端口不通。實(shí)際使用時(shí)我用465端口一切正常25端口則出現(xiàn)超時(shí)。這里有個(gè)經(jīng)驗(yàn)如果你部署在云服務(wù)器上還要檢查安全組規(guī)則是否放行了對(duì)應(yīng)出方向端口。大部分云廠商默認(rèn)放行所有出方向端口但在部分企業(yè)內(nèi)網(wǎng)環(huán)境需要向網(wǎng)絡(luò)管理員申請(qǐng)開通。6.3 中文亂碼問題根因分析中文亂碼是另一個(gè)高頻問題。問題出現(xiàn)的現(xiàn)象是收件方收到郵件后主題顯示問號(hào)或亂碼正文中的中文也成了亂碼。根因在于編碼設(shè)置不一致。處理方法就是我前面代碼中體現(xiàn)的JSP頁面聲明UTF-8表單提交前使用UTF-8編碼Servlet中調(diào)用request.setCharacterEncoding(UTF-8)在讀取參數(shù)之前執(zhí)行setSubject指定UTF-8參數(shù)setContent聲明text/html;charsetUTF-8四個(gè)環(huán)節(jié)缺一不可。我在JSP頁面里還特意給表單加了accept-charsetUTF-8屬性雖然現(xiàn)代瀏覽器默認(rèn)會(huì)按頁面編碼提交但多這一層保險(xiǎn)總沒有壞處。另外一個(gè)隱蔽的坑是如果你的項(xiàng)目部署在Windows服務(wù)器上系統(tǒng)默認(rèn)字符集是GBK某些文件的編碼如果被IDE用系統(tǒng)默認(rèn)字符集保存了JSP編譯出來就會(huì)出亂碼。這種情況可以在server.xml中的Connector標(biāo)簽添加URIEncodingUTF-8屬性確保GET請(qǐng)求參數(shù)的編碼也正確。6.4 頻繁發(fā)送觸發(fā)限流策略測(cè)試時(shí)如果短時(shí)間內(nèi)連續(xù)發(fā)送多封郵件可能會(huì)觸發(fā)郵箱服務(wù)商的反垃圾策略。服務(wù)器會(huì)返回類似這樣的錯(cuò)誤554 Transaction failed這時(shí)不能繼續(xù)重試否則可能被封禁發(fā)信權(quán)限。正確做法是放慢發(fā)送頻率每次間隔至少一兩分鐘如果是正式項(xiàng)目需要批量發(fā)送建議設(shè)計(jì)異步隊(duì)列控制發(fā)送速率和日發(fā)送量上限。個(gè)人郵箱的日發(fā)送配額通常有限不建議拿個(gè)人郵箱做大規(guī)模生產(chǎn)發(fā)信。6.5 常見錯(cuò)誤碼速查表為了方便排查我把一些常見問題整理成了表格現(xiàn)象可能原因解決思路535認(rèn)證失敗授權(quán)碼錯(cuò)誤重新生成授權(quán)碼并更新配置Connection timed out端口不通、防火墻攔截telnet測(cè)試端口更換465端口Could not connect to SMTP host服務(wù)器地址配置錯(cuò)誤檢查郵箱服務(wù)商SMTP地址550 Mailbox not found收件人地址不存在確認(rèn)收件人郵箱拼寫554 Transaction failed內(nèi)容觸發(fā)反垃圾策略降低發(fā)送頻率檢查郵件內(nèi)容主題顯示亂碼setSubject未指定編碼使用setSubject(subject, UTF-8)頁面表單中文亂碼Servlet未調(diào)用setCharacterEncoding在讀取參數(shù)前設(shè)置UTF-8這張表可以貼在你項(xiàng)目的README里后續(xù)維護(hù)時(shí)候查起來很方便。7. 進(jìn)階擴(kuò)展與個(gè)人經(jīng)驗(yàn)總結(jié)7.1 如何加入附件支持現(xiàn)在實(shí)現(xiàn)的版本只支持純文本和HTML內(nèi)容。如果業(yè)務(wù)需要支持附件你需要在原來的MimeMessage基礎(chǔ)上使用MimeMultipart和MimeBodyPart構(gòu)造復(fù)合消息。MimeMultipart multipart new MimeMultipart(); // 正文部分 MimeBodyPart textPart new MimeBodyPart(); textPart.setContent(content, text/html;charsetUTF-8); multipart.addBodyPart(textPart); // 附件部分 MimeBodyPart filePart new MimeBodyPart(); DataSource source new FileDataSource(filePath); filePart.setDataHandler(new DataHandler(source)); filePart.setFileName(MimeUtility.encodeText(fileName, UTF-8, B)); multipart.addBodyPart(filePart); message.setContent(multipart);這里有個(gè)關(guān)鍵點(diǎn)setFileName需要進(jìn)行MIME編碼處理否則中文文件名在收件人那里會(huì)變成亂碼。MimeUtility.encodeText幫我們把中文轉(zhuǎn)換為符合MIME規(guī)范的編碼。如果不做這步收件人下載附件時(shí)文件名就會(huì)顯示成亂碼——這個(gè)問題我實(shí)際測(cè)試時(shí)遇到過填入測(cè)試報(bào)告.pdf后收件人看到的是?UTF-8?B?...?這樣的長(zhǎng)串令人頭大。7.2 支持多收件人與抄送實(shí)際業(yè)務(wù)中一封郵件可能需要發(fā)給多個(gè)收件人。JavaMail API支持在一條消息上添加多個(gè)收件人message.addRecipients(Message.RecipientType.TO, InternetAddress.parse(aexample.com,bexample.com));這里用的是addRecipients復(fù)數(shù)可以一次解析多個(gè)地址用逗號(hào)分隔。抄送則是message.addRecipient(Message.RecipientType.CC, new InternetAddress(ccexample.com));7.3 開發(fā)中的三點(diǎn)體會(huì)最后分享幾個(gè)我在整個(gè)實(shí)現(xiàn)過程中的體會(huì)這些不是代碼層面的知識(shí)但我覺得比代碼更重要。第一原生實(shí)現(xiàn)的最大價(jià)值不是不用框架而是讓你理解框架幫你做了什么。當(dāng)你親手配置Session、看著Authenticator的調(diào)用、閱讀SMTP協(xié)議的調(diào)試日志你才真正理解為什么Spring Boot里只要填幾行配置郵件就能發(fā)出去——因?yàn)榭蚣芴婺惴庋b了這一整條鏈路。有了這個(gè)理解再用框架時(shí)你排查問題會(huì)精準(zhǔn)很多。第二很多奇怪的問題根源都是編碼不一致。我做這個(gè)項(xiàng)目時(shí)中文亂碼問題前前后后折騰了大半天從頁面排查到Servlet再到JavaMail的設(shè)置最后發(fā)現(xiàn)是JSP文件本身的編碼被IDE存成了GBK。所以項(xiàng)目創(chuàng)建之初就統(tǒng)一設(shè)置項(xiàng)目編碼為UTF-8文件編碼為UTF-8連接數(shù)據(jù)庫、寫頁面、返回響應(yīng)都明確指定UTF-8能避免后續(xù)大量扯皮。第三調(diào)試信息是好朋友別嫌它煩。setDebug(true)打出的日志雖然長(zhǎng)但它是你能看到的、客戶端和服務(wù)器之間的真實(shí)對(duì)話記錄。遇到問題時(shí)先看日志再說能省掉大量盲目試錯(cuò)的時(shí)間。正式上線時(shí)關(guān)掉它否則日志文件會(huì)快速膨脹。這個(gè)項(xiàng)目的后續(xù)擴(kuò)展方向其實(shí)不少比如把發(fā)件配置移動(dòng)到數(shù)據(jù)庫表做成后臺(tái)可以動(dòng)態(tài)管理的功能比如加入發(fā)送記錄表記錄每次發(fā)送的時(shí)間、收件人、狀態(tài)再比如做一個(gè)定時(shí)任務(wù)定期處理隊(duì)列中的待發(fā)郵件。每一步擴(kuò)展都是對(duì)JavaWeb技術(shù)棧更深入的一次實(shí)踐。 原生JavaWeb實(shí)現(xiàn)郵件發(fā)送：Servlet+JavaMail從零搭建
1. 項(xiàng)目概述1.1 這個(gè)需求背后的真實(shí)場(chǎng)景說到Java Web發(fā)郵件很多剛?cè)胄械耐瑢W(xué)第一反應(yīng)是拿個(gè)Spring Boot項(xiàng)目加個(gè)starter填幾個(gè)配置一個(gè)JavaMailSender注入進(jìn)來就能跑了。但如果你還在學(xué)原生Servlet、JSP的老一套技術(shù)?；蛘吣闼陧?xiàng)目有盡量不引入框架依賴的約束那原生Java Web實(shí)現(xiàn)郵件發(fā)送這個(gè)需求就會(huì)突然變得不那么輕松。我這次做的東西就是在這個(gè)背景下展開的一個(gè)純Servlet JavaMail API實(shí)現(xiàn)的郵件發(fā)送功能頁面提交表單后端接到請(qǐng)求后通過SMTP協(xié)議把郵件發(fā)出去。沒有Spring沒有Maven插件沒有一堆自動(dòng)配置每一步都手動(dòng)拼起來。這種做法的價(jià)值在于它能讓你真正理解一封郵件從瀏覽器表單到對(duì)方收件箱之間到底經(jīng)歷了哪些環(huán)節(jié)而不是被框架的黑盒隱藏起來。這套代碼適合誰參考三類人第一類是正在學(xué)Java Web、想搞明白Servlet如何承接請(qǐng)求并完成任務(wù)的同學(xué)第二類是在校做課程設(shè)計(jì)、需要一個(gè)完整可演示的郵件發(fā)送模塊的開發(fā)者第三類是工作中遇到了不能用框架、必須原生實(shí)現(xiàn)這種約束需要快速落地的工程師?？赐赀@篇文章你能拿到可以直接跑起來的源碼也能明白文件編碼問題、SMTP認(rèn)證失敗、端口不通這些坑是怎么踩出來的。1.2 準(zhǔn)備聊哪些內(nèi)容文章會(huì)分為這樣幾個(gè)部分先說郵件發(fā)送涉及的基礎(chǔ)知識(shí)——SMTP協(xié)議是什么、JavaMail API和它的依賴關(guān)系然后講我如何規(guī)劃項(xiàng)目結(jié)構(gòu)和關(guān)鍵配置接著給出完整源碼逐段拆解發(fā)送邏輯再聊Servlet如何接入Http請(qǐng)求以及JSP頁面上的表單細(xì)節(jié)最后把實(shí)際開發(fā)中遇到的典型問題和排查思路整理成清單。每個(gè)段落都會(huì)附帶我在動(dòng)手過程中的實(shí)際操作記錄和經(jīng)驗(yàn)體會(huì)不是純理論都是可復(fù)現(xiàn)的步驟。2. 郵件發(fā)送的核心機(jī)制與JavaMail選型2.1 SMTP協(xié)議到底是干什么的郵件發(fā)送這件事本質(zhì)上就是你的程序作為郵件客戶端把一封構(gòu)造好的郵件扔給一臺(tái)SMTP服務(wù)器再由這臺(tái)服務(wù)器負(fù)責(zé)把郵件投遞到收件人的郵件服務(wù)器上。整個(gè)過程遵循SMTP協(xié)議——Simple Mail Transfer Protocol簡(jiǎn)單郵件傳輸協(xié)議。它定義了兩臺(tái)服務(wù)器之間、客戶端與服務(wù)器之間的對(duì)話規(guī)則。你可以把SMTP服務(wù)器想象成一個(gè)快遞中轉(zhuǎn)站。你寫好了包裹郵件填好了收件人地址收件郵箱然后把它交給中轉(zhuǎn)站SMTP服務(wù)器中轉(zhuǎn)站根據(jù)地址去投遞。如果收件人郵箱恰好也在同一家中轉(zhuǎn)站的管轄范圍那它直接投進(jìn)對(duì)方信箱如果不在它會(huì)轉(zhuǎn)交給下一個(gè)中轉(zhuǎn)站。發(fā)郵件這個(gè)動(dòng)作從用戶視角看只是點(diǎn)了發(fā)送按鈕但背后經(jīng)歷了至少一次TCP連接、一次身份認(rèn)證通常需要、一次郵件數(shù)據(jù)傳輸。第三方免費(fèi)郵箱提供的SMTP服務(wù)器通常會(huì)在服務(wù)器上開一個(gè)認(rèn)證機(jī)制。你用自己的郵箱賬號(hào)去登錄對(duì)方服務(wù)器通過驗(yàn)證之后才允許發(fā)信。這也是為什么實(shí)際開發(fā)中你幾乎不可能只寫代碼就能把郵件發(fā)出去——你必須有一個(gè)真實(shí)的、開啟了SMTP服務(wù)權(quán)限的郵箱賬戶。大多數(shù)主流郵箱廠商默認(rèn)不開放這個(gè)功能需要你手動(dòng)在設(shè)置里開啟SMTP/POP3/IMAP服務(wù)然后生成一個(gè)授權(quán)碼而非直接使用登錄密碼。這個(gè)細(xì)節(jié)非常關(guān)鍵我第一次測(cè)試時(shí)用賬號(hào)密碼直接認(rèn)證服務(wù)器返回535錯(cuò)誤查了半天才意識(shí)到要用授權(quán)碼。2.2 JavaMail API的結(jié)構(gòu)與依賴Java原生發(fā)郵件依賴的核心API是javax.mail包這是JavaEE規(guī)范中JavaMail的一部分。它不是JDK自帶的需要額外引入兩個(gè)JAR包mail.jar提供Session、Message、Transport等主要類activation.jar處理MIME類型數(shù)據(jù)的輔助包比如附件、圖片內(nèi)嵌這類二進(jìn)制的數(shù)據(jù)如果你的項(xiàng)目用Maven管理依賴引入這兩個(gè)坐標(biāo)就行但如果是原生Servlet項(xiàng)目、沒有Maven那你得手動(dòng)把JAR包放在WEB-INF/lib目錄下。我在開發(fā)時(shí)使用的是最傳統(tǒng)的手動(dòng)部署方式——自己在本地下載了mail.jar和activation.jar放在lib目錄然后讓Tomcat在啟動(dòng)時(shí)加載它們。這種方式的好處是完全可控不用依賴網(wǎng)絡(luò)構(gòu)件倉庫對(duì)課程設(shè)計(jì)或者內(nèi)網(wǎng)開發(fā)環(huán)境非常友好。JavaMail API工作的核心對(duì)象有三個(gè)Session整個(gè)郵件會(huì)話的配置中心持有服務(wù)器地址、端口、認(rèn)證開關(guān)、網(wǎng)絡(luò)超時(shí)這些參數(shù)MimeMessage代表一封郵件負(fù)責(zé)組裝發(fā)件人、收件人、主題、正文、附件Transport真正把MimeMessage發(fā)給SMTP服務(wù)器并完成數(shù)據(jù)傳輸?shù)耐ǖ肋@三者的關(guān)系可以簡(jiǎn)化理解為一個(gè)類似快遞流程你(Session)約好了快遞公司SMTP服務(wù)器的規(guī)矩填好快遞單MimeMessage然后交給快遞員Transport帶走。在后面的代碼部分你就能看到這三者依次登場(chǎng)。2.3 為什么不用第三方SDK而自己寫現(xiàn)在很多云服務(wù)商提供了HTTP接口發(fā)郵件的SDK比如通過API密鑰調(diào)用發(fā)信接口代碼量更小、送達(dá)率也更高。那為什么我這次堅(jiān)持用原生JavaMail原因很簡(jiǎn)單題目要求是原生JavaWeb實(shí)現(xiàn)這是技術(shù)學(xué)習(xí)路徑上必須走的一步。用云服務(wù)商的SDK屏蔽了底層的SMTP交互學(xué)習(xí)價(jià)值大打折扣。而手工寫JavaMail代碼你能看清SMTP服務(wù)器的連接是Socket層面的TCP通信郵件內(nèi)容本質(zhì)上是MIME格式的文本數(shù)據(jù)附件是多段MIME結(jié)構(gòu)拼接起來的這些底層認(rèn)知對(duì)于將來調(diào)試復(fù)雜的郵件問題——比如附件格式錯(cuò)亂、郵件被識(shí)別為垃圾內(nèi)容——會(huì)提供很大的幫助。當(dāng)然如果項(xiàng)目上線到生產(chǎn)環(huán)境我的建議還是優(yōu)先用成熟的郵件服務(wù)商或者企業(yè)內(nèi)部郵件服務(wù)器原生JavaMail更適合學(xué)習(xí)和可控的自建場(chǎng)景。后者在投遞成功率、反垃圾評(píng)分上靠的是背后整個(gè)基礎(chǔ)設(shè)施的積累。3. 項(xiàng)目結(jié)構(gòu)和基礎(chǔ)配置準(zhǔn)備3.1 項(xiàng)目目錄怎么組織我這次的項(xiàng)目結(jié)構(gòu)完全按照Servlet規(guī)范的標(biāo)準(zhǔn)布局來沒有多余的花架子。核心文件有這些mail-demo/ ├── src/ │ └── com/example/mail/ │ ├── MailSender.java // 郵件發(fā)送核心邏輯 │ ├── SendMailServlet.java // 接收表單請(qǐng)求的Servlet │ └── MailConfig.java // 郵件配置常量服務(wù)器、賬號(hào)、授權(quán)碼 ├── web/ │ ├── WEB-INF/ │ │ ├── lib/ │ │ │ ├── mail.jar │ │ │ └── activation.jar │ │ └── web.xml │ └── sendMail.jsp // 發(fā)送頁面這個(gè)結(jié)構(gòu)是手動(dòng)建出來的沒有用IDE的Web項(xiàng)目向?qū)?。之所以手?dòng)搭是因?yàn)楹芏喑鯇W(xué)者在IDE里點(diǎn)新建Dynamic Web Project時(shí)會(huì)面臨各種版本兼容的選項(xiàng)錯(cuò)誤反而不如自己動(dòng)手創(chuàng)建目錄、自己寫web.xml來得清晰。當(dāng)然你在IDEA里用Project Structure新建Web項(xiàng)目也是可以的只要保證最終部署出來的目錄結(jié)構(gòu)滿足Servlet規(guī)范即可。還有一點(diǎn)要提前說清楚WEB-INF目錄下的東西是Web容器保護(hù)的外部不能通過URL直接訪問。所以mail.jar和activation.jar放在WEB-INF/lib下能被Tomcat自動(dòng)加載而用戶無法通過http://ip:8080/mail-demo/mail.jar下載到它。這個(gè)機(jī)制是Servlet規(guī)范定義的保證依賴庫的私密性。3.2 需要的JAR包怎么獲取前面提到的兩個(gè)JAR包獲取途徑很常規(guī)。mail.jar可以在Oracle官網(wǎng)的JavaMail頁面下載也可以從Maven中央倉庫直接下載jar包文件。activation.jar同樣可以在Maven中央倉庫獲取搜索javax.activation即可。需要注意的是版本問題JavaMail版本建議選1.4.7這是公認(rèn)穩(wěn)定且資料多的版本activation建議選1.1.1。高版本的jakarta.mail是另一套命名空間jakarta.mail包跟傳統(tǒng)的javax.mail不兼容如果項(xiàng)目還是老式Servlet容器Tomcat 8/9那用javax.mail的命名空間就夠了不用追新。如果你用的是Maven直接在pom.xml中配置dependency groupIdjavax.mail/groupId artifactIdmail/artifactId version1.4.7/version /dependency dependency groupIdjavax.activation/groupId artifactIdactivation/artifactId version1.1.1/version /dependency這里有一個(gè)容易踩的坑不同版本的mail.jar依賴的activation.jar版本可能不同如果不匹配運(yùn)行時(shí)會(huì)出現(xiàn)ClassNotFoundException: com.sun.activation.registries.MailcapFile這類錯(cuò)誤。我自己的做法是干脆兩個(gè)JAR都從同一個(gè)來源下載比如Maven倉庫中的配套版本避免版本錯(cuò)位。3.3 關(guān)鍵配置參數(shù)解釋在做郵件發(fā)送之前先要摸清你選擇的郵箱服務(wù)商提供的基礎(chǔ)參數(shù)。不同的郵件服務(wù)商SMTP服務(wù)器地址和端口可能不一樣常見的配置模式有普通SSL加密模式smtp.xxx.com端口465需要開啟SSL升級(jí)TLS模式smtp.xxx.com端口587需要STARTTLS我實(shí)際操作時(shí)優(yōu)先使用465端口SSL模式因?yàn)?87端口在有些服務(wù)器環(huán)境下會(huì)被運(yùn)營(yíng)商封鎖或者郵件服務(wù)商默認(rèn)不允許非加密連接。465這種SSL直連模式更省事只需要在Properties設(shè)置mail.smtp.ssl.enabletrue即可。除了服務(wù)器和端口還要準(zhǔn)備好你的完整郵箱地址作為發(fā)件人地址授權(quán)碼在郵箱設(shè)置中開啟SMTP后生成的一串獨(dú)立密碼收件人郵箱測(cè)試時(shí)最好用另一個(gè)不同域名下的郵箱這樣能驗(yàn)證跨服務(wù)器投遞是否正常我給項(xiàng)目加了一個(gè)MailConfig類來統(tǒng)一存放這些常量避免在代碼里到處寫死。這個(gè)問題雖然簡(jiǎn)單但做得好不好直接影響后面維護(hù)的體驗(yàn)——我見過不少項(xiàng)目把郵箱密碼散落在七八個(gè)類里改一次授權(quán)碼要全局搜索非常痛苦。4. 核心代碼實(shí)現(xiàn)詳解4.1 MailSender類——郵件發(fā)送的骨架先給出這個(gè)類的完整代碼這是整個(gè)項(xiàng)目中最核心的部分package com.example.mail; import java.util.Properties; import javax.mail.Authenticator; import javax.mail.Message; import javax.mail.MessagingException; import javax.mail.PasswordAuthentication; import javax.mail.Session; import javax.mail.Transport; import javax.mail.internet.InternetAddress; import javax.mail.internet.MimeMessage; public class MailSender { public static void send(String to, String subject, String content) throws MessagingException { Properties props new Properties(); // SMTP服務(wù)器地址 props.put(mail.smtp.host, MailConfig.SMTP_HOST); // 端口 props.put(mail.smtp.port, MailConfig.SMTP_PORT); // 是否開啟認(rèn)證 props.put(mail.smtp.auth, true); // 是否開啟SSL props.put(mail.smtp.ssl.enable, true); // 設(shè)置超時(shí)時(shí)間避免服務(wù)器無響應(yīng)時(shí)客戶端卡死 props.put(mail.smtp.connectiontimeout, 10000); props.put(mail.smtp.timeout, 10000); Session session Session.getInstance(props, new Authenticator() { Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(MailConfig.USERNAME, MailConfig.AUTH_CODE); } }); // 打開調(diào)試模式方便觀察SMTP協(xié)議交互過程 session.setDebug(true); MimeMessage message new MimeMessage(session); message.setFrom(new InternetAddress(MailConfig.USERNAME)); message.addRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject, UTF-8); message.setContent(content, text/html;charsetUTF-8); Transport.send(message); } }這段代碼里值得逐行解釋的地方不少。先看Session.getInstance(props, authenticator)這一行props里配置了連接SMTP的所有參數(shù)而Authenticator是JavaMail用來獲取認(rèn)證憑據(jù)的接口。注意看我在這里返回的不是郵箱的登錄密碼而是AUTH_CODE授權(quán)碼。這個(gè)設(shè)計(jì)是JavaMail API的標(biāo)準(zhǔn)用法——通過PasswordAuthentication封裝用戶名和密碼/授權(quán)碼Transport在連接服務(wù)器時(shí)會(huì)自動(dòng)使用這組憑據(jù)做認(rèn)證。再看message.setSubject(subject, UTF-8)。這個(gè)方法的重載形式很多如果你直接調(diào)用setSubject(subject)主題會(huì)按默認(rèn)編碼處理中文大概率變成亂碼。我特意指定了UTF-8確保中英文都能正確編碼。同理正文通過setContent(content, text/html;charsetUTF-8)設(shè)置告訴收件人的郵件客戶端這是一封HTML格式、UTF-8編碼的郵件。如果你想要純文本格式把第二個(gè)參數(shù)改成text/plain;charsetUTF-8就行。還有一個(gè)容易被忽略的細(xì)節(jié)session.setDebug(true)。這行代碼平時(shí)沒存在感但當(dāng)你遇到郵件發(fā)不出去這種問題需要排查時(shí)它會(huì)幫你打印出客戶端和SMTP服務(wù)器之間的完整對(duì)話過程——包括DNS解析、TCP連接、EHLO指令、AUTH LOGIN認(rèn)證、MAIL FROM指令、RCPT TO指令、DATA指令以及服務(wù)器的每個(gè)響應(yīng)碼。我第一次排查認(rèn)證失敗問題時(shí)就是依靠這個(gè)輸出看到了服務(wù)器返回的錯(cuò)誤碼才定位到授權(quán)碼的問題。上線部署時(shí)記得把setDebug改成false否則會(huì)產(chǎn)生大量日志輸出。4.2 MailConfig類——統(tǒng)一管理配置有經(jīng)驗(yàn)的人寫代碼不會(huì)把配置參數(shù)分散在業(yè)務(wù)代碼里。我單獨(dú)抽了個(gè)MailConfig類package com.example.mail; public class MailConfig { // SMTP服務(wù)器地址 public static final String SMTP_HOST smtp.yourmailservice.com; // 端口SSL加密連接常用465 public static final String SMTP_PORT 465; // 發(fā)件人郵箱地址 public static final String USERNAME your_accountexample.com; // 授權(quán)碼不是登錄密碼 public static final String AUTH_CODE xxxxxxxxxxxxxx; }這個(gè)類的作用不言自明當(dāng)你的部署環(huán)境切換時(shí)比如從測(cè)試郵箱切換到公司內(nèi)部郵件服務(wù)器只需要改這一個(gè)文件當(dāng)授權(quán)碼過期需要替換時(shí)也只需要改這一個(gè)地方。這里有個(gè)建議如果你要把項(xiàng)目推到Git倉庫上務(wù)必在.gitignore中排除這個(gè)文件或者在提交前將真實(shí)授權(quán)碼替換成占位符——否則授權(quán)碼泄露別人就能用你的郵箱發(fā)郵件輕則被當(dāng)作垃圾郵件源重則影響郵箱安全。4.3 SendMailServlet——接收請(qǐng)求的核心入口Servlet在Java Web開發(fā)中扮演的角色就是接受HTTP請(qǐng)求、執(zhí)行業(yè)務(wù)邏輯、返回響應(yīng)視圖。我這里創(chuàng)建了一個(gè)SendMailServlet只負(fù)責(zé)接收頁面表單的POST請(qǐng)求并調(diào)用MailSenderpackage com.example.mail; import java.io.IOException; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; WebServlet(/sendMail) public class SendMailServlet extends HttpServlet { private static final long serialVersionUID 1L; Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { request.setCharacterEncoding(UTF-8); response.setContentType(text/html;charsetUTF-8); String to request.getParameter(to); String subject request.getParameter(subject); String content request.getParameter(content); if (to null || to.trim().isEmpty() || subject null || subject.trim().isEmpty()) { request.setAttribute(message, 收件人、主題不能為空); request.getRequestDispatcher(sendMail.jsp).forward(request, response); return; } try { MailSender.send(to.trim(), subject.trim(), content); request.setAttribute(message, 郵件發(fā)送成功); } catch (Exception e) { e.printStackTrace(); request.setAttribute(message, 郵件發(fā)送失敗 e.getMessage()); } request.getRequestDispatcher(sendMail.jsp).forward(request, response); } }注意編碼問題我在doPost第一行就設(shè)置了request.setCharacterEncoding(UTF-8)。這個(gè)調(diào)用必須在讀取任何請(qǐng)求參數(shù)之前執(zhí)行否則Tomcat會(huì)按默認(rèn)的ISO-8859-1來解碼POST請(qǐng)求體中文表單提交就會(huì)出現(xiàn)亂碼。這個(gè)細(xì)節(jié)初學(xué)者特別容易踩坑——我見過很多人在頁面已經(jīng)設(shè)置了UTF-8但后臺(tái)收到的參數(shù)依然是亂碼的情況原因就是漏了這行。另外我做了基本的非空校驗(yàn)只校驗(yàn)了收件人和主題沒對(duì)郵箱格式做正則校驗(yàn)。正常開發(fā)中收件人格式校驗(yàn)是很基本的——郵箱里注入垃圾內(nèi)容導(dǎo)致發(fā)信失敗事小如果將來做批量發(fā)送功能格式錯(cuò)誤可能引發(fā)異常退信。后面在升級(jí)篇中我會(huì)展示一個(gè)簡(jiǎn)單的驗(yàn)證方式。4.4 sendMail.jsp——前端提交界面最后需要一個(gè)交互頁面。我這里用JSP實(shí)現(xiàn)通過簡(jiǎn)單的HTML表單提交數(shù)據(jù)% page contentTypetext/html;charsetUTF-8 languagejava % html head title郵件發(fā)送/title style body { font-family: Microsoft YaHei, sans-serif; background: #f5f5f5; } .container { width: 600px; margin: 50px auto; background: #fff; padding: 30px; border-radius: 8px; } label { display: block; margin-top: 15px; font-weight: bold; } input[typetext], textarea { width: 100%; padding: 8px; margin-top: 5px; border: 1px solid #ccc; border-radius: 4px; } textarea { height: 120px; } button { margin-top: 20px; padding: 10px 30px; background: #409eff; color: #fff; border: none; border-radius: 4px; cursor: pointer; } /style /head body div classcontainer h2發(fā)送郵件/h2 p stylecolor: red;${message}/p form actionsendMail methodpost label收件人郵箱/label input typetext nameto placeholdersomeoneexample.com label郵件主題/label input typetext namesubject placeholder郵件主題 label郵件內(nèi)容/label textarea namecontent placeholder請(qǐng)輸入郵件正文內(nèi)容/textarea button typesubmit發(fā)送/button /form /div /body /html表單的提交方式必須是post因?yàn)猷]件發(fā)送會(huì)改變服務(wù)器狀態(tài)而且郵件主題和正文可能包含較長(zhǎng)的內(nèi)容POST在數(shù)據(jù)大小限制和語義上都更合適。表單的action指向sendMail這個(gè)映射在Servlet代碼中是通過WebServlet(/sendMail)注解定義的——如果用低版本的Servlet容器注解可能不支持你需要再去web.xml里聲明Servlet映射我這次使用的是Servlet 3.0直接走注解。頁面上用了${message}來顯示后端返回的結(jié)果這要求JSP默認(rèn)支持EL表達(dá)式。大部分Tomcat配置都是支持的如果顯示原樣${message}那是開了忽略EL的配置可以在JSP頂部加% page isELIgnoredfalse %解決。5. 部署運(yùn)行與完整驗(yàn)證流程5.1 部署到Tomcat部署過程我是這樣操作的先確保本地已經(jīng)安裝了Tomcat 8或9然后把整個(gè)項(xiàng)目導(dǎo)出為WAR包或者直接把項(xiàng)目目錄丟到Tomcat的webapps目錄下。如果你用的是IDEA可以在Run Configuration里配置Tomcat Server把項(xiàng)目部署到Tomcat后點(diǎn)擊運(yùn)行。啟動(dòng)過程中有幾點(diǎn)要特別注意Tomcat啟動(dòng)時(shí)會(huì)在日志中打印部署信息如果WEB-INF/lib下的JAR包沒有正確加載你會(huì)看到ClassNotFoundException異常那多半是lib目錄路徑不對(duì)或者JAR包缺失如果出現(xiàn)端口占用檢查是否有其他Tomcat實(shí)例在運(yùn)行可以在conf/server.xml中改端口瀏覽器訪問路徑通常是http://localhost:8080/mail-demo/sendMail.jsp這里mail-demo是你的上下文路徑也就是WAR包名或項(xiàng)目名啟動(dòng)完成后頁面能正常顯示就可以開始測(cè)試發(fā)送了。5.2 功能驗(yàn)證步驟我的驗(yàn)證流程是這樣的開兩個(gè)郵箱一個(gè)作為發(fā)件方一個(gè)作為收件方兩個(gè)郵箱都用不同域名這樣才能檢驗(yàn)跨服務(wù)器投遞。然后我在頁面上分別填寫收件人recipientotherdomain.com主題JavaMail原生發(fā)送測(cè)試內(nèi)容h2這是HTML內(nèi)容/h2p這是一封來自原生JavaWeb項(xiàng)目的郵件。/p點(diǎn)擊發(fā)送后如果頁面顯示郵件發(fā)送成功再去看收件方郵箱是否收到。為了確認(rèn)整個(gè)鏈路完整我在MailSender中開著setDebug(true)控制臺(tái)會(huì)打印出一大段SMTP協(xié)議交互日志。關(guān)鍵的日志片段類似DEBUG SMTP: Connected to host: smtp.xxx.com, port: 465 DEBUG SMTP: AUTH LOGIN command mixed with SSL DEBUG SMTP: Use 8bit NTLM DEBUG SMTP: AUTH LOGIN succeeded DEBUG SMTP: MAIL FROM:your_accountexample.com DEBUG SMTP: RCPT TO:recipientotherdomain.com DEBUG SMTP: DATA當(dāng)看到AUTH LOGIN succeeded和RCPT TO成功返回時(shí)基本可以判斷郵件已經(jīng)進(jìn)入投遞流程。等收件方郵箱收到郵件說明整個(gè)鏈路是通的。5.3 控制臺(tái)日志怎么看很多同學(xué)面對(duì)一大段Debug日志會(huì)發(fā)懵我在這里簡(jiǎn)單說一下怎么看。SMTP協(xié)議的命令都是有跡可循的220開頭的行服務(wù)器打招呼說明TCP連接成功250開頭的行請(qǐng)求被接受比如EHLO、MAIL FROM、RCPT TO成功334開頭的行服務(wù)器要求提供認(rèn)證信息用戶名/密碼235開頭的行認(rèn)證成功535開頭的行認(rèn)證失敗常見原因是授權(quán)碼錯(cuò)誤554開頭的行發(fā)送被拒絕可能是內(nèi)容觸發(fā)反垃圾策略把這幾個(gè)狀態(tài)碼記住絕大多數(shù)郵件發(fā)送問題都能在日志中直接定位。我也是用這個(gè)方法調(diào)通了整個(gè)項(xiàng)目后面要分享的幾個(gè)坑也全都靠日志才排查清楚。6. 常見問題與排查技巧實(shí)錄6.1 授權(quán)碼錯(cuò)誤的經(jīng)典報(bào)錯(cuò)第一次測(cè)試時(shí)我在發(fā)件人配置中填了真正的郵箱登錄密碼結(jié)果控制臺(tái)打出如下錯(cuò)誤javax.mail.AuthenticationFailedException: 535 Error: authentication failed排查步驟很簡(jiǎn)單先確認(rèn)郵箱是否已開啟SMTP服務(wù)再確認(rèn)授權(quán)碼是否有效。多數(shù)郵箱開啟SMTP服務(wù)后會(huì)明確提示授權(quán)碼僅顯示一次, 需要妥善保存如果遺忘了只能重新生成。把配置里的AUTH_CODE換成新授權(quán)碼問題就解決了。這是一個(gè)很多人會(huì)犯的錯(cuò)誤因?yàn)榈卿浢艽a和授權(quán)碼是兩個(gè)不同的東西登錄密碼只能在網(wǎng)頁Web端使用授權(quán)碼是專門提供給第三方客戶端使用的。所以拿到一個(gè)發(fā)不出去郵件的報(bào)錯(cuò)先別慌著改代碼先檢查認(rèn)證憑據(jù)。6.2 端口不通的排查記錄另一次測(cè)試中我配置了SMTP端口為25這是SMTP協(xié)議的默認(rèn)端口但在部分網(wǎng)絡(luò)環(huán)境下25端口會(huì)被ISP封鎖日志顯示連接超時(shí)java.net.ConnectException: Connection timed out: connect排查方法是先用telnet smtp.xxx.com 25測(cè)試端口連通性。如果telnet連接不了果斷換成465或587端口。服務(wù)器防火墻規(guī)則、云服務(wù)商安全組這些網(wǎng)絡(luò)層面因素都可能導(dǎo)致端口不通。實(shí)際使用時(shí)我用465端口一切正常25端口則出現(xiàn)超時(shí)。這里有個(gè)經(jīng)驗(yàn)如果你部署在云服務(wù)器上還要檢查安全組規(guī)則是否放行了對(duì)應(yīng)出方向端口。大部分云廠商默認(rèn)放行所有出方向端口但在部分企業(yè)內(nèi)網(wǎng)環(huán)境需要向網(wǎng)絡(luò)管理員申請(qǐng)開通。6.3 中文亂碼問題根因分析中文亂碼是另一個(gè)高頻問題。問題出現(xiàn)的現(xiàn)象是收件方收到郵件后主題顯示問號(hào)或亂碼正文中的中文也成了亂碼。根因在于編碼設(shè)置不一致。處理方法就是我前面代碼中體現(xiàn)的JSP頁面聲明UTF-8表單提交前使用UTF-8編碼Servlet中調(diào)用request.setCharacterEncoding(UTF-8)在讀取參數(shù)之前執(zhí)行setSubject指定UTF-8參數(shù)setContent聲明text/html;charsetUTF-8四個(gè)環(huán)節(jié)缺一不可。我在JSP頁面里還特意給表單加了accept-charsetUTF-8屬性雖然現(xiàn)代瀏覽器默認(rèn)會(huì)按頁面編碼提交但多這一層保險(xiǎn)總沒有壞處。另外一個(gè)隱蔽的坑是如果你的項(xiàng)目部署在Windows服務(wù)器上系統(tǒng)默認(rèn)字符集是GBK某些文件的編碼如果被IDE用系統(tǒng)默認(rèn)字符集保存了JSP編譯出來就會(huì)出亂碼。這種情況可以在server.xml中的Connector標(biāo)簽添加URIEncodingUTF-8屬性確保GET請(qǐng)求參數(shù)的編碼也正確。6.4 頻繁發(fā)送觸發(fā)限流策略測(cè)試時(shí)如果短時(shí)間內(nèi)連續(xù)發(fā)送多封郵件可能會(huì)觸發(fā)郵箱服務(wù)商的反垃圾策略。服務(wù)器會(huì)返回類似這樣的錯(cuò)誤554 Transaction failed這時(shí)不能繼續(xù)重試否則可能被封禁發(fā)信權(quán)限。正確做法是放慢發(fā)送頻率每次間隔至少一兩分鐘如果是正式項(xiàng)目需要批量發(fā)送建議設(shè)計(jì)異步隊(duì)列控制發(fā)送速率和日發(fā)送量上限。個(gè)人郵箱的日發(fā)送配額通常有限不建議拿個(gè)人郵箱做大規(guī)模生產(chǎn)發(fā)信。6.5 常見錯(cuò)誤碼速查表為了方便排查我把一些常見問題整理成了表格現(xiàn)象可能原因解決思路535認(rèn)證失敗授權(quán)碼錯(cuò)誤重新生成授權(quán)碼并更新配置Connection timed out端口不通、防火墻攔截telnet測(cè)試端口更換465端口Could not connect to SMTP host服務(wù)器地址配置錯(cuò)誤檢查郵箱服務(wù)商SMTP地址550 Mailbox not found收件人地址不存在確認(rèn)收件人郵箱拼寫554 Transaction failed內(nèi)容觸發(fā)反垃圾策略降低發(fā)送頻率檢查郵件內(nèi)容主題顯示亂碼setSubject未指定編碼使用setSubject(subject, UTF-8)頁面表單中文亂碼Servlet未調(diào)用setCharacterEncoding在讀取參數(shù)前設(shè)置UTF-8這張表可以貼在你項(xiàng)目的README里后續(xù)維護(hù)時(shí)候查起來很方便。7. 進(jìn)階擴(kuò)展與個(gè)人經(jīng)驗(yàn)總結(jié)7.1 如何加入附件支持現(xiàn)在實(shí)現(xiàn)的版本只支持純文本和HTML內(nèi)容。如果業(yè)務(wù)需要支持附件你需要在原來的MimeMessage基礎(chǔ)上使用MimeMultipart和MimeBodyPart構(gòu)造復(fù)合消息。MimeMultipart multipart new MimeMultipart(); // 正文部分 MimeBodyPart textPart new MimeBodyPart(); textPart.setContent(content, text/html;charsetUTF-8); multipart.addBodyPart(textPart); // 附件部分 MimeBodyPart filePart new MimeBodyPart(); DataSource source new FileDataSource(filePath); filePart.setDataHandler(new DataHandler(source)); filePart.setFileName(MimeUtility.encodeText(fileName, UTF-8, B)); multipart.addBodyPart(filePart); message.setContent(multipart);這里有個(gè)關(guān)鍵點(diǎn)setFileName需要進(jìn)行MIME編碼處理否則中文文件名在收件人那里會(huì)變成亂碼。MimeUtility.encodeText幫我們把中文轉(zhuǎn)換為符合MIME規(guī)范的編碼。如果不做這步收件人下載附件時(shí)文件名就會(huì)顯示成亂碼——這個(gè)問題我實(shí)際測(cè)試時(shí)遇到過填入測(cè)試報(bào)告.pdf后收件人看到的是?UTF-8?B?...?這樣的長(zhǎng)串令人頭大。7.2 支持多收件人與抄送實(shí)際業(yè)務(wù)中一封郵件可能需要發(fā)給多個(gè)收件人。JavaMail API支持在一條消息上添加多個(gè)收件人message.addRecipients(Message.RecipientType.TO, InternetAddress.parse(aexample.com,bexample.com));這里用的是addRecipients復(fù)數(shù)可以一次解析多個(gè)地址用逗號(hào)分隔。抄送則是message.addRecipient(Message.RecipientType.CC, new InternetAddress(ccexample.com));7.3 開發(fā)中的三點(diǎn)體會(huì)最后分享幾個(gè)我在整個(gè)實(shí)現(xiàn)過程中的體會(huì)這些不是代碼層面的知識(shí)但我覺得比代碼更重要。第一原生實(shí)現(xiàn)的最大價(jià)值不是不用框架而是讓你理解框架幫你做了什么。當(dāng)你親手配置Session、看著Authenticator的調(diào)用、閱讀SMTP協(xié)議的調(diào)試日志你才真正理解為什么Spring Boot里只要填幾行配置郵件就能發(fā)出去——因?yàn)榭蚣芴婺惴庋b了這一整條鏈路。有了這個(gè)理解再用框架時(shí)你排查問題會(huì)精準(zhǔn)很多。第二很多奇怪的問題根源都是編碼不一致。我做這個(gè)項(xiàng)目時(shí)中文亂碼問題前前后后折騰了大半天從頁面排查到Servlet再到JavaMail的設(shè)置最后發(fā)現(xiàn)是JSP文件本身的編碼被IDE存成了GBK。所以項(xiàng)目創(chuàng)建之初就統(tǒng)一設(shè)置項(xiàng)目編碼為UTF-8文件編碼為UTF-8連接數(shù)據(jù)庫、寫頁面、返回響應(yīng)都明確指定UTF-8能避免后續(xù)大量扯皮。第三調(diào)試信息是好朋友別嫌它煩。setDebug(true)打出的日志雖然長(zhǎng)但它是你能看到的、客戶端和服務(wù)器之間的真實(shí)對(duì)話記錄。遇到問題時(shí)先看日志再說能省掉大量盲目試錯(cuò)的時(shí)間。正式上線時(shí)關(guān)掉它否則日志文件會(huì)快速膨脹。這個(gè)項(xiàng)目的后續(xù)擴(kuò)展方向其實(shí)不少比如把發(fā)件配置移動(dòng)到數(shù)據(jù)庫表做成后臺(tái)可以動(dòng)態(tài)管理的功能比如加入發(fā)送記錄表記錄每次發(fā)送的時(shí)間、收件人、狀態(tài)再比如做一個(gè)定時(shí)任務(wù)定期處理隊(duì)列中的待發(fā)郵件。每一步擴(kuò)展都是對(duì)JavaWeb技術(shù)棧更深入的一次實(shí)踐。