處理文件上傳大概是Java Web開發(fā)里最常被問到的需求之一。很多剛接觸Servlet的開發(fā)者以為從HttpServletRequest里拿上傳的文件就像拿表單參數(shù)一樣簡單——結(jié)果一調(diào)getParameter返回null或者getInputStream讀到一堆看不懂的二進(jìn)制再不然就是Connector上直接給你拋個IllegalStateException。這篇文章我就結(jié)合自己踩過的坑把“HttpServletRequest獲取上傳文件”這件事從頭到尾講透從multipart/form-data的底層格式到Servlet 3.0原生API的完整寫法再到老項(xiàng)目里那套第三方上傳組件的兼容方案以及各種讓人頭大的中文亂碼、內(nèi)存溢出、臨時文件清理問題全部梳理一遍。不管你是剛?cè)腴T的新手還是被老項(xiàng)目折磨過一陣子的開發(fā)者照著這篇文章的思路去調(diào)整自己的代碼基本都能落地。1. 先搞清楚需求文件上傳到底在解決什么問題1.1 從表單到請求上傳文件發(fā)生的完整鏈路“把文件傳給服務(wù)器”這件事放在HTTP的世界里其實(shí)沒那么復(fù)雜。瀏覽器把文件內(nèi)容塞進(jìn)HTTP請求體服務(wù)器從請求體里讀取字節(jié)流再想辦法還原成文件。關(guān)鍵就在于“塞進(jìn)去”這個動作的編碼方式。平時我們用得最多的表單提交默認(rèn)的編碼方式是application/x-www-form-urlencoded。這種格式下瀏覽器會把所有的表單數(shù)據(jù)拼成一個類似URL參數(shù)的字符串比如usernameadminpassword123456。這種格式傳純文本沒問題但是傳文件就不行了因?yàn)槲募?nèi)容是二進(jìn)制里面可能包含各種特殊字符甚至包含用于分隔字段的和直接按字符串拼接必然會亂套。所以表單里一旦出現(xiàn)input typefile就必須把form的enctype屬性設(shè)置為multipart/form-data。這時候?yàn)g覽器會把整個請求體切成若干個“段”Part每個段用一段隨機(jī)生成的boundary字符串隔開。這個boundary會同時出現(xiàn)在請求頭的Content-Type里比如Content-Type: multipart/form-data; boundary----WebKitFormBoundaryABC123。請求體就變成了類似這樣的結(jié)構(gòu)------WebKitFormBoundaryABC123 Content-Disposition: form-data; nameusername admin ------WebKitFormBoundaryABC123 Content-Disposition: form-data; namefile; filenametest.txt Content-Type: text/plain 文件內(nèi)容字節(jié)流 ------WebKitFormBoundaryABC123--服務(wù)器端要做的就是先根據(jù)Content-Type里的boundary把請求體切成一個個Part再從Part的Content-Disposition頭里解析出字段名、文件名最后把Part里的字節(jié)流保存起來。這件事Servlet容器在收到請求后其實(shí)已經(jīng)幫你做了大半你的代碼要做的只是調(diào)用方法拿結(jié)果。1.2 兩種主流實(shí)現(xiàn)方案怎么選在Java Web世界里拿到上傳文件這件事有兩條主流路線。一條是Servlet 3.0規(guī)范提供的原生API也就是通過HttpServletRequest的getPart()和getParts()方法直接拿到容器解析好的Part對象。只要你用的Servlet容器支持Servlet 3.0規(guī)范現(xiàn)在主流容器都支持比如Tomcat 7及以上的版本你的項(xiàng)目里不需要引入任何額外的JAR包一個注解加幾行代碼就能搞定。另一條路線是使用第三方上傳組件最經(jīng)典的就是Commons FileUpload。這個組件在Servlet 3.0規(guī)范出現(xiàn)之前就已經(jīng)存在了老項(xiàng)目里用得非常多它通過自己的解析器把請求體解析成List 代碼風(fēng)格和原生API差異很大但功能同樣完整。選擇哪條路線主要看你項(xiàng)目的實(shí)際情況。新項(xiàng)目我強(qiáng)烈建議直接走Servlet 3.0原生API零依賴、代碼簡潔、跟容器配合得也最順暢。老項(xiàng)目如果已經(jīng)在用Commons FileUpload且跑得好好的沒必要為了追求新而推翻重來后面章節(jié)我會詳細(xì)講兩種方案各自的完整寫法和注意點(diǎn)。2. 核心原理HttpServletRequest與multipart/form-data的關(guān)系2.1 Content-Type和boundary到底是怎么回事很多人寫文件上傳代碼的時候會忽略一個非?；A(chǔ)的問題請求頭里那兩個關(guān)鍵參數(shù)是干嘛用的Content-Type里不僅聲明了multipart/form-data還帶了一個boundary參數(shù)。boundary就是各個Part之間的“分隔線”它的值是一段隨機(jī)字符串瀏覽器保證這個字符串不會出現(xiàn)在文件內(nèi)容里。服務(wù)器解析請求體的時候就是靠這段boundary把一長串字節(jié)流切成一個個段落。這里有個特別容易踩的坑如果你手動構(gòu)建HTTP請求或者用某些HTTP客戶端工具發(fā)送multipart請求boundary沒配對服務(wù)器解析必然失敗。但用瀏覽器表單上傳時瀏覽器會自動生成boundary通常不會出問題。不過后端代碼里你會發(fā)現(xiàn)你根本不需要關(guān)心boundary是什么因?yàn)镾ervlet容器早就替你完成了拆分工作你拿到的Part對象就是拆分之后的產(chǎn)物。2.2 Part是什么容器幫你拆好的數(shù)據(jù)塊從開發(fā)者的視角來看Part就是multipart/form-data請求體中一個獨(dú)立的段落它對應(yīng)一個表單字段比如usernameadmin的普通輸入框?qū)?yīng)一個上傳文件。Part對象身上帶了幾個特別關(guān)鍵的方法getName()返回這個Part對應(yīng)的表單字段name屬性值比如input namefile這里返回的就是file。getSubmittedFileName()返回上傳文件的原始文件名注意這個方法在Servlet 3.1規(guī)范中才正式提供3.0版本下可能拿不到。getContentType()返回文件MIME類型比如image/png、text/plain。getSize()返回這個Part的字節(jié)數(shù)可以用來做文件大小的預(yù)判斷。getInputStream()拿到Part內(nèi)容的輸入流你可以自己把字節(jié)流讀到目標(biāo)文件。write(String fileName)容器幫我把Part內(nèi)容直接寫到一個文件里省去手動讀流的麻煩。需要特別注意的是Part對象里裝的不僅僅是文件。如果你在同一個表單里還放了普通輸入框比如姓名、備注之類的字段這些字段也會被封裝成Part對象只是它們的getSubmittedFileName()返回null且Content-Disposition里沒有filename字段。所以遍歷getParts()的時候要先判斷一下是不是文件Part。2.3 為什么getParameter在文件上傳時拿不到值這是我在很多初學(xué)者項(xiàng)目里看到的高頻問題。表單都設(shè)置enctypemultipart/form-data了代碼里request.getParameter(username)居然返回null搜索引擎一搜發(fā)現(xiàn)別人也有同樣的問題。原因在于一旦表單編碼方式變成multipart/form-data整個請求體就不再是那種usernameadminpassword123456的格式了。Servlet容器在處理普通格式請求時會把請求體自動解析到parameterMap里getParameter()自然就能拿到值。但遇到multipart格式時容器就不再執(zhí)行這個解析動作了它把請求體原樣保留下來等你通過getPart()/getParts()去讀取。所以getParameter()返回null是正常現(xiàn)象。正確的做法是在遍歷Part的時候判斷isFormField類型然后從Part的輸入流中讀取普通字段的值。這一點(diǎn)我會在下一章的完整示例代碼里展示出來。3. 實(shí)操用Servlet 3.0原生API獲取上傳文件3.1 前置準(zhǔn)備注解與配置一個都不能少Servlet 3.0原生API的使用前提是在你的Servlet類上標(biāo)注MultipartConfig注解或者在web.xml里配置multipart-config節(jié)點(diǎn)。這個注解就是告訴Servlet容器這個Servlet會接收multipart/form-data格式的請求請你幫我解析Part。如果你忘了加這個注解會有什么后果getParts()方法會正常返回一個空集合或者直接拋IllegalStateException具體表現(xiàn)取決于容器版本和實(shí)現(xiàn)。我身邊就有同事由于忘記加注解還到處找bug最后發(fā)現(xiàn)是配置缺失很容易浪費(fèi)大量時間。MultipartConfig注解有四個屬性可以配置它們決定了文件上傳的邊界與臨時文件策略屬性含義建議值fileSizeThreshold文件大小閾值超過該值的數(shù)據(jù)會從內(nèi)存轉(zhuǎn)寫到臨時文件建議設(shè)1MB左右maxFileSize單個文件允許的最大字節(jié)數(shù)根據(jù)業(yè)務(wù)場景設(shè)比如10MBmaxRequestSize整個multipart請求體允許的最大字節(jié)數(shù)建議比maxFileSize稍大比如50MBlocationPart.write()方法寫入文件的默認(rèn)目錄建議配置絕對路徑別忘了在doPost方法里先調(diào)用request.setCharacterEncoding(UTF-8)否則中文字段和文件名可能亂碼。這句話對普通表單同樣適用尤其在容器默認(rèn)編碼不是UTF-8的情況下。3.2 核心代碼一步步完成文件接收與保存直接給一個能跑通的基礎(chǔ)版本。假設(shè)前端表單里有一個文件輸入框namefile和一個普通輸入框nameremark后端Servlet的完整代碼如下WebServlet(/upload) MultipartConfig( fileSizeThreshold 1024 * 1024, maxFileSize 10 * 1024 * 1024, maxRequestSize 50 * 1024 * 1024 ) public class UploadServlet extends HttpServlet { Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { request.setCharacterEncoding(UTF-8); String uploadDir /data/upload; File dir new File(uploadDir); if (!dir.exists()) { dir.mkdirs(); } String remark null; for (Part part : request.getParts()) { if (part.getSubmittedFileName() null) { // 普通表單字段從輸入流中讀取值 remark readValue(part); continue; } // 文件Part String originName part.getSubmittedFileName(); String ext getExtension(originName); String newName UUID.randomUUID().toString().replace(-, ) ext; part.write(uploadDir File.separator newName); } response.getWriter().write(upload success, remark remark); } private String readValue(Part part) throws IOException { try (BufferedReader reader new BufferedReader( new InputStreamReader(part.getInputStream(), UTF-8))) { return reader.readLine(); } } private String getExtension(String fileName) { int index fileName.lastIndexOf(.); return index 0 ? fileName.substring(index) : ; } }這段代碼里有幾個細(xì)節(jié)值得說。第一part.write()的參數(shù)既可以是絕對路徑也可以是相對路徑。如果傳入相對路徑容器會把它拼接到MultipartConfig的location屬性指定的目錄后面。很多初學(xué)者在location沒設(shè)置的情況下調(diào)用part.write(abc.txt)結(jié)果文件不知道被寫到哪去了。最穩(wěn)妥的方式是直接傳一個絕對路徑別依賴location。第二文件名不要直接用前端傳上來的原始名字。一個是防覆蓋的問題不同用戶上傳同名文件會把彼此的文件覆蓋掉另一個是安全檢查惡意用戶可能通過文件名構(gòu)造路徑穿越攻擊。用UUID重新命名保留原始文件的擴(kuò)展名是性價比最高的做法。第三普通字段從Part里讀取時用readLine()就能拿到字符串值這是因?yàn)橐粋€表單字段的Part里內(nèi)容通常就一行。如果是textarea這種多行文本就需要循環(huán)讀取所有的行再拼接。3.3 關(guān)鍵參數(shù)調(diào)優(yōu)MultipartConfig三個屬性怎么設(shè)關(guān)于fileSizeThreshold這個參數(shù)控制的是“內(nèi)存緩沖區(qū)的上限”。當(dāng)上傳的文件大小小于這個閾值時容器會直接把數(shù)據(jù)存儲在內(nèi)存里讀起來很快。一旦文件超過閾值容器就會把數(shù)據(jù)轉(zhuǎn)寫到磁盤的臨時文件中防止大文件把內(nèi)存撐爆。所以如果你的應(yīng)用經(jīng)常要接收大文件建議把閾值調(diào)小一些比如256KB讓數(shù)據(jù)盡早走磁盤。如果只是收一些很小的圖片閾值可以設(shè)置2MB減少磁盤IO。maxFileSize和maxRequestSize建議嚴(yán)格設(shè)置不要設(shè)成-1放任不管。我見過一個項(xiàng)目沒設(shè)大小限制結(jié)果用戶上傳了一個10GB的視頻文件直接把磁盤打滿了。maxFileSize限制的是單個Part的大小maxRequestSize限制的是整個請求體的總大小包括所有文件和普通字段。如果請求內(nèi)容超過限制容器會拋出異常最常見的表現(xiàn)就是FileUploadException或IllegalStateException。4. 實(shí)操兼容老項(xiàng)目的Commons FileUpload方案4.1 組件選型什么場景還要用老方案雖然Servlet 3.0原生API用起來很順手但我在實(shí)際工作中確實(shí)遇到過不得不使用Commons FileUpload的場景。最常見的就是老的項(xiàng)目還跑在Servlet 2.5容器上或者項(xiàng)目里已經(jīng)有一套基于FileItem的封裝代碼牽一發(fā)而動全身。這種情況下即便你心里再想用原生API也不得不先把老代碼的運(yùn)作方式吃透。Commons FileUpload的核心類就兩個DiskFileItemFactory負(fù)責(zé)配置臨時文件策略和生成FileItem實(shí)例ServletFileUpload負(fù)責(zé)解析請求體、返回List 。FileItem的方法跟Part高度類似isFormField()判斷是不是普通字段getFieldName()拿字段名getName()拿文件名getInputStream()拿內(nèi)容流write()保存文件。使用這個方案有一個非常關(guān)鍵的前提必須在調(diào)用getParameter()之前就執(zhí)行解析因?yàn)榻馕鲞^程會消費(fèi)請求體的輸入流。一旦你提前調(diào)用了getParameter()容器已經(jīng)把輸入流消耗掉了此時再解析multipart你會發(fā)現(xiàn)拿到的集合是空的。這個坑我在排查問題時遇到過好幾次。4.2 核心代碼DiskFileItemFactory ServletFileUpload下面是一段標(biāo)準(zhǔn)的Commons FileUpload解析代碼兼顧了普通字段和文件的處理protected void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { String uploadDir /data/upload; if (!ServletFileUpload.isMultipartContent(request)) { response.getWriter().write(not multipart request); return; } DiskFileItemFactory factory new DiskFileItemFactory(); // 超過1MB的數(shù)據(jù)寫入臨時文件避免內(nèi)存溢出 factory.setSizeThreshold(1024 * 1024); factory.setRepository(new File(/tmp/upload_tmp)); ServletFileUpload upload new ServletFileUpload(factory); upload.setFileSizeMax(10 * 1024 * 1024); upload.setSizeMax(50 * 1024 * 1024); try { ListFileItem items upload.parseRequest(request); for (FileItem item : items) { if (item.isFormField()) { String fieldName item.getFieldName(); String value item.getString(UTF-8); // 處理普通字段 } else { String fileName new File(item.getName()).getName(); String ext getExtension(fileName); String newName UUID.randomUUID().toString().replace(-, ) ext; File storeFile new File(uploadDir, newName); item.write(storeFile); } } } catch (Exception e) { // 建議根據(jù)異常類型分別處理比如大小超限拋FileUploadBase.SizeLimitExceededException throw new ServletException(e); } }重點(diǎn)看兩個地方。第一item.getName()在IE瀏覽器老版本下可能返回完整的本地路徑比如C:\fakepath\test.txt所以代碼里用new File(item.getName()).getName()把純文件名提取出來防止把路徑也當(dāng)成文件名存下來。第二item.getString(UTF-8)這一句指定了編碼方式如果不傳參數(shù)默認(rèn)會按平臺編碼解碼中文亂碼的概率極高。還有一個容易被忽略的點(diǎn)工廠的setRepository設(shè)置了臨時文件目錄這個目錄必須存在且可寫。如果目錄不存在文件超過閾值轉(zhuǎn)寫臨時文件時會報異常而且這個異常信息不那么直觀排查起來挺費(fèi)勁。4.3 新舊方案對比一張表看清差異對比項(xiàng)Servlet 3.0原生APICommons FileUpload依賴JAR無需額外依賴commons-fileupload、commons-io容器要求Servlet 3.0及以上Servlet 2.3及以上核心對象PartFileItem獲取普通字段從Part輸入流讀取item.getString()文件大小限制MultipartConfig注解ServletFileUpload的set方法代碼簡潔度更簡潔略繁瑣容器解析時機(jī)容器內(nèi)部自動解析代碼中主動parseRequest這張表不是想說哪個方案絕對更好而是方便你根據(jù)自己項(xiàng)目的技術(shù)棧做決策。新項(xiàng)目無腦選Servlet 3.0原生API老項(xiàng)目既然已經(jīng)在用Commons FileUpload只要代碼運(yùn)行穩(wěn)定也不建議僅僅為了“更先進(jìn)”去重構(gòu)。5. 常見問題與排查技巧實(shí)錄5.1 現(xiàn)象對照表報錯與解決思路我在實(shí)際項(xiàng)目里遇到過大量文件上傳相關(guān)的問題很多問題表面上報錯千奇百怪根源卻就那么幾類。我整理了一份速查表按“現(xiàn)象-原因-解法”梳理遇到問題可以先對著表格檢查現(xiàn)象可能原因解決思路request.getPart()拋IllegalStateExceptionServlet未配置MultipartConfig補(bǔ)充注解或web.xml配置getParts()返回空集合表單未設(shè)置enctypemultipart/form-data或boundary異常檢查表單enctype設(shè)置getParameter()拿不到表單字段值multipart格式下容器不會填充parameterMap從Part/FileItem中讀取字段文件保存后只有文件名沒有內(nèi)容part.write()未指定絕對路徑且location未配置使用絕對路徑保存getSubmittedFileName()返回nullServlet容器版本較低或者Part是普通字段而非文件升級容器或者對Part做isFileField判斷上傳中文文件名出現(xiàn)亂碼請求編碼與解析編碼不一致setCharacterEncoding(UTF-8)并統(tǒng)一編碼大文件上傳時內(nèi)存溢出fileSizeThreshold配置過大或者未配置調(diào)低fileSizeThreshold啟用磁盤臨時文件上傳報SizeLimitExceededExceptionmaxFileSize或maxRequestSize超限增大參數(shù)限制或檢查是否誤設(shè)過小值臨時目錄堆積大量tmp文件請求異常終止導(dǎo)致臨時文件未清理容器通常會定期清理自己寫流時確保finally中清理臨時文件對照表格看自己的場景大部分問題都能快速定位。唯一要提醒的是getSubmittedFileName()這個方法雖然名字看起來很標(biāo)準(zhǔn)但它在Servlet 3.0規(guī)范里并未正式定義到Servlet 3.1才補(bǔ)齊。如果項(xiàng)目運(yùn)行在Servlet 3.0容器上建議用Part.getHeader(Content-Disposition)自行解析文件名或者直接升級容器版本。5.2 文件名、中文亂碼與安全過濾的實(shí)戰(zhàn)處理文件名處理是所有文件上傳功能里最需要花心思的環(huán)節(jié)。第一個問題是我上面反復(fù)提到的覆蓋文件名。用戶傳上來的文件名五花八門兩個人同時傳一個a.jpg再常見不過。如果不重新命名后上傳的文件就會覆蓋前面那個造成數(shù)據(jù)丟失。更嚴(yán)重的是有人可能在文件名里塞入../這類路徑穿越字符如果代碼用原始文件名拼路徑文件就可能被寫到目錄之外。雖然現(xiàn)代容器多少會做一些防護(hù)但自己這塊的防御不能省。我的建議是三段式處理先從原始文件名提取擴(kuò)展名然后生成UUID作為新名字最后拼上擴(kuò)展名。擴(kuò)展名最好再用一個白名單過濾一遍比如只允許.jpg、.png、.pdf、.txt等業(yè)務(wù)明確需要的類型。不要依賴Content-Type做類型校驗(yàn)因?yàn)镃ontent-Type是客戶端提供的完全可以偽造。真正更穩(wěn)妥的做法是保存后對圖片類文件重新讀取并校驗(yàn)它的實(shí)際格式。第二個問題是中文文件名亂碼。這個問題的根源在于瀏覽器先按照UTF-8編碼把文件名寫進(jìn)請求頭而Servlet容器在解析請求頭時如果沒按UTF-8解碼就會出現(xiàn)亂碼。在代碼開頭調(diào)用request.setCharacterEncoding(UTF-8)能解決一部分問題但注意這個方法只影響請求體的編碼對請求頭中Content-Disposition里的文件名解析不同容器行為有差異。因此我的兜底方案是在后端拿到文件名后嘗試重新解碼。比如發(fā)現(xiàn)文件名亂碼就用ISO-8859-1還原字節(jié)再按UTF-8編碼重新生成。這段代碼雖然看起來有點(diǎn)hack但在兼容老容器時非常管用。第三個問題是文件內(nèi)容的真實(shí)性與大小限制。在保存文件之前建議先用part.getSize()或item.getSize()判斷一下文件大小再結(jié)合業(yè)務(wù)提前拋錯。別等文件完全寫入磁盤之后才做校驗(yàn)?zāi)菢影渍糏O帶寬。如果需要限制圖片尺寸最好借助圖像處理工具類重新壓縮而不是讓用戶直接傳原圖。5.3 多文件上傳與場景擴(kuò)展的特殊處理多文件上傳在原生API下實(shí)現(xiàn)起來出乎意料地簡單。前端只要給文件輸入框加上multiple屬性后端遍歷getParts()時所有g(shù)etSubmittedFileName()不為null的Part都是文件循環(huán)保存即可。唯一要注意的是多個文件的name屬性可能相同不要通過getName()去區(qū)分文件而是直接遍歷所有Part。比如前端代碼長這樣form enctypemultipart/form-data methodpost action/upload input typefile namefiles multiple button typesubmit上傳/button /form后端這段偽代碼可以同時處理多個文件for (Part part : request.getParts()) { if (part.getSubmittedFileName() null) { continue; } // 逐個保存 part.write(uploadDir File.separator UUID.randomUUID().toString().replace(-, )); }這里有個細(xì)節(jié)如果一個文件Part在遍歷過程中沒做任何處理請求結(jié)束后容器會負(fù)責(zé)清理可能產(chǎn)生的臨時文件。但如果你手動調(diào)用了part.getInputStream()讀取了數(shù)據(jù)流一定要在finally塊里關(guān)閉InputStream。它有可能會占用臨時文件句柄導(dǎo)致文件鎖殘留。如果你在項(xiàng)目里使用了Spring MVC這類框架內(nèi)部的MultipartResolver本質(zhì)上也是在解析HttpServletRequest里的Part原理和我上面寫的一致。遇到框架上傳問題時不妨先從Servlet層面排查一遍很多時候框架報的錯根源都在容器解析和請求參數(shù)這一層。6. 最后再分享兩個排查小技巧寫到這里該收尾了補(bǔ)兩個我在實(shí)際排查中覺得特別有效的小技巧。第一個是抓原始請求體。當(dāng)你懷疑文件上傳數(shù)據(jù)根本沒到后端時不要急著打日志先抓原始請求體看看。用工具發(fā)一個multipart請求或者在后端攔截器里把request.getInputStream()的內(nèi)容打印出來觀察body中boundary、filename、Content-Disposition是否齊全。我排查過好幾次“明明傳了文件后端卻說沒收到”的問題最后都發(fā)現(xiàn)是前端請求把body搞丟了或者是nginx層把大請求體攔截了。這個辦法能直接定位是傳輸鏈路的問題還是后端解析的問題。第二個是給臨時文件目錄單獨(dú)做監(jiān)控。因?yàn)槲募蟼鞒３膳R時文件如果代碼里某條異常路徑?jīng)]有清理臨時文件時間長了會堆積大量垃圾占用磁盤空間。我習(xí)慣在運(yùn)維側(cè)給臨時目錄加一個定期清理任務(wù)比如清理三天前、大小超過一定閾值的臨時文件。很多人只關(guān)注上傳本身成功與否忽略了臨時文件清理這一環(huán)等到服務(wù)器磁盤告警才想起來?；氐阶詈唵蔚哪蔷湓捰肧ervlet容器接收文件上傳本質(zhì)就是理解multipart格式然后調(diào)用合適的API。把這些細(xì)節(jié)一條條理清了從getParts()方法拿到文件就不再是玄學(xué)而是徹底可控的工程行為。 Servlet文件上傳詳解：從multipart到getParts原生API
處理文件上傳大概是Java Web開發(fā)里最常被問到的需求之一。很多剛接觸Servlet的開發(fā)者以為從HttpServletRequest里拿上傳的文件就像拿表單參數(shù)一樣簡單——結(jié)果一調(diào)getParameter返回null或者getInputStream讀到一堆看不懂的二進(jìn)制再不然就是Connector上直接給你拋個IllegalStateException。這篇文章我就結(jié)合自己踩過的坑把“HttpServletRequest獲取上傳文件”這件事從頭到尾講透從multipart/form-data的底層格式到Servlet 3.0原生API的完整寫法再到老項(xiàng)目里那套第三方上傳組件的兼容方案以及各種讓人頭大的中文亂碼、內(nèi)存溢出、臨時文件清理問題全部梳理一遍。不管你是剛?cè)腴T的新手還是被老項(xiàng)目折磨過一陣子的開發(fā)者照著這篇文章的思路去調(diào)整自己的代碼基本都能落地。1. 先搞清楚需求文件上傳到底在解決什么問題1.1 從表單到請求上傳文件發(fā)生的完整鏈路“把文件傳給服務(wù)器”這件事放在HTTP的世界里其實(shí)沒那么復(fù)雜。瀏覽器把文件內(nèi)容塞進(jìn)HTTP請求體服務(wù)器從請求體里讀取字節(jié)流再想辦法還原成文件。關(guān)鍵就在于“塞進(jìn)去”這個動作的編碼方式。平時我們用得最多的表單提交默認(rèn)的編碼方式是application/x-www-form-urlencoded。這種格式下瀏覽器會把所有的表單數(shù)據(jù)拼成一個類似URL參數(shù)的字符串比如usernameadminpassword123456。這種格式傳純文本沒問題但是傳文件就不行了因?yàn)槲募?nèi)容是二進(jìn)制里面可能包含各種特殊字符甚至包含用于分隔字段的和直接按字符串拼接必然會亂套。所以表單里一旦出現(xiàn)input typefile就必須把form的enctype屬性設(shè)置為multipart/form-data。這時候?yàn)g覽器會把整個請求體切成若干個“段”Part每個段用一段隨機(jī)生成的boundary字符串隔開。這個boundary會同時出現(xiàn)在請求頭的Content-Type里比如Content-Type: multipart/form-data; boundary----WebKitFormBoundaryABC123。請求體就變成了類似這樣的結(jié)構(gòu)------WebKitFormBoundaryABC123 Content-Disposition: form-data; nameusername admin ------WebKitFormBoundaryABC123 Content-Disposition: form-data; namefile; filenametest.txt Content-Type: text/plain 文件內(nèi)容字節(jié)流 ------WebKitFormBoundaryABC123--服務(wù)器端要做的就是先根據(jù)Content-Type里的boundary把請求體切成一個個Part再從Part的Content-Disposition頭里解析出字段名、文件名最后把Part里的字節(jié)流保存起來。這件事Servlet容器在收到請求后其實(shí)已經(jīng)幫你做了大半你的代碼要做的只是調(diào)用方法拿結(jié)果。1.2 兩種主流實(shí)現(xiàn)方案怎么選在Java Web世界里拿到上傳文件這件事有兩條主流路線。一條是Servlet 3.0規(guī)范提供的原生API也就是通過HttpServletRequest的getPart()和getParts()方法直接拿到容器解析好的Part對象。只要你用的Servlet容器支持Servlet 3.0規(guī)范現(xiàn)在主流容器都支持比如Tomcat 7及以上的版本你的項(xiàng)目里不需要引入任何額外的JAR包一個注解加幾行代碼就能搞定。另一條路線是使用第三方上傳組件最經(jīng)典的就是Commons FileUpload。這個組件在Servlet 3.0規(guī)范出現(xiàn)之前就已經(jīng)存在了老項(xiàng)目里用得非常多它通過自己的解析器把請求體解析成List 代碼風(fēng)格和原生API差異很大但功能同樣完整。選擇哪條路線主要看你項(xiàng)目的實(shí)際情況。新項(xiàng)目我強(qiáng)烈建議直接走Servlet 3.0原生API零依賴、代碼簡潔、跟容器配合得也最順暢。老項(xiàng)目如果已經(jīng)在用Commons FileUpload且跑得好好的沒必要為了追求新而推翻重來后面章節(jié)我會詳細(xì)講兩種方案各自的完整寫法和注意點(diǎn)。2. 核心原理HttpServletRequest與multipart/form-data的關(guān)系2.1 Content-Type和boundary到底是怎么回事很多人寫文件上傳代碼的時候會忽略一個非?；A(chǔ)的問題請求頭里那兩個關(guān)鍵參數(shù)是干嘛用的Content-Type里不僅聲明了multipart/form-data還帶了一個boundary參數(shù)。boundary就是各個Part之間的“分隔線”它的值是一段隨機(jī)字符串瀏覽器保證這個字符串不會出現(xiàn)在文件內(nèi)容里。服務(wù)器解析請求體的時候就是靠這段boundary把一長串字節(jié)流切成一個個段落。這里有個特別容易踩的坑如果你手動構(gòu)建HTTP請求或者用某些HTTP客戶端工具發(fā)送multipart請求boundary沒配對服務(wù)器解析必然失敗。但用瀏覽器表單上傳時瀏覽器會自動生成boundary通常不會出問題。不過后端代碼里你會發(fā)現(xiàn)你根本不需要關(guān)心boundary是什么因?yàn)镾ervlet容器早就替你完成了拆分工作你拿到的Part對象就是拆分之后的產(chǎn)物。2.2 Part是什么容器幫你拆好的數(shù)據(jù)塊從開發(fā)者的視角來看Part就是multipart/form-data請求體中一個獨(dú)立的段落它對應(yīng)一個表單字段比如usernameadmin的普通輸入框?qū)?yīng)一個上傳文件。Part對象身上帶了幾個特別關(guān)鍵的方法getName()返回這個Part對應(yīng)的表單字段name屬性值比如input namefile這里返回的就是file。getSubmittedFileName()返回上傳文件的原始文件名注意這個方法在Servlet 3.1規(guī)范中才正式提供3.0版本下可能拿不到。getContentType()返回文件MIME類型比如image/png、text/plain。getSize()返回這個Part的字節(jié)數(shù)可以用來做文件大小的預(yù)判斷。getInputStream()拿到Part內(nèi)容的輸入流你可以自己把字節(jié)流讀到目標(biāo)文件。write(String fileName)容器幫我把Part內(nèi)容直接寫到一個文件里省去手動讀流的麻煩。需要特別注意的是Part對象里裝的不僅僅是文件。如果你在同一個表單里還放了普通輸入框比如姓名、備注之類的字段這些字段也會被封裝成Part對象只是它們的getSubmittedFileName()返回null且Content-Disposition里沒有filename字段。所以遍歷getParts()的時候要先判斷一下是不是文件Part。2.3 為什么getParameter在文件上傳時拿不到值這是我在很多初學(xué)者項(xiàng)目里看到的高頻問題。表單都設(shè)置enctypemultipart/form-data了代碼里request.getParameter(username)居然返回null搜索引擎一搜發(fā)現(xiàn)別人也有同樣的問題。原因在于一旦表單編碼方式變成multipart/form-data整個請求體就不再是那種usernameadminpassword123456的格式了。Servlet容器在處理普通格式請求時會把請求體自動解析到parameterMap里getParameter()自然就能拿到值。但遇到multipart格式時容器就不再執(zhí)行這個解析動作了它把請求體原樣保留下來等你通過getPart()/getParts()去讀取。所以getParameter()返回null是正常現(xiàn)象。正確的做法是在遍歷Part的時候判斷isFormField類型然后從Part的輸入流中讀取普通字段的值。這一點(diǎn)我會在下一章的完整示例代碼里展示出來。3. 實(shí)操用Servlet 3.0原生API獲取上傳文件3.1 前置準(zhǔn)備注解與配置一個都不能少Servlet 3.0原生API的使用前提是在你的Servlet類上標(biāo)注MultipartConfig注解或者在web.xml里配置multipart-config節(jié)點(diǎn)。這個注解就是告訴Servlet容器這個Servlet會接收multipart/form-data格式的請求請你幫我解析Part。如果你忘了加這個注解會有什么后果getParts()方法會正常返回一個空集合或者直接拋IllegalStateException具體表現(xiàn)取決于容器版本和實(shí)現(xiàn)。我身邊就有同事由于忘記加注解還到處找bug最后發(fā)現(xiàn)是配置缺失很容易浪費(fèi)大量時間。MultipartConfig注解有四個屬性可以配置它們決定了文件上傳的邊界與臨時文件策略屬性含義建議值fileSizeThreshold文件大小閾值超過該值的數(shù)據(jù)會從內(nèi)存轉(zhuǎn)寫到臨時文件建議設(shè)1MB左右maxFileSize單個文件允許的最大字節(jié)數(shù)根據(jù)業(yè)務(wù)場景設(shè)比如10MBmaxRequestSize整個multipart請求體允許的最大字節(jié)數(shù)建議比maxFileSize稍大比如50MBlocationPart.write()方法寫入文件的默認(rèn)目錄建議配置絕對路徑別忘了在doPost方法里先調(diào)用request.setCharacterEncoding(UTF-8)否則中文字段和文件名可能亂碼。這句話對普通表單同樣適用尤其在容器默認(rèn)編碼不是UTF-8的情況下。3.2 核心代碼一步步完成文件接收與保存直接給一個能跑通的基礎(chǔ)版本。假設(shè)前端表單里有一個文件輸入框namefile和一個普通輸入框nameremark后端Servlet的完整代碼如下WebServlet(/upload) MultipartConfig( fileSizeThreshold 1024 * 1024, maxFileSize 10 * 1024 * 1024, maxRequestSize 50 * 1024 * 1024 ) public class UploadServlet extends HttpServlet { Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { request.setCharacterEncoding(UTF-8); String uploadDir /data/upload; File dir new File(uploadDir); if (!dir.exists()) { dir.mkdirs(); } String remark null; for (Part part : request.getParts()) { if (part.getSubmittedFileName() null) { // 普通表單字段從輸入流中讀取值 remark readValue(part); continue; } // 文件Part String originName part.getSubmittedFileName(); String ext getExtension(originName); String newName UUID.randomUUID().toString().replace(-, ) ext; part.write(uploadDir File.separator newName); } response.getWriter().write(upload success, remark remark); } private String readValue(Part part) throws IOException { try (BufferedReader reader new BufferedReader( new InputStreamReader(part.getInputStream(), UTF-8))) { return reader.readLine(); } } private String getExtension(String fileName) { int index fileName.lastIndexOf(.); return index 0 ? fileName.substring(index) : ; } }這段代碼里有幾個細(xì)節(jié)值得說。第一part.write()的參數(shù)既可以是絕對路徑也可以是相對路徑。如果傳入相對路徑容器會把它拼接到MultipartConfig的location屬性指定的目錄后面。很多初學(xué)者在location沒設(shè)置的情況下調(diào)用part.write(abc.txt)結(jié)果文件不知道被寫到哪去了。最穩(wěn)妥的方式是直接傳一個絕對路徑別依賴location。第二文件名不要直接用前端傳上來的原始名字。一個是防覆蓋的問題不同用戶上傳同名文件會把彼此的文件覆蓋掉另一個是安全檢查惡意用戶可能通過文件名構(gòu)造路徑穿越攻擊。用UUID重新命名保留原始文件的擴(kuò)展名是性價比最高的做法。第三普通字段從Part里讀取時用readLine()就能拿到字符串值這是因?yàn)橐粋€表單字段的Part里內(nèi)容通常就一行。如果是textarea這種多行文本就需要循環(huán)讀取所有的行再拼接。3.3 關(guān)鍵參數(shù)調(diào)優(yōu)MultipartConfig三個屬性怎么設(shè)關(guān)于fileSizeThreshold這個參數(shù)控制的是“內(nèi)存緩沖區(qū)的上限”。當(dāng)上傳的文件大小小于這個閾值時容器會直接把數(shù)據(jù)存儲在內(nèi)存里讀起來很快。一旦文件超過閾值容器就會把數(shù)據(jù)轉(zhuǎn)寫到磁盤的臨時文件中防止大文件把內(nèi)存撐爆。所以如果你的應(yīng)用經(jīng)常要接收大文件建議把閾值調(diào)小一些比如256KB讓數(shù)據(jù)盡早走磁盤。如果只是收一些很小的圖片閾值可以設(shè)置2MB減少磁盤IO。maxFileSize和maxRequestSize建議嚴(yán)格設(shè)置不要設(shè)成-1放任不管。我見過一個項(xiàng)目沒設(shè)大小限制結(jié)果用戶上傳了一個10GB的視頻文件直接把磁盤打滿了。maxFileSize限制的是單個Part的大小maxRequestSize限制的是整個請求體的總大小包括所有文件和普通字段。如果請求內(nèi)容超過限制容器會拋出異常最常見的表現(xiàn)就是FileUploadException或IllegalStateException。4. 實(shí)操兼容老項(xiàng)目的Commons FileUpload方案4.1 組件選型什么場景還要用老方案雖然Servlet 3.0原生API用起來很順手但我在實(shí)際工作中確實(shí)遇到過不得不使用Commons FileUpload的場景。最常見的就是老的項(xiàng)目還跑在Servlet 2.5容器上或者項(xiàng)目里已經(jīng)有一套基于FileItem的封裝代碼牽一發(fā)而動全身。這種情況下即便你心里再想用原生API也不得不先把老代碼的運(yùn)作方式吃透。Commons FileUpload的核心類就兩個DiskFileItemFactory負(fù)責(zé)配置臨時文件策略和生成FileItem實(shí)例ServletFileUpload負(fù)責(zé)解析請求體、返回List 。FileItem的方法跟Part高度類似isFormField()判斷是不是普通字段getFieldName()拿字段名getName()拿文件名getInputStream()拿內(nèi)容流write()保存文件。使用這個方案有一個非常關(guān)鍵的前提必須在調(diào)用getParameter()之前就執(zhí)行解析因?yàn)榻馕鲞^程會消費(fèi)請求體的輸入流。一旦你提前調(diào)用了getParameter()容器已經(jīng)把輸入流消耗掉了此時再解析multipart你會發(fā)現(xiàn)拿到的集合是空的。這個坑我在排查問題時遇到過好幾次。4.2 核心代碼DiskFileItemFactory ServletFileUpload下面是一段標(biāo)準(zhǔn)的Commons FileUpload解析代碼兼顧了普通字段和文件的處理protected void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { String uploadDir /data/upload; if (!ServletFileUpload.isMultipartContent(request)) { response.getWriter().write(not multipart request); return; } DiskFileItemFactory factory new DiskFileItemFactory(); // 超過1MB的數(shù)據(jù)寫入臨時文件避免內(nèi)存溢出 factory.setSizeThreshold(1024 * 1024); factory.setRepository(new File(/tmp/upload_tmp)); ServletFileUpload upload new ServletFileUpload(factory); upload.setFileSizeMax(10 * 1024 * 1024); upload.setSizeMax(50 * 1024 * 1024); try { ListFileItem items upload.parseRequest(request); for (FileItem item : items) { if (item.isFormField()) { String fieldName item.getFieldName(); String value item.getString(UTF-8); // 處理普通字段 } else { String fileName new File(item.getName()).getName(); String ext getExtension(fileName); String newName UUID.randomUUID().toString().replace(-, ) ext; File storeFile new File(uploadDir, newName); item.write(storeFile); } } } catch (Exception e) { // 建議根據(jù)異常類型分別處理比如大小超限拋FileUploadBase.SizeLimitExceededException throw new ServletException(e); } }重點(diǎn)看兩個地方。第一item.getName()在IE瀏覽器老版本下可能返回完整的本地路徑比如C:\fakepath\test.txt所以代碼里用new File(item.getName()).getName()把純文件名提取出來防止把路徑也當(dāng)成文件名存下來。第二item.getString(UTF-8)這一句指定了編碼方式如果不傳參數(shù)默認(rèn)會按平臺編碼解碼中文亂碼的概率極高。還有一個容易被忽略的點(diǎn)工廠的setRepository設(shè)置了臨時文件目錄這個目錄必須存在且可寫。如果目錄不存在文件超過閾值轉(zhuǎn)寫臨時文件時會報異常而且這個異常信息不那么直觀排查起來挺費(fèi)勁。4.3 新舊方案對比一張表看清差異對比項(xiàng)Servlet 3.0原生APICommons FileUpload依賴JAR無需額外依賴commons-fileupload、commons-io容器要求Servlet 3.0及以上Servlet 2.3及以上核心對象PartFileItem獲取普通字段從Part輸入流讀取item.getString()文件大小限制MultipartConfig注解ServletFileUpload的set方法代碼簡潔度更簡潔略繁瑣容器解析時機(jī)容器內(nèi)部自動解析代碼中主動parseRequest這張表不是想說哪個方案絕對更好而是方便你根據(jù)自己項(xiàng)目的技術(shù)棧做決策。新項(xiàng)目無腦選Servlet 3.0原生API老項(xiàng)目既然已經(jīng)在用Commons FileUpload只要代碼運(yùn)行穩(wěn)定也不建議僅僅為了“更先進(jìn)”去重構(gòu)。5. 常見問題與排查技巧實(shí)錄5.1 現(xiàn)象對照表報錯與解決思路我在實(shí)際項(xiàng)目里遇到過大量文件上傳相關(guān)的問題很多問題表面上報錯千奇百怪根源卻就那么幾類。我整理了一份速查表按“現(xiàn)象-原因-解法”梳理遇到問題可以先對著表格檢查現(xiàn)象可能原因解決思路request.getPart()拋IllegalStateExceptionServlet未配置MultipartConfig補(bǔ)充注解或web.xml配置getParts()返回空集合表單未設(shè)置enctypemultipart/form-data或boundary異常檢查表單enctype設(shè)置getParameter()拿不到表單字段值multipart格式下容器不會填充parameterMap從Part/FileItem中讀取字段文件保存后只有文件名沒有內(nèi)容part.write()未指定絕對路徑且location未配置使用絕對路徑保存getSubmittedFileName()返回nullServlet容器版本較低或者Part是普通字段而非文件升級容器或者對Part做isFileField判斷上傳中文文件名出現(xiàn)亂碼請求編碼與解析編碼不一致setCharacterEncoding(UTF-8)并統(tǒng)一編碼大文件上傳時內(nèi)存溢出fileSizeThreshold配置過大或者未配置調(diào)低fileSizeThreshold啟用磁盤臨時文件上傳報SizeLimitExceededExceptionmaxFileSize或maxRequestSize超限增大參數(shù)限制或檢查是否誤設(shè)過小值臨時目錄堆積大量tmp文件請求異常終止導(dǎo)致臨時文件未清理容器通常會定期清理自己寫流時確保finally中清理臨時文件對照表格看自己的場景大部分問題都能快速定位。唯一要提醒的是getSubmittedFileName()這個方法雖然名字看起來很標(biāo)準(zhǔn)但它在Servlet 3.0規(guī)范里并未正式定義到Servlet 3.1才補(bǔ)齊。如果項(xiàng)目運(yùn)行在Servlet 3.0容器上建議用Part.getHeader(Content-Disposition)自行解析文件名或者直接升級容器版本。5.2 文件名、中文亂碼與安全過濾的實(shí)戰(zhàn)處理文件名處理是所有文件上傳功能里最需要花心思的環(huán)節(jié)。第一個問題是我上面反復(fù)提到的覆蓋文件名。用戶傳上來的文件名五花八門兩個人同時傳一個a.jpg再常見不過。如果不重新命名后上傳的文件就會覆蓋前面那個造成數(shù)據(jù)丟失。更嚴(yán)重的是有人可能在文件名里塞入../這類路徑穿越字符如果代碼用原始文件名拼路徑文件就可能被寫到目錄之外。雖然現(xiàn)代容器多少會做一些防護(hù)但自己這塊的防御不能省。我的建議是三段式處理先從原始文件名提取擴(kuò)展名然后生成UUID作為新名字最后拼上擴(kuò)展名。擴(kuò)展名最好再用一個白名單過濾一遍比如只允許.jpg、.png、.pdf、.txt等業(yè)務(wù)明確需要的類型。不要依賴Content-Type做類型校驗(yàn)因?yàn)镃ontent-Type是客戶端提供的完全可以偽造。真正更穩(wěn)妥的做法是保存后對圖片類文件重新讀取并校驗(yàn)它的實(shí)際格式。第二個問題是中文文件名亂碼。這個問題的根源在于瀏覽器先按照UTF-8編碼把文件名寫進(jìn)請求頭而Servlet容器在解析請求頭時如果沒按UTF-8解碼就會出現(xiàn)亂碼。在代碼開頭調(diào)用request.setCharacterEncoding(UTF-8)能解決一部分問題但注意這個方法只影響請求體的編碼對請求頭中Content-Disposition里的文件名解析不同容器行為有差異。因此我的兜底方案是在后端拿到文件名后嘗試重新解碼。比如發(fā)現(xiàn)文件名亂碼就用ISO-8859-1還原字節(jié)再按UTF-8編碼重新生成。這段代碼雖然看起來有點(diǎn)hack但在兼容老容器時非常管用。第三個問題是文件內(nèi)容的真實(shí)性與大小限制。在保存文件之前建議先用part.getSize()或item.getSize()判斷一下文件大小再結(jié)合業(yè)務(wù)提前拋錯。別等文件完全寫入磁盤之后才做校驗(yàn)?zāi)菢影渍糏O帶寬。如果需要限制圖片尺寸最好借助圖像處理工具類重新壓縮而不是讓用戶直接傳原圖。5.3 多文件上傳與場景擴(kuò)展的特殊處理多文件上傳在原生API下實(shí)現(xiàn)起來出乎意料地簡單。前端只要給文件輸入框加上multiple屬性后端遍歷getParts()時所有g(shù)etSubmittedFileName()不為null的Part都是文件循環(huán)保存即可。唯一要注意的是多個文件的name屬性可能相同不要通過getName()去區(qū)分文件而是直接遍歷所有Part。比如前端代碼長這樣form enctypemultipart/form-data methodpost action/upload input typefile namefiles multiple button typesubmit上傳/button /form后端這段偽代碼可以同時處理多個文件for (Part part : request.getParts()) { if (part.getSubmittedFileName() null) { continue; } // 逐個保存 part.write(uploadDir File.separator UUID.randomUUID().toString().replace(-, )); }這里有個細(xì)節(jié)如果一個文件Part在遍歷過程中沒做任何處理請求結(jié)束后容器會負(fù)責(zé)清理可能產(chǎn)生的臨時文件。但如果你手動調(diào)用了part.getInputStream()讀取了數(shù)據(jù)流一定要在finally塊里關(guān)閉InputStream。它有可能會占用臨時文件句柄導(dǎo)致文件鎖殘留。如果你在項(xiàng)目里使用了Spring MVC這類框架內(nèi)部的MultipartResolver本質(zhì)上也是在解析HttpServletRequest里的Part原理和我上面寫的一致。遇到框架上傳問題時不妨先從Servlet層面排查一遍很多時候框架報的錯根源都在容器解析和請求參數(shù)這一層。6. 最后再分享兩個排查小技巧寫到這里該收尾了補(bǔ)兩個我在實(shí)際排查中覺得特別有效的小技巧。第一個是抓原始請求體。當(dāng)你懷疑文件上傳數(shù)據(jù)根本沒到后端時不要急著打日志先抓原始請求體看看。用工具發(fā)一個multipart請求或者在后端攔截器里把request.getInputStream()的內(nèi)容打印出來觀察body中boundary、filename、Content-Disposition是否齊全。我排查過好幾次“明明傳了文件后端卻說沒收到”的問題最后都發(fā)現(xiàn)是前端請求把body搞丟了或者是nginx層把大請求體攔截了。這個辦法能直接定位是傳輸鏈路的問題還是后端解析的問題。第二個是給臨時文件目錄單獨(dú)做監(jiān)控。因?yàn)槲募蟼鞒３膳R時文件如果代碼里某條異常路徑?jīng)]有清理臨時文件時間長了會堆積大量垃圾占用磁盤空間。我習(xí)慣在運(yùn)維側(cè)給臨時目錄加一個定期清理任務(wù)比如清理三天前、大小超過一定閾值的臨時文件。很多人只關(guān)注上傳本身成功與否忽略了臨時文件清理這一環(huán)等到服務(wù)器磁盤告警才想起來?；氐阶詈唵蔚哪蔷湓捰肧ervlet容器接收文件上傳本質(zhì)就是理解multipart格式然后調(diào)用合適的API。把這些細(xì)節(jié)一條條理清了從getParts()方法拿到文件就不再是玄學(xué)而是徹底可控的工程行為。