零代碼修改遷移：從 SmartUpload 到 Apache FileUpload 的適配器模式實戰

項目背景與痛點

舊系統大量使用 SmartUpload 處理檔案上傳，但其單檔限制約 10 MB，無法滿足新需求（≥50 MB）。全量替換為 Apache Commons FileUpload 需修改 50 處代碼，風險極高。採用適配器模式，編寫同名類 SmartUpload 封裝 FileUpload 核心，實現「零業務代碼修改」平滑遷移。

原有業務代碼片段

SmartUpload objUpload = new SmartUpload(pageContext);
if (objUpload.getCount() > 0) {
    for (int i = 1; i <= objUpload.getCount(); i++) {
        ps.setString(9, objUpload.getUgetContentType(i));
        ps.setString(10, objUpload.getUFileName(i));
        ps.setBinaryStream(11, objUpload.getUFileInputStream(i), objUpload.getFLength(i));
    }
}

適配器核心實現

關鍵設計決策

• 同包同名：置於 gui 包，類名仍為 SmartUpload，ClassLoader 優先加載，原有 import 無需變動。
• 構造器重載：兼容原有四種構造方式，新增 filesize 參數控制上限（預設 100 MB）。
• 內部存儲結構：Hashtable<String, FileItem> files 按序號索引上傳檔案；Hashtable<String, Hashtable> parameters 存儲普通表單欄位，支援同名多值。
• 編碼處理：預設 GBK，可透過構造器指定，解決中文檔名亂碼。

核心初始化邏輯 pageinit()

DiskFileItemFactory factory = new DiskFileItemFactory();
factory.setSizeThreshold(4096); // 4 KB 閾值，超過寫臨時檔
ServletFileUpload upload = new ServletFileUpload(factory);
upload.setHeaderEncoding(this.pencoding);
upload.setFileSizeMax(this.filemaxsize); // 單檔大小限制

List<FileItem> items = upload.parseRequest(request);
for (FileItem item : items) {
    if (item.isFormField()) {
        // 普通欄位存入 parameters
    } else if (item.getSize() > 0) { // 過濾空檔案欄位
        if (item.getSize() > filemaxsize) { maxflag = 1; }
        files.put(String.valueOf(++filecount), item);
    }
}

關鍵 API 映射表

遷移效果與優勢

• 零業務代碼變更：JSP/Servlet 完全無感知。
• 大檔支援：突破 10 MB 限制，可配置至 100 MB 甚至更高。
• 編碼健壯：統一處理中文參數與檔名。
• 擴展性：後續可輕鬆加入進度條、多檔並發等 FileUpload 高級特性。

注意事項

1. 需引入 commons-fileupload、commons-io 依賴。
2. 臨時檔目錄權限需可寫；生產環境建議配置 repository 指定專用目錄。
3. clean() 方法預留資源釋放邏輯，FileUpload 會自動清理臨時檔，通常無需額外代碼。