修復 commons-fileupload 自訂 Header 遺失 Bug：原始碼層級深度分析與熱修復方案

Apache Commons FileUpload 是檔案上傳的經典元件，但在處理 multipart/mixed 巢狀結構 且包含自訂 Header 時，會遺失內層部分的 FileItemHeaders。本文從源碼 FileUploadBase.findNextItem() 切入，定位缺陷並提供最小侵入性修復方案。

問題重現場景

• 前端自行組裝 multipart 請求，在檔案部分加入自訂 Header（如 X-File-Meta: {...}）。
• 後端用 ServletFileUpload.parseRequest(req) 解析。
• 取得 FileItemStream 後，呼叫 getHeaders() 發現自訂 Header 遺失，僅剩 Content-Disposition、Content-Type。

源碼定位：FileUploadBase.findNextItem()

關鍵邏輯（簡化）：

FileItemHeaders headers = getParsedHeaders(multi.readHeaders());
// ... 解析 fieldName、fileName ...
// 外層 part：建立 FileItemStreamImpl(fileName, fieldName, contentType, isFormField, contentLength)
// 內層 part (巢狀 multipart/mixed)：
// 原始碼：currentItem = new FileItemStreamImpl(fileName, currentFieldName, headers.getHeader(CONTENT_TYPE), false, getContentLength(headers));
// 缺陷：未將 headers 傳入建構子！

修復方案：擴充建構子並透傳 Headers

1. 新增帶 Headers 的建構子 於 FileItemStreamImpl：

FileItemStreamImpl(String pName, String pFieldName, String pContentType,
                   boolean pFormField, long pContentLength, FileItemHeaders headers)
        throws IOException {
    // ... 原有初始化 ...
    if (headers != null) {
        this.headers = headers;  // 關鍵：保存完整 Headers
    }
    // ... 流初始化 ...
}

2. 修改 findNextItem() 內層分支呼叫新建構子：

currentItem = new FileItemStreamImpl(fileName, currentFieldName,
        headers.getHeader(CONTENT_TYPE), false,
        getContentLength(headers), headers); // 透傳 headers

熱修復部署策略（無需重新編譯 Jar）

若專案無法升級元件版本，可採用 Java Agent / ByteBuddy 執行期重定義類別：

new AgentBuilder.Default()
    .type(named("org.apache.commons.fileupload.FileUploadBase$FileItemStreamImpl"))
    .transform((builder, typeDescription, classLoader, module) ->
        builder.method(named("<init>").and(takesArguments(6)))
             .intercept(MethodDelegation.to(FixHeadersInterceptor.class)))
    .installOn(instrumentation);

或更簡單：將修復後的 FileUploadBase.class、FileItemStreamImpl.class 放入專案 WEB-INF/classes（類載入器優先級高於 Jar），即可覆蓋生效。

驗證測試

// 單元測試片段
FileItemStream item = upload.getItemIterator(req).next();
FileItemHeaders headers = item.getHeaders();
assertNotNull(headers.getHeader("X-File-Meta")); // 通過

官方修正進度

此 Issue 已在 Commons FileUpload 1.4+ 修正（FILEUPLOAD-300），建議升級至 1.4 以上版本為根本解決。若受限於舊版相依，採用上述熱修復即可快速止血。

避坑指南

• 勿在 FileItemHeaders 中放入大型物件，Headers 會隨每個 part 駐留記憶體。
• 巢狀 multipart 層級超過 2 層時，邊界解析複雜度指數上升，建議協議設計扁平化。
• 同步升級 commons-io 至 2.11+，避免 LimitedInputStream 相關記憶體洩漏。

深入源碼定位並修復第三方元件 Bug，是資深工程師不可或缺的核心能力；掌握熱修復技術更能在無法升級依賴時從容應對。