RestTemplate调用返回ResponseEntity<Object>的API数据映射异常排查

核心问题分析 #

你遇到的所有问题本质都是响应结构不匹配导致的：

• API返回的是外层包含status、message、data的嵌套结构，而非直接返回Survey数组
• RestTemplate默认会将JSON对象转成LinkedHashMap，直接强转泛型对象会因为泛型擦除抛出类型转换异常

最优解决方案：定义统一响应实体类 #

1. 创建匹配响应结构的泛型实体类 #

这个类完全对应API的返回格式，用泛型适配不同的data类型：

@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResponse<T> {
    private Integer status;
    private String message;
    private List<T> data;
}

2. 修改RestTemplate调用代码 #

用ParameterizedTypeReference指定泛型类型，让RestTemplate自动完成对象映射：

public void getSurvey(String personId){
    try {
        ResponseEntity<ApiResponse<Survey>> response = restTemplate.exchange(
                url + personId,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<ApiResponse<Survey>>() {}
        );
        
        ApiResponse<Survey> apiResponse = response.getBody();
        if (apiResponse != null && apiResponse.getData() != null) {
            List<Survey> surveyList = apiResponse.getData();
            // 提取所需字段
            for (Survey survey : surveyList) {
                System.out.println("ID: " + survey.getId());
                System.out.println("Name: " + survey.getName());
                System.out.println("Job描述: " + survey.getJobDesc());
            }
        }
    } catch(Exception ex) {
        System.out.println("Exception is:" + ex);
        ex.printStackTrace();
    }
}

各失败方法的原因解析 #

• 方法1（强转List）：RestTemplate把data数组的元素转成了LinkedHashMap，泛型擦除后强转只是编译期欺骗，运行时必然抛出ClassCastException
• 方法2（直接用ResponseEntity）：API返回的外层结构没有Survey的字段，RestTemplate找不到映射关系，所以所有字段为null
• 方法3（直接转Survey）：响应中的status、message字段在Survey类中没有对应属性，ObjectMapper无法识别这些字段，因此抛出异常

替代方案：不新增实体类的临时解决法 #

如果不想新增ApiResponse类，可以手动将LinkedHashMap转为Survey对象：

public void getSurvey(String personId){
    try {
        ResponseEntity<Map<String, Object>> response = restTemplate.exchange(
                url + personId,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<Map<String, Object>>() {}
        );
        
        List<LinkedHashMap<String, Object>> rawDataList = (List<LinkedHashMap<String, Object>>) response.getBody().get("data");
        ObjectMapper objectMapper = new ObjectMapper();
        List<Survey> surveyList = new ArrayList<>();
        
        for (LinkedHashMap<String, Object> itemMap : rawDataList) {
            Survey survey = objectMapper.convertValue(itemMap, Survey.class);
            surveyList.add(survey);
            System.out.println("提取的ID：" + survey.getId());
        }
    } catch(Exception ex) {
        System.out.println("Exception is:" + ex);
        ex.printStackTrace();
    }
}

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