Spring RestClient调用XCP/Xen API时URL特殊字符编码问题求助

问题根源 #

1. 原代码错误地将整个filter=tags:...作为查询参数名，而非参数名为filter、值为tags:/^Backups$/i
2. Xen API要求严格编码查询参数中的特殊字符（:、/、^、$等），但Spring RestClient默认编码规则不会编码部分RFC3986允许的字符，手动编码又会触发二次转义

可行解决方案 #

方案1：使用queryParamEncoded传递预编码参数

先对filter参数值进行全编码，再通过queryParamEncoded告知RestClient无需二次编码：

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

public List<VMLink> getVMsByTags(String[] tag) {
    // 生成原始filter值：tags:/^[标签]$/i
    String rawFilterValue = "tags:" + StringConverters.tagArrayToTagRegex(tag);
    // 全编码特殊字符，匹配Postman的有效请求格式
    String encodedFilterValue = URLEncoder.encode(rawFilterValue, StandardCharsets.UTF_8);

    return restClient.get()
            .uri(uriBuilder -> uriBuilder
                    .path(baseURI + "vms")
                    .queryParam("fields", "name_label,power_state")
                    // 使用queryParamEncoded避免二次编码
                    .queryParamEncoded("filter", encodedFilterValue)
                    .build())
            .accept(MediaType.APPLICATION_JSON)
            .acceptCharset(StandardCharsets.UTF_8)
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});
}

方案2：直接构建编码后的完整URI

如果方案1仍有问题，可手动拼接完整编码后的URI字符串，再通过URI.create创建有效URI：

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

public List<VMLink> getVMsByTags(String[] tag) {
    String rawFilterValue = "tags:" + StringConverters.tagArrayToTagRegex(tag);
    String encodedFilterValue = URLEncoder.encode(rawFilterValue, StandardCharsets.UTF_8);
    
    // 拼接完整编码后的URI
    String fullUri = baseURI + "vms?fields=name_label,power_state&filter=" + encodedFilterValue;
    URI uri = URI.create(fullUri);

    return restClient.get()
            .uri(uri)
            .accept(MediaType.APPLICATION_JSON)
            .acceptCharset(StandardCharsets.UTF_8)
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});
}

关键注意事项 #

• 确保baseURI末尾没有多余的/，避免拼接后出现//vms这类无效路径
• URLEncoder.encode会自动编码所有非字母数字及-_.*之外的字符，完全符合Xen API要求的编码格式
• 使用queryParamEncoded时，仅对已编码的参数使用该方法，其他参数（如fields）仍用普通queryParam即可

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