Java HTTP 請求 URL 參數編碼：使用 URLEncoder 解決非法字元錯誤

問題現象

拼接 URL 參數時包含空格/中文/特殊字元，拋出 Illegal character in query 或伺服器解析錯誤。

根本原因

URL 查詢字串僅允許 ASCII 字母數字及 - _ . ~，其他字元必須 Percent-Encoding (URL Encoding)。

正確做法：URLEncoder.encode

String query = URLEncoder.encode(editText.getText().toString(), StandardCharsets.UTF_8.name());
String url = "https://example.com/search?q=" + query;

// 完整範例
String baseUrl = "https://api.example.com/endpoint";
String param1 = URLEncoder.encode(value1, "UTF-8");
String param2 = URLEncoder.encode(value2, "UTF-8");
String url = baseUrl + "?param1=" + param1 + "¶m2=" + param2;

關鍵細節

• 編碼單個參數值，而非整個 URL（避免編碼 ? & = 等結構字元）。
• 指定 UTF-8：StandardCharsets.UTF_8 或 "UTF-8"，避免平台預設編碼不一致。
• 空格編碼為 + 或 %20：URLEncoder 依 RFC 3986 將空格編為 +，大多數伺服器支援；若需 %20 可 .replace("+", "%20")。

現代替代：Uri.Builder / OkHttp HttpUrl

// Android Uri.Builder (自動編碼)
Uri uri = new Uri.Builder()
    .scheme("https")
    .authority("api.example.com")
    .appendPath("endpoint")
    .appendQueryParameter("param1", value1)  // 自動編碼
    .appendQueryParameter("param2", value2)
    .build();
String url = uri.toString();

// OkHttp HttpUrl (推薦)
HttpUrl url = new HttpUrl.Builder()
    .scheme("https")
    .host("api.example.com")
    .addPathSegment("endpoint")
    .addQueryParameter("param1", value1)
    .addQueryParameter("param2", value2)
    .build();

常見誤區

• 手動拼接字串："url?param=" + value 不編碼，極易出錯。
• 編碼整個 URL：URLEncoder.encode(fullUrl) 會破壞結構字元。
• 忽略編碼：純 ASCII 參數碰巧能跑，一旦含中文/特殊字元即崩潰。

總結

永遠使用標準庫/框架提供的 URL 建構器（Uri.Builder、HttpUrl、URLEncoder），手動拼接是 Bug 溫床。