Java HTTP 请求中 URL 查询参数的正确编码方法-java教程-PHP中文网

Java HTTP 请求中 URL 查询参数的正确编码方法

本文详解 Java 中构造含特殊字符（如 $、{、}、'、"）的 REST API 查询 URL 时，如何精准使用 URLEncoder 对 query 参数值单独编码，避免 URISyntaxException 或 HTTP 400 错误。

本文详解 java 中构造含特殊字符（如 `$`、`{`、`}`、`'`、`"`）的 rest api 查询 url 时，如何精准使用 `urlencoder` 对 query 参数值单独编码，避免 `urisyntaxexception` 或 http 400 错误。

在 Java 中通过 HttpURLConnection（或任何 HTTP 客户端）调用 REST 接口时，若 URL 查询字符串（query string）包含 MongoDB 风格查询语法（如 {$and:[{...}]}）、引号、花括号、美元符等非标准 URL 字符，直接拼接原始字符串或全量 URI 编码均会导致失败：前者触发 URISyntaxException（非法字符），后者因过度编码（如将 /、:、?、= 等分隔符也编码）破坏 URL 结构，导致服务端无法解析，返回 HTTP 400。

✅ 正确做法是：仅对每个 query parameter 的 value 部分进行 UTF-8 编码，而 protocol、host、path、?、&、= 等 URL 固有结构字符必须保持原样。

以问题中的查询为例：

OpenJDK 24

下载

String baseUrl = "https://host.com/rest/v14/commerceDocumentsSimplifiedRenewalsTransaction";
String queryValue = "{$and:[{customerSignatureRequestSentOn_srq:{$gte: '2023-04-01'}},{customerSignatureRequestSentOn_srq:{$lte: '2023-06-04'}},{customerSigned_srq:{ $exists: false }},{renewalType_srq:{ $eq: \"Amendment\" }},{subType_srq:{ $eq: \"Proactive\" }}]}";
String fieldsValue = "quoteNumber_srq,customerSignatureRequestSentOn_srq";

// ✅ 关键：仅编码 value，保留 ? 和 & 等结构
String fullUrl = baseUrl 
    + "?q=" + URLEncoder.encode(queryValue, StandardCharsets.UTF_8)
    + "&fields=" + URLEncoder.encode(fieldsValue, StandardCharsets.UTF_8);

URL url = new URL(fullUrl);
HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
conn.setRequestProperty("Authorization", generateBasicAuthInHeaders("***", "***"));
conn.setRequestProperty("Content-Type", "application/json"); // 注意：GET 请求通常无需设 Content-Type，或应为 text/plain；此处建议移除或按服务端要求调整
conn.setConnectTimeout(3000);
conn.setRequestMethod("GET");
conn.connect();

int responseCode = conn.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
    // 处理响应...
}

⚠️ 重要注意事项：

URLEncoder.encode(...) 默认使用 application/x-www-form-urlencoded 规则（空格→+，非 ASCII→%XX），完全适用于 query parameter value，但绝不可用于整个 URL 字符串；
不要对 ?、&、=、/、: 等 URL 元字符编码，否则服务端无法识别参数边界；

若使用 UriBuilder（如 Jersey Client），应分别传入 key 和未编码的 value，由 builder 自动编码 value：

URI uri = UriBuilder.fromPath("https://host.com/rest/v14/commerceDocumentsSimplifiedRenewalsTransaction")
    .queryParam("q", queryValue)           // value 自动编码
    .queryParam("fields", fieldsValue)     // value 自动编码
    .build();

Content-Type 在 GET 请求中通常无意义，可省略；若服务端强制要求，请确认其真实接受类型（如 application/json 更合理，而非 x-www-form-urlencoded）；
建议升级至现代 HTTP 客户端（如 Apache HttpClient 5.x 或 Java 11+ HttpClient），它们内置更健壮的 URI 构建与编码逻辑。