Java FileItem 類核心方法詳解與文件上傳實戰指南

前言

在 Java Web 開發中，FileItem 是 Apache Commons FileUpload 庫的核心類，封裝了表單欄位與上傳文件的數據。掌握其常用方法對於實現健壯的文件上傳功能至關重要。本文將系統梳理 10 個核心方法的用法與注意事項。

核心方法速查表

關鍵方法深度解析

1. isFormField() - 欄位類型判斷

List<FileItem> items = upload.parseRequest(request);
for (FileItem item : items) {
    if (item.isFormField()) {
        // 處理普通表單欄位：username、password 等
        String fieldName = item.getFieldName();
        String value = item.getString("UTF-8");
    } else {
        // 處理文件上傳
        String fileName = item.getName();
        // ...
    }
}

2. getName() - 文件名獲取與跨瀏覽器兼容

瀏覽器差異：

• IE：C:\Users\Admin\Documents\photo.jpg
• Chrome/Firefox/Safari：photo.jpg

統一處理最佳實踐：

String fileName = item.getName();
if (fileName != null) {
    fileName = fileName.substring(fileName.lastIndexOf(File.separator) + 1);
    // 進一步處理：UUID 重命名、副檔名驗證等
}

3. getString(String encoding) - 亂碼終結者

// 錯誤示範：使用預設編碼導致中文亂碼
String value = item.getString();

// 正確做法：顯式指定 UTF-8
String value = item.getString("UTF-8");

4. write(File) vs getInputStream() - 存儲策略選擇

5. delete() - 資源洩漏防範

try {
    // 文件處理邏輯
    item.write(targetFile);
} finally {
    // 確保臨時文件被清理，防止磁盤佔用
    item.delete();
}

注意： 雖然 GC 會最終清理，但高併發下臨時文件堆積會導致磁盤空間耗盡，finally 區塊調用 delete() 是最佳實踐。

完整上傳處理範例

@PostMapping("/upload")
public ResponseEntity<String> handleUpload(HttpServletRequest request) {
    ServletFileUpload upload = new ServletFileUpload(new DiskFileItemFactory());
    upload.setHeaderEncoding("UTF-8");
    
    try {
        List<FileItem> items = upload.parseRequest(request);
        for (FileItem item : items) {
            if (item.isFormField()) {
                // 普通欄位處理
                formData.put(item.getFieldName(), item.getString("UTF-8"));
            } else {
                // 文件處理
                String originalName = item.getName();
                if (originalName == null || originalName.isEmpty()) continue;
                
                String safeName = originalName.substring(
                    originalName.lastIndexOf(File.separator) + 1
                );
                String contentType = item.getContentType();
                long size = item.getSize();
                
                // 業務驗證：類型、大小限制
                if (!allowedTypes.contains(contentType)) {
                    return ResponseEntity.badRequest().body("不支援的文件類型");
                }
                if (size > MAX_SIZE) {
                    return ResponseEntity.badRequest().body("文件過大");
                }
                
                // 存儲：使用 UUID 避免衝突
                String ext = safeName.substring(safeName.lastIndexOf('.'));
                String storedName = UUID.randomUUID() + ext;
                File dest = new File(UPLOAD_DIR, storedName);
                
                item.write(dest); // 或使用 getInputStream() 配合 Files.copy()
                
                // 記錄元數據到數據庫
                fileService.saveMetadata(safeName, storedName, contentType, size);
            }
        }
        return ResponseEntity.ok("上傳成功");
    } catch (Exception e) {
        log.error("上傳失敗", e);
        return ResponseEntity.internalServerError().body("上傳異常");
    }
}

常見坑點總結

1. 編碼問題：永遠使用 getString("UTF-8")，並確保 ServletFileUpload.setHeaderEncoding("UTF-8")
2. 文件名安全：必須去除路徑資訊，防止目錄遍歷攻擊
3. 臨時文件清理：finally 中調用 delete()
4. 大文件處理：超過閾值自動寫入臨時文件，需配置 DiskFileItemFactory.setSizeThreshold()
5. 併發安全：使用 UUID 或時間戳重命名，避免同名覆蓋

總結

FileItem 雖然 API 簡單，但細節決定成敗。掌握其 10 個核心方法的語義與邊界條件，配合恰當的異常處理與安全防護，即可構建企業級的文件上傳服務。建議收藏本文作為開發參考手冊。