Java Spring WebClient自动转义%字符：URI中#编码异常问题

问题原因 #

直接拼接字符串构建URI时，WebClient会对整个字符串进行二次编码，导致手动转义的%被再次转义成%25；而直接保留#的话，因为#在URI中默认是片段标识符的开头，WebClient不会自动将其转义为路径/查询参数的合法字符。

正确做法 #

不要手动转义，使用UriComponentsBuilder构建URI，或者利用WebClient的参数化uri方法，让框架正确处理特殊字符的转义：

方法一：使用UriComponentsBuilder构建完整URI #

import org.springframework.web.util.UriComponentsBuilder;

// ...

String tag = "#8QQRVVL0";
String playersEndpoint = "players/";

// 构建URI，自动处理特殊字符转义
String uri = UriComponentsBuilder.fromPath(playersEndpoint + tag).build().encode().toUriString();

JSONObject json = webClient.get()
        .uri(uri)
        .retrieve()
        .bodyToMono(JSONObject.class)
        .block();

方法二：使用WebClient的参数化uri方法 #

如果tag是路径参数的一部分，可以用占位符的方式传入，框架会自动转义：

String tag = "#8QQRVVL0";

JSONObject json = webClient.get()
        .uri("players/{tag}", tag) // 这里的{tag}会自动转义特殊字符
        .retrieve()
        .bodyToMono(JSONObject.class)
        .block();

为什么之前的方法失效 #

• 手动替换#为%23后，WebClient会把整个拼接后的字符串当作未编码的内容，将%再次转义为%25，最终得到%2523。
• 直接保留#时，WebClient会将其识别为URI片段的起始符，不会将其作为路径的一部分进行转义，导致后端无法正确识别这个标识符。

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