如何使用Java WebClient调用含APIKey的REST API及多URI请求

针对你需要调用的https://exampleAPI.com/api/v1/example/numberExample/5?apikey=123-456-789这类复杂格式API，下面是具体的实现方案、URI处理技巧和API Key传入方式：

一、构建复杂请求URL的正确方式 #

不要直接硬拼字符串（容易出现URL编码错误），推荐用WebClient的uri()方法结合UriBuilder分部分构建：

示例代码（Java） #

import org.springframework.web.reactive.function.client.WebClient;

public class ApiClient {
    private final WebClient webClient;

    public ApiClient() {
        // 初始化WebClient，指定基础URL
        this.webClient = WebClient.builder()
                .baseUrl("https://exampleAPI.com/api/v1")
                .build();
    }

    public void fetchData() {
        int someId = 5;
        String apiKey = "123-456-789";

        webClient.get()
                // 构建路径与查询参数
                .uri(uriBuilder -> uriBuilder
                        .path("/example/numberExample/{id}") // 路径参数占位符
                        .queryParam("apikey", apiKey) // 添加查询参数
                        .build(someId)) // 填充路径参数值
                .retrieve()
                // 后续处理响应
                .bodyToMono(ApiResponse.class)
                .subscribe(response -> {
                    System.out.println(response.getData());
                });
    }
}

二、各类URI的处理技巧 #

1. 路径参数：用{占位符}定义在路径中，通过build()方法传入实际值，WebClient会自动处理URL编码（比如特殊字符转义）。
2. 多段路径：可以用多个path()方法链式拼接，比如path("/example").path("/numberExample/{id}")，效果和合并写法一致。
3. 多查询参数：如果有多个查询参数，继续调用queryParam()即可，比如.queryParam("apikey", apiKey).queryParam("filter", "active")。

三、API Key的正确传入方式 #

方式1：作为查询参数（你的示例采用的方式） #

就是上面代码里的queryParam("apikey", apiKey)，直接把API Key放在URL的查询串中，适合API明确要求这种传递方式的场景。

方式2：放在请求头中（更安全，推荐优先使用） #

如果API支持通过请求头传递API Key（比如X-API-Key），可以这样写：

webClient.get()
        .uri("/example/numberExample/{id}", someId)
        .header("X-API-Key", apiKey) // 把API Key放在请求头
        .retrieve()
        .bodyToMono(ApiResponse.class)
        .subscribe(...);

四、解析API响应的JSON #

根据你给出的JSON结构，需要创建对应的Java实体类来映射：

实体类定义 #

import java.util.List;

// 顶层响应类
public class ApiResponse {
    private Query query;
    private List<DataItem> data;

    // Getter、Setter方法
    public Query getQuery() { return query; }
    public void setQuery(Query query) { this.query = query; }
    public List<DataItem> getData() { return data; }
    public void setData(List<DataItem> data) { this.data = data; }
}

// Query子类
class Query {
    private String apikey;
    private String someId;

    // Getter、Setter方法
    public String getApikey() { return apikey; }
    public void setApikey(String apikey) { this.apikey = apikey; }
    public String getSomeId() { return someId; }
    public void setSomeId(String someId) { this.someId = someId; }
}

// DataItem子类
class DataItem {
    private int data1;
    private String data2;
    private int data3;
    private int data4;

    // Getter、Setter方法
    public int getData1() { return data1; }
    public void setData1(int data1) { this.data1 = data1; }
    public String getData2() { return data2; }
    public void setData2(String data2) { this.data2 = data2; }
    public int getData3() { return data3; }
    public void setData3(int data3) { this.data3 = data3; }
    public int getData4() { return data4; }
    public void setData4(int data4) { this.data4 = data4; }
}

之后通过bodyToMono(ApiResponse.class)就能自动将JSON响应映射到实体类对象中。

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