Struts2 文件上傳基礎（一）：Commons FileUpload 原生用法詳解

核心類與職責

• FileItem：封裝單個表單項（含文件與普通字段），上傳核心對象
• FileUploadBase：解析請求、驗證大小/類型，子類 ServletFileUpload 常用於 Servlet 環境
• DiskFileItemFactory：控制臨時存儲策略
  • repository：臨時目錄（默認 java.io.tmpdir）
  • sizeThreshold：內存緩衝閾值，超過則寫入臨時文件
• ServletFileUpload.setSizeMax()：總上傳大小限制

表單必要條件

1. method="post"
2. enctype="multipart/form-data"

完整 Servlet 實現示例

upload.jsp

<form method="post" action="UploadServlet" enctype="multipart/form-data">
  用戶名: <input type="text" name="user.username"/><br/>
  密碼: <input type="text" name="user.password"/><br/>
  文件1: <input type="file" name="file1"/><br/>
  文件2: <input type="file" name="file2"/><br/>
  <input type="submit" value="上傳"/>
</form>

UploadServlet.doPost()

DiskFileItemFactory factory = new DiskFileItemFactory();
factory.setSizeThreshold(1024 * 128);           // 128KB 內存緩衝
factory.setRepository(new File("C:/temp"));     // 臨時目錄

ServletFileUpload upload = new ServletFileUpload(factory);
upload.setSizeMax(1024 * 1024 * 512);           // 512MB 總限制

List<FileItem> items = upload.parseRequest(request);
for (FileItem item : items) {
    if (!item.isFormField()) {                  // 過濾普通字段
        item.write(new File("D:/upload", item.getName()));
    }
}

關鍵注意點

• isFormField() 必須判斷，否則普通輸入框也會被當作文件處理
• 臨時目錄權限需可寫，生產環境建議配置專用磁盤
• 大文件建議調大 sizeThreshold 減少內存壓力
• 異常處理要完善，確保臨時文件清理

為什麼 Struts2 要封裝它？

原生 API 需手動解析、遍歷、判斷、寫入，代碼分散在 Servlet 中。Struts2 通過攔截器自動完成解析→參數映射→Action 注入，實現「無感上傳」，開發者只關注業務拷貝邏輯。