UriBuilder查询参数编码问题：如何正确处理含+的邮箱参数

问题代码 #

var responseEntity =
          webClient
              .get()
              .uri(
                  uriBuilder ->
                      uriBuilder
                          .path("myendpoint")
                          .queryParam("email", email)
                          .build())
              .retrieve()

问题描述 #

这段代码处理含+的邮箱（如my+email@gmail.com）时，会出现以下编码异常：

• 默认编码逻辑不对查询参数中的+进行编码，导致参数传递不符合预期
• 手动将邮箱编码为my%2Bemail@gmail.com后，默认编码器会再次对%编码，最终变成my%252Bemail@gmail.com
• 使用uriBuilder.encode()方法会把邮箱中的@也一并编码，破坏邮箱格式

需要生成的目标URI：https://myendpoint?email=my%2Bemail@gmail.com

解决方案 #

方案1：手动编码参数后关闭自动编码

使用URLEncoder手动编码邮箱参数，再关闭UriBuilder的自动编码，确保仅对+进行正确编码，同时保留@等合法字符：

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

// ...

String encodedEmail = URLEncoder.encode(email, StandardCharsets.UTF_8.name());

var responseEntity = webClient
    .get()
    .uri(uriBuilder -> uriBuilder
            .path("myendpoint")
            .queryParam("email", encodedEmail)
            .encode(false) // 关闭自动编码，避免重复编码
            .build())
    .retrieve();

方案2：直接构建完整URI

完全手动构建符合要求的URI，绕过WebClient的自动编码逻辑：

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

// ...

String baseUri = "https://myendpoint";
String encodedEmail = URLEncoder.encode(email, StandardCharsets.UTF_8.name());
URI targetUri = URI.create(baseUri + "?email=" + encodedEmail);

var responseEntity = webClient
    .get()
    .uri(targetUri)
    .retrieve();

方案3：全局配置编码模式

通过自定义UriBuilderFactory设置全局编码规则，让WebClient自动正确处理参数编码，无需每次手动操作：

import org.springframework.web.util.DefaultUriBuilderFactory;
import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

// ...

// 创建UriBuilder工厂，设置仅编码参数值的模式
DefaultUriBuilderFactory uriFactory = new DefaultUriBuilderFactory();
uriFactory.setEncodingMode(EncodingMode.VALUES_ONLY);

// 配置WebClient使用该工厂
WebClient webClient = WebClient.builder()
        .uriBuilderFactory(uriFactory)
        .build();

// 原代码无需修改，即可正确编码email参数
var responseEntity = webClient
    .get()
    .uri(uriBuilder -> uriBuilder
            .path("myendpoint")
            .queryParam("email", email)
            .build())
    .retrieve();

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