本文详解如何在 Spring Boot 中使用 WebClient 模拟 PHP cURL 的 http_build_query 表单提交，重点纠正将参数误设为 HTTP 头、忽略 Content-Type 和请求体格式等常见错误。
本文详解如何在 spring boot 中使用 webclient 模拟 php curl 的 `http_build_query` 表单提交，重点纠正将参数误设为 http 头、忽略 `content-type` 和请求体格式等常见错误。
在 Spring Boot 中使用 WebClient 替代传统 cURL 请求时，一个常见误区是混淆请求参数位置与传输格式。你提供的 PHP cURL 示例中，http_build_query(...) 生成的是 application/x-www-form-urlencoded 格式的请求体（即键值对形式的表单数据），而非 URL 查询参数或自定义请求头——而你的 WebClient 实现却错误地将 username 和 password 设置为 HTTP 头部，且未设置请求体，导致服务端无法解析认证信息。
✅ 正确做法是：
- 保持 Content-Type: application/x-www-form-urlencoded（非 application/json）；
- 通过 .bodyValue() 或 .body() 提交 URL 编码的表单数据；
- 避免将业务字段（如 username/password）放入 Header（除非 API 明确要求 bearer token 或 API key 认证）；
- URI 应为纯基础地址，不要手动拼接查询参数（除非服务端明确要求 GET + query，但本例为 POST 表单，应走 body）。
以下是推荐的实现方式（使用 MultiValueMap，类型安全且自动编码）：
public Mono<SearchDetailsResponse> sendSearchDetailsRequest() {
MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
formData.add("action", "GetSearchDetails");
formData.add("username", "lambistic");
formData.add("password", "lambistic######");
formData.add("responsetype", "json");
return webClient.post()
.uri("https://www.myurl.com/") // ✅ 纯 URI，不拼参
.header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_FORM_URLENCODED_VALUE)
.bodyValue(formData) // ✅ 自动序列化为 x-www-form-urlencoded 字符串
.retrieve()
.bodyToMono(SearchDetailsResponse.class);
}⚠️ 注意事项：
- 若 SearchDetailsResponse 是 JSON 响应体，请确保服务端返回 Content-Type: application/json，且类字段命名与 JSON key 匹配（可配合 @JsonProperty 注解）；
- WebClient 默认不处理重定向（302），如需支持，请显式配置 .exchangeStrategies(ExchangeStrategies.builder().codecs(configurer -> ...).build()) 或检查服务端是否返回了非 2xx 状态码；
- 密码明文传输存在安全风险，生产环境建议升级为 HTTPS + Basic Auth、Bearer Token 或更安全的 OAuth2 / API Key 方案；
- 如服务端强制要求参数在 URL 中（GET），才应改用 .uri(uriBuilder -> uriBuilder .path("/").queryParam("action", "GetSearchDetails")...build())，但本例原始 cURL 是 POST，故优先走请求体。
总结：http_build_query 对应的是 application/x-www-form-urlencoded 请求体，不是 header，也不是 JSON body。理解协议语义，才能写出健壮、可维护的 WebClient 调用。
