SpringBoot泛型封装常见陷阱与避坑方法

前言

日常开发中，CRUD 写多了难免会感叹：泛型用好了是利器，用不好就是陷阱。在

业务代码里，泛型几乎无处不在：

Result> getUsers();
BaseService service;
Response>> orders();

表面上看很规范，但实际项目里，泛型相关的坑一个接一个，稍不注意就踩中。

• 明明定义了泛型上限，序列化时却变成了LinkedHashMap
• 泛型擦除导致instanceof判断永远失效
• 泛型方法里new T()直接编译报错
• 工具类封装时泛型参数对不上号
• ……

今天我们来盘点 SpringBoot 泛型封装中8 个高频踩坑点，看完就能直接应用到项目中。

1. 坑一：泛型擦除——instanceof 判断永远为 false

常见写法

public class Response {
    private T data;
    
    public boolean isList() {
        // 误以为 data 是 List 就返回 true？
        return data instanceof List; // 永远 false！
    }
}

问题在哪

运行时泛型会被擦除为Object，List也会被擦除成List，根本不存在List这种具体类型。所以data instanceof List语法上就错了，编译器直接报错。

正确做法

方案一：通过传入 Class 参数判断

public class Response {
    private T data;
    private Class clazz;
    
    public Response(Class clazz) {
        this.clazz = clazz;
    }
    
    public boolean isList() {
        return List.class.isAssignableFrom(clazz);
    }
}
​
// 使用
Response> response = new Response<>(new TypeToken>(){}.getType());

方案二：使用 TypeReference 保留泛型信息（JSON 序列化场景）

public class Result {
    private T data;
    
    // 配合 Jackson 使用
    public static  Result fromJson(String json, TypeReference> typeRef) {
        try {
            return new ObjectMapper().readValue(json, typeRef);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}
​
// 调用
Result> result = Result.fromJson(json, 
    new TypeReference>>() {});

2. 坑二：工具类封装时泛型参数“对不上”

常见写法

public class ResultUtil {
    
    public static  Result success(T data) {
        Result result = new Result<>();
        result.setData(data);
        result.setCode(200);
        return result;
    }
}
​
// 调用
List users = userService.list();
Result> result = ResultUtil.success(users); // 完美

这看起来没问题。但如果这样写呢？

public static  T getData(Result result) {
    if (result.getCode() == 200) {
        return result.getData(); // OK
    }
    return null; // 这里有问题吗？
}

问题在哪

当T是基本类型包装类（如Integer、Long）时，返回null可能会触发 NPE。

正确做法

public static  T getDataOrThrow(Result result) {
    if (result.getCode() != 200) {
        throw new BusinessException(result.getMessage());
    }
    return result.getData(); // 非空，编译器保证
}
​
// 或者返回空对象而非 null
public static  T getData(Result result, T defaultValue) {
    if (result.getCode() != 200) {
        return defaultValue;
    }
    return result.getData();
}

3. 坑三：new T() 永远编译不过

常见写法

public class BaseService {
    
    public T createEntity() {
        // 想动态创建实例
        return new T(); // 编译错误！
    }
}

问题在哪

泛型擦除后，运行时根本不知道 T 是什么类型，无法调用构造函数。这是 Java 类型系统的固有局限。

正确做法

方案一：通过 Class 对象创建

public class BaseService {
    
    private final Class entityClass;
    
    public BaseService(Class entityClass) {
        this.entityClass = entityClass;
    }
    
    public T createEntity() {
        try {
            return entityClass.getDeclaredConstructor().newInstance();
        } catch (Exception e) {
            throw new RuntimeException("创建实例失败", e);
        }
    }
}
​
// 使用
UserService userService = new UserService(User.class);
User user = userService.createEntity();

方案二：用反射工具类封装（推荐）

public class BeanUtil {
    
    public static  T newInstance(Class clazz) {
        try {
            return clazz.getDeclaredConstructor().newInstance();
        } catch (Exception e) {
            throw new IllegalStateException("无法创建实例: " + clazz.getName(), e);
        }
    }
    
    public static  T copyProperties(Object source, Class targetClass) {
        T target = newInstance(targetClass);
        BeanUtils.copyProperties(source, target);
        return target;
    }
}

4. 坑四：泛型上限没设对，导致类型转换 ClassCastException

常见写法

// 随便定义一个泛型
public class DataHolder {
    private T data;
    
    public void process() {
        // 假设需要调用 Comparable 方法
        Comparable comparable = data; // 可能出问题
        comparable.compareTo(data); // 如果 T 是 String，OK；如果是 User？User 没实现 Comparable
    }
}

问题在哪

没有约束T的上限，任何类型都能传，但代码里却需要特定能力（如Comparable、Serializable）。

正确做法

明确泛型上限

// 限定 T 必须实现 Comparable
public class DataHolder> {
    private T data;
    
    public T max(T other) {
        return data.compareTo(other) > 0 ? data : other; // 编译器保证安全
    }
}
​
// 限定 T 必须实现序列化
public class CacheWrapper {
    private T data;
}
​
// 限定多重上限
public class Processor> {
    public double doubleValue(T value) {
        return value.doubleValue();
    }
}

常见场景：Service 层基类

// 基础 Service，限定 entity 必须继承 BaseEntity
public abstract class BaseService {
    
    protected abstract Mapper getMapper();
    
    public DTO getById(Long id) {
        T entity = getMapper().selectById(id);
        return convertToDTO(entity); // entity 一定有 id、createTime 等
    }
    
    protected abstract DTO convertToDTO(T entity);
}
​
// 子类实现
public class UserServiceImpl extends BaseService {
    
    @Override
    protected Mapper getMapper() {
        return userMapper;
    }
    
    @Override
    protected UserDTO convertToDTO(User user) {
        // user 一定有 getId()，因为继承了 BaseEntity
        return UserDTO.builder()
            .id(user.getId())
            .name(user.getName())
            .build();
    }
}

5. 坑五：泛型方法定义错误，调用时类型推断失败

常见写法

public class Converter {
    
    // 以为是泛型方法，实际上不是
    public static T convert(Object source) {
        return (T) source; // 编译警告，运行时可能 ClassCastException
    }
}
​
// 调用
String str = Converter.convert(someObject); // 谁知道转成啥？

问题在哪

这个T不是方法级别泛型，而是类级别泛型。如果类没有声明，这里的T就是普通的类型参数（虽然也能编译，但语义完全错误）。

正确做法

正确的泛型方法

public class Converter {
    
    // 正确的泛型方法： 是方法声明的一部分
    public static  T convert(Object source, Class targetClass) {
        if (source == null) {
            return null;
        }
        return targetClass.cast(source);
    }
    
    // 更安全的版本
    public static  T convert(S source, Function converter) {
        if (source == null) {
            return null;
        }
        return converter.apply(source);
    }
}
​
// 使用
String str = Converter.convert(someObject, String.class);
UserDTO dto = Converter.convert(user, UserDTO::toDTO);

复杂场景：返回多种类型的泛型方法

// 业务场景：统一处理成功/失败返回
public class ApiResult {
    
    public static  T getOrThrow(ApiResponse response) {
        if (!response.isSuccess()) {
            throw new ApiException(response.getCode(), response.getMessage());
        }
        return response.getData();
    }
    
    // 配合 Optional 使用
    public static  Optional toOptional(ApiResponse response) {
        if (response.isSuccess() && response.getData() != null) {
            return Optional.of(response.getData());
        }
        return Optional.empty();
    }
}

6. 坑六：泛型通配符 ? extends 和 ? super 傻傻分不清

常见写法

// 读取数据时用 extends
public void read(List list) {
    Object item = list.get(0); // 读 OK
    list.add(new Object()); // 写？编译错误
}
​
// 写入数据时用 super
public void write(List list) {
    list.add("hello"); // 写 OK
    String item = list.get(0); // 读？需要强制转型
}

问题在哪

搞不清 PECS 原则（Producer Extends, Consumer Super）：

• 读取数据（生产者）→ 用? extends
• 写入数据（消费者）→ 用? super

正确做法

记住 PECS 原则

// 生产者：用 extends，只能读
public double sumOfPrices(List products) {
    double total = 0;
    for (Product p : products) { // 读 OK
        total += p.getPrice();
    }
    // products.add(new Product()); // 编译错误，不能写
    return total;
}
​
// 消费者：用 super，只能写
public void addNumbers(List list) {
    list.add(1); // 写 OK
    list.add(2);
    // Integer num = list.get(0); // 读出来是 Object
}
​
// 既读又写？别用通配符
public  void copy(List dest, List src) {
    for (T item : src) { // src 是生产者，可以读
        dest.add(item); // dest 是消费者，可以写
    }
}

实际业务场景

// DTO 转换：源列表是生产者，目标列表是消费者
public  void convertList(List sources, List targets, 
                                Function converter) {
    for (S source : sources) {
        targets.add(converter.apply(source));
    }
}
​
// 使用
List users = userMapper.selectList();
List dtos = new ArrayList<>();
convertList(users, dtos, User::toDTO);

public class Result {
    private T data;
    
    // 序列化给前端
    public String toJson() {
        return new ObjectMapper().writeValueAsString(this);
    }
}
​
// 接口
@GetMapping("/user")
public Result getUser() {
    Result result = new Result<>();
    result.setData(userDTO);
    return result;
}

{
  "data": {
    "name": "张三",
    "id": 1
  }
}

// 后端
Result> result = new Result<>();
result.setData(Arrays.asList(userDTO1, userDTO2));
​
// 前端收到
{
  "data": [
    {"name": "张三", "id": 1}, // 不再是 UserDTO
    {"name": "李四", "id": 2}
  ]
}

public class Result {
    
    public String toJson() {
        try {
            ObjectMapper mapper = new ObjectMapper();
            mapper.registerModule(new JavaTimeModule());
            return mapper.writeValueAsString(this);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    
    // 泛型反序列化方法
    public static  T fromJson(String json, TypeReference typeRef) {
        try {
            return new ObjectMapper().readValue(json, typeRef);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}
​
// 后端给前端：直接序列化，不需要改动
// 前端拿到字符串后：
Result> result = Result.fromJson(jsonString,
    new TypeReference>>() {});

@JsonTypeInfo(use = JsonTypeInfo.Id.MINIMAL_CLASS)
public class Result {
    private T data;
}
​
// 序列化成
{
  "data": {
    "@c": ".UserDTO",
    "name": "张三"
  }
}

@GetMapping("/users")
public ResponseEntity>> getUsers() {
    Result> result = Result.success(userService.list());
    return ResponseEntity.ok(result);
}

// 四层泛型嵌套，你能一眼看出 data 是什么吗？
Response>>> result = userService.query(request);
​
// 访问数据时
List users = result.getData().getData().getData().getRecords();

// 第一层：接口返回统一封装
public class ApiResponse {
    private int code;
    private String message;
    private T data;
}
​
// 第二层：分页数据统一封装
public class PageResult {
    private List records;
    private long total;
    private int pageNum;
    private int pageSize;
}
​
// 简化后的调用
ApiResponse> result = userService.query(request);
PageResult page = result.getData();
List users = page.getRecords();

public class Result {
    private T data;
    
    public Optional getOptionalData() {
        return Optional.ofNullable(data);
    }
}
​
// 使用
user.getOptionalData()
    .map(PageResult::getRecords)
    .orElse(Collections.emptyList());

public class ResultHelper {
    
    public static  List getRecordsOrEmpty(Result> result) {
        if (result == null || result.getData() == null) {
            return Collections.emptyList();
        }
        return result.getData().getRecords();
    }
}
​
// 调用
List users = ResultHelper.getRecordsOrEmpty(result);