JSON.parseObject 返回 List 时不能强制转换的解决方案

1. 问题背景

在使用 Fastjson 或 Fastjson2 时，很多开发者习惯这样写：

java 复制代码

List<User> userList = (List<User>) JSON.parseObject(jsonString);

运行时会抛出 ClassCastException，提示无法将 JSONObject 或 JSONArray 强制转换为 List<User>。这是因为 JSON.parseObject 默认返回的是 JSONObject 类型，而不是泛型 List。

2. 错误原因分析

JSON.parseObject(String text) 的返回值类型是 JSONObject，它本质上是一个 Map。当 JSON 字符串是数组结构时，直接强转成 List 会失败。

java 复制代码

// 错误写法：运行时报 ClassCastException
List<User> userList = (List<User>) JSON.parseObject(jsonArrayString);

3. 正确解决方案

方案一：使用 TypeReference（推荐）

java 复制代码

import com.alibaba.fastjson.TypeReference;

List<User> userList = JSON.parseObject(jsonString, new TypeReference<List<User>>() {});

方案二：使用 parseArray

java 复制代码

List<User> userList = JSON.parseArray(jsonString, User.class);

方案三：先转 JSONArray 再遍历

java 复制代码

JSONArray array = JSON.parseArray(jsonString);
List<User> userList = array.toJavaList(User.class);

4. 完整示例

java 复制代码

public class JsonDemo {
    public static void main(String[] args) {
        String json = "[{\"name\":\"张三\",\"age\":20},{\"name\":\"李四\",\"age\":22}]";

        // 方式一：TypeReference
        List<User> list1 = JSON.parseObject(json, new TypeReference<List<User>>() {});

        // 方式二：parseArray
        List<User> list2 = JSON.parseArray(json, User.class);

        // 方式三：JSONArray 转换
        JSONArray array = JSON.parseArray(json);
        List<User> list3 = array.toJavaList(User.class);

        System.out.println(list1);
        System.out.println(list2);
        System.out.println(list3);
    }
}

5. 注意事项

使用 TypeReference 时，泛型信息会被完整保留，不会因类型擦除而丢失。
parseArray 适用于 JSON 字符串本身就是数组的情况。
如果 JSON 字符串是对象而非数组，应使用 JSON.parseObject(json, User.class) 解析为单个对象。
Fastjson2 中 API 基本一致，同样支持上述三种写法。