如何创建适配数组开头格式API响应的API类？

要处理这种以数组为顶层结构的API响应，核心是先匹配JSON的嵌套结构定义数据模型，再在API类中完成请求发送与响应解析的封装。以下是两种主流编程语言的实现方案：

Python 实现（基于 Pydantic + Requests） #

1. 定义数据模型 #

用Pydantic映射JSON结构，自动完成类型校验与解析：

from pydantic import BaseModel
from typing import List

# 最内层嵌套的请求项模型
class ReqItem(BaseModel):
    _id: str
    username: str
    amount: int

# API数组中每个元素的模型
class ApiResponseItem(BaseModel):
    reqList: List[ReqItem]
    _id: str
    username: str
    amount: int

# 整个API响应是ApiResponseItem的数组类型
ApiResponse = List[ApiResponseItem]

2. 封装API处理类 #

把请求发送、响应解析的逻辑封装到类中：

import requests

class ApiHandler:
    def __init__(self, base_url: str):
        self.base_url = base_url

    def fetch_data(self, endpoint: str) -> ApiResponse:
        response = requests.get(f"{self.base_url}/{endpoint}")
        response.raise_for_status()  # 抛出HTTP请求错误
        # 将JSON数组解析为模型列表
        return [ApiResponseItem(**item) for item in response.json()]

使用示例 #

# 初始化API处理器
api = ApiHandler("https://your-api-domain.com")
# 获取并解析数据
data = api.fetch_data("target-endpoint")

# 访问解析后的数据
for item in data:
    print(f"用户名: {item.username}, 总金额: {item.amount}")
    for req_item in item.reqList:
        print(f"子请求项: {req_item.username} - {req_item.amount}")

Java 实现（基于 Jackson + OkHttp） #

1. 定义POJO数据类 #

用Jackson注解匹配JSON字段：

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;

// 最内层嵌套的请求项
class ReqItem {
    @JsonProperty("_id")
    private String id;
    private String username;
    private int amount;

    // Getter & Setter 方法
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public int getAmount() { return amount; }
    public void setAmount(int amount) { this.amount = amount; }
}

// API数组中的单个元素类
class ApiResponseItem {
    private List<ReqItem> reqList;
    @JsonProperty("_id")
    private String id;
    private String username;
    private int amount;

    // Getter & Setter 方法
    public List<ReqItem> getReqList() { return reqList; }
    public void setReqList(List<ReqItem> reqList) { this.reqList = reqList; }
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public int getAmount() { return amount; }
    public void setAmount(int amount) { this.amount = amount; }
}

2. 封装API处理类 #

用OkHttp发送请求，Jackson解析JSON数组：

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
import java.util.List;

public class ApiHandler {
    private final String baseUrl;
    private final OkHttpClient client;
    private final ObjectMapper objectMapper;

    public ApiHandler(String baseUrl) {
        this.baseUrl = baseUrl;
        this.client = new OkHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    public List<ApiResponseItem> fetchData(String endpoint) throws IOException {
        Request request = new Request.Builder()
                .url(baseUrl + "/" + endpoint)
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("请求失败: " + response);
            // 解析JSON数组为List<ApiResponseItem>
            return objectMapper.readValue(
                    response.body().string(),
                    new TypeReference<List<ApiResponseItem>>() {}
            );
        }
    }
}

使用示例 #

public class Main {
    public static void main(String[] args) {
        ApiHandler api = new ApiHandler("https://your-api-domain.com");
        try {
            List<ApiResponseItem> data = api.fetchData("target-endpoint");
            for (ApiResponseItem item : data) {
                System.out.println("用户名: " + item.getUsername() + ", 总金额: " + item.getAmount());
                for (ReqItem req : item.getReqList()) {
                    System.out.println("子请求项: " + req.getUsername() + " - " + req.getAmount());
                }
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

核心注意事项 #

• 从最内层嵌套结构开始定义模型，确保每个字段的名称、类型与JSON完全匹配；
• 解析顶层数组时，要指定为模型类的数组/列表类型，而非单个模型对象；
• 在API类中统一处理HTTP错误、解析异常，减少业务代码中的重复逻辑。

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