Android HttpURLConnection 發送 POST 請求完整指南

核心步驟

1. 建立 URL 物件
2. 開啟連線並轉型為 HttpURLConnection
3. 設定請求屬性：setDoOutput(true)、setRequestMethod("POST")、setRequestProperty 等
4. 取得 OutputStream 寫入請求體
5. 呼叫 getInputStream() 觸發真正送出並讀取回應
6. 關閉資源流

完整範例程式碼

public String postRequest(String urlString, String jsonBody) throws IOException {
    URL url = new URL(urlString);
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    
    // 設定請求參數
    conn.setDoOutput(true);           // 允許輸出流（POST 必須）
    conn.setDoInput(true);            // 允許輸入流（預設 true）
    conn.setUseCaches(false);         // POST 不使用快取
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
    conn.setRequestProperty("Accept", "application/json");
    conn.setConnectTimeout(10000);    // 連線逾時 10 秒
    conn.setReadTimeout(10000);       // 讀取逾時 10 秒
    
    // 寫入請求體
    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = jsonBody.getBytes(StandardCharsets.UTF_8);
        os.write(input, 0, input.length);
    }
    
    // 讀取回應
    int responseCode = conn.getResponseCode();
    InputStream is = (responseCode >= 200 && responseCode < 300) 
                     ? conn.getInputStream() 
                     : conn.getErrorStream();
    
    try (BufferedReader br = new BufferedReader(new InputStreamReader(is, StandardCharsets.UTF_8))) {
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) sb.append(line);
        return sb.toString();
    } finally {
        conn.disconnect();
    }
}

常見踩坑提醒

• 必須在 connect() 或 getOutputStream() 前設定所有屬性，否則會拋出 IllegalStateException。
• 請求體只能寫入一次，寫完關閉 OutputStream 後不可再寫；若需重送必須重新建立連線。
• 回應碼非 2xx 時請讀取 getErrorStream()，否則會丟失錯誤訊息。
• Android 9+ 預設禁用明文傳輸，需在 AndroidManifest.xml 設定 android:usesCleartextTraffic="true" 或改用 HTTPS。

進階：使用 OkHttp 簡化流程

現代 Android 開發建議直接使用 OkHttp，程式碼更簡潔且支援連線池、自動重試、攔截器等功能：

OkHttpClient client = new OkHttpClient();
RequestBody body = RequestBody.create(jsonBody, MediaType.get("application/json; charset=utf-8"));
Request request = new Request.Builder()
    .url(urlString)
    .post(body)
    .build();
try (Response response = client.newCall(request).execute()) {
    return response.body().string();
}

結語

掌握 HttpURLConnection 底層運作有助於除錯，但實務上強烈建議採用成熟的網路庫（OkHttp、Retrofit）以提升開發效率與穩定性。