HttpClient 4.2.1 文件上傳中文亂碼解決：MultipartEntity 與 PostMethod 兩種方式

HttpClient 4.2.1 文件上傳中文/文件名亂碼完美解決

HttpClient 4.x 兩種上傳 API（HttpPost + MultipartEntity、PostMethod）分別設置 UTF-8 編碼的關鍵代碼片段。

方式 A：HttpPost + MultipartEntity（推薦）

HttpPost httpPost = new HttpPost(url);
// 關鍵：構造 MultipartEntity 時指定 Charset.UTF-8
MultipartEntity reqEntity = new MultipartEntity(
    HttpMultipartMode.BROWSER_COMPATIBLE,
    null,
    Charset.forName("UTF-8")
);

FileBody bin = new FileBody(new File(localFilePath));
// 字符串部分顯式指定 ContentType UTF-8
StringBody userName = new StringBody("張三", ContentType.create("text/plain", Consts.UTF_8));

reqEntity.addPart("file", bin);
reqEntity.addPart("userName", userName);
httpPost.setEntity(reqEntity);

方式 B：PostMethod（舊 API，兼容模式）

PostMethod postMethod = new PostMethod(url);
// 設置請求體編碼
postMethod.getParams().setParameter(HttpMethodParams.HTTP_CONTENT_CHARSET, "utf-8");
// 文件上傳需配合 Part[] 構建，略

核心原理

• MultipartEntity 第三個構造參數 charset 決定生成的 Content-Type: multipart/form-data; charset=UTF-8 及各 Part 的編碼。
• StringBody 使用 ContentType.create("text/plain", Consts.UTF_8) 顯式聲明字符集，避免默認 ISO-8859-1 導致中文亂碼。
• 文件名中文：FileBody 內部會對文件名做 RFC 5987 編碼（filename*=UTF-8''...），現代瀏覽器/服務端均支持。

常見坑點

1. 未指定 Charset.forName("UTF-8") 導致默認 ISO-8859-1。
2. 服務端未正確解析 filename* 屬性，建議服務端優先讀取 filename*，回退 filename。
3. 大文件建議使用 HttpClientBuilder.create().setConnectionManager(...).build() 連接池複用。