Java 17迁移后RestTemplate处理URI特殊字符报400错误的排查与解决

问题背景 #

• 原始请求URL：http://localhost:80/v1/accounts/60a362bd6b84a37effc8f5a3/name/QA Analyst
• 使用的核心代码：

UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(requestUrl);
ResponseEntity<RoleResponse> responseEntity = null;
HttpEntity<?> entity = new HttpEntity(RestUtil.getHeaders(this.appSecret));

try {
  responseEntity = this.restTemplate.exchange(builder.toUriString(), HttpMethod.GET, entity, RoleResponse.class, new Object[0]);
} catch (Exception var9) {
  log.error("Error occurred while getting role by name for accountId {}", accountId, var9);
  throw new RestClientException("rest_client_exception", "Unable to get role by name for account");
}

• 现象：
  • Java 8环境下，服务端收到的请求URI为v1/accounts/60a362bd6b84a37effc8f5a3/name/QA%2520Analyst（空格被双重编码： →%20→%2520），返回200状态码
  • 迁移至Java 17后，请求抛出400 BAD_REQUEST错误

原因分析 #

核心差异来自Spring版本的URL编码逻辑调整：

• Java 8通常搭配的旧版Spring（如Spring 5.2及以下）中，UriComponentsBuilder.toUriString()会对URL中所有特殊字符（包括已编码的%）再次编码，导致空格被双重转义成%2520，服务端能匹配预期的编码规则。
• Java 17一般搭配的新版Spring（如Spring 5.3+、Spring Boot 2.7+）遵循RFC标准URL规范，默认启用避免双重编码的逻辑：只会对原始未编码的特殊字符（如空格）进行单次编码，服务端收到的是QA%20Analyst，但服务端预期的是双重编码后的%2520，因此参数解析失败返回400。

解决方法 #

1. 调整服务端逻辑（推荐） #

修改服务端的参数解析规则，接受单次编码的URL参数（QA%20Analyst），因为双重编码不符合标准URL规范，新版Spring的处理才是合规的，这是长期最优解。

2. 强制RestTemplate进行双重编码 #

如果暂时无法修改服务端，可以通过以下方式让RestTemplate恢复旧版的双重编码行为：

方法一：手动预编码参数

先对参数进行一次URL编码，再传入UriComponentsBuilder，让其再次编码%字符：

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

// 手动预编码角色名称
String encodedRoleName = URLEncoder.encode("QA Analyst", StandardCharsets.UTF_8);
// 拼接预编码后的参数到URL
String requestUrl = "http://localhost:80/v1/accounts/60a362bd6b84a37effc8f5a3/name/" + encodedRoleName;

UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(requestUrl);
// 后续请求代码不变

方法二：配置RestTemplate的编码模式

通过DefaultUriBuilderFactory设置编码模式为ALL，强制对所有字符（包括已编码的%）进行编码：

import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.DefaultUriBuilderFactory;

// 初始化RestTemplate并配置编码模式
RestTemplate restTemplate = new RestTemplate();
DefaultUriBuilderFactory uriFactory = new DefaultUriBuilderFactory();
// 设置编码模式为完全编码，允许双重转义
uriFactory.setEncodingMode(DefaultUriBuilderFactory.EncodingMode.ALL);
restTemplate.setUriTemplateHandler(uriFactory);

3. 直接使用手动编码后的URL（不推荐） #

跳过UriComponentsBuilder，直接使用完全手动编码后的字符串作为请求URL，但需注意处理所有特殊字符，避免出现其他URL格式错误：

String fullyEncodedUrl = "http://localhost:80/v1/accounts/60a362bd6b84a37effc8f5a3/name/QA%2520Analyst";
responseEntity = this.restTemplate.exchange(fullyEncodedUrl, HttpMethod.GET, entity, RoleResponse.class);

内容的提问来源于stack exchange，提问作者Marcus