Java HTTP 通訊實戰：基於 HttpClient 4.x 的 POST 請求封裝與編碼處理

Java HTTP 通訊實戰：基於 HttpClient 4.x 的 POST 請求封裝與編碼處理

Android 可用 Volley/OkHttp，但標準 Java 專案常用 Apache HttpClient（4.x/5.x）或 JDK 11+ HttpClient。本文提供基於 HttpClient 4.x 的通用 POST 工具方法，涵蓋參數編碼、回應處理與異常捕獲。

核心工具方法

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
import java.util.List;

public class HttpUtil {
    /**
     * 發送 POST 請求並返回字串回應
     * @param url 請求地址
     * @param params 表單參數列表
     * @return 回應內容字串，異常返回 null
     */
    public static String sendPost(String url, List<NameValuePair> params) {
        HttpPost httpPost = new HttpPost(url);
        try {
            // 設定表單實體，指定 UTF-8 編碼
            httpPost.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));
            
            // 執行請求
            HttpResponse response = new DefaultHttpClient().execute(httpPost);
            
            // 讀取回應實體
            HttpEntity entity = response.getEntity();
            if (entity != null) {
                return EntityUtils.toString(entity, "UTF-8");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }
}

使用範例

List<NameValuePair> params = new ArrayList<>();
params.add(new BasicNameValuePair("username", "admin"));
params.add(new BasicNameValuePair("password", "123456"));

String result = HttpUtil.sendPost("https://api.example.com/login", params);
System.out.println("回應：" + result);

關鍵注意事項

1. 編碼一致性： UrlEncodedFormEntity 與 EntityUtils.toString 均指定 UTF-8，避免中文亂碼。
2. 連線管理： 範例每次 new DefaultHttpClient() 效能低，生產環境應使用 PoolingHttpClientConnectionManager 複用連線。
3. 超時設定： 必須配置連線/讀取超時，防止阻塞：

RequestConfig config = RequestConfig.custom()
    .setConnectTimeout(5000)
    .setSocketTimeout(10000)
    .build();
httpPost.setConfig(config);

遷移至 HttpClient 5.x / JDK 11 HttpClient

• HttpClient 5.x： 類別包變更為 org.apache.hc.client5.http.*，API 相似但更現代化（支援非阻塞、HTTP/2）。
• JDK 11+ HttpClient： 無第三方依賴，支援 HTTP/2、WebSocket、CompletableFuture 非阻塞：

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString("username=admin&password=123456"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

根據專案 JDK 版本與依賴策略選擇最適合的 HTTP 客端實現。