应避免泛型代码中使用原生类型，必须用具体类型参数（如List）或通配符（如List）替代，禁用List、Map等裸类型；IDE和CI需强制拦截，并在反射与反序列化中保留泛型信息。

避免在泛型代码中使用原生类型，核心是让编译器全程参与类型检查——原生类型（如 List、Map）会主动放弃这一保护，把隐患拖到运行时才爆发。

所有集合声明必须带具体类型参数

禁止写 List list = new ArrayList() 或 Map cache = new HashMap() 这类语句。必须明确写出类型：

• List users = new ArrayList();
• Map balances = new HashMap();
• 构造器、字段、局部变量、方法参数和返回值，全部适用

用通配符替代“类型未知”的场景

当确实不知道或不关心具体类型（比如通用工具方法接收任意集合），不要退化为原生类型，改用安全的通配符：

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• ✅ void process(List> items) —— 可安全读取为 Object，禁止写入（防污染）
• ✅ T first(List extends T> list) —— 利用上界保证读取安全
• ❌ void process(List items) —— 编译期放行，运行时强转风险全开

在 IDE 中强制拦截原生类型用法

原生类型不是语法错误，但它是严重代码异味。需靠工具提前拦截：

• IntelliJ：Settings → Editor → Inspections → “Raw type usage” → 设为 Error
• Eclipse：Preferences → Java → Compiler → Errors/Warnings → “Usage of a raw type” → 设为 Error
• 配合 CI 流程，在编译阶段直接失败，不给绕过机会

警惕反射与反序列化带来的隐性退化

JSON 解析、RPC 响应、反射获取字段等操作，容易把一个本该是 List 的对象，以 List 原生类型形式暴露出来：

• 反序列化时优先用带泛型信息的 API，例如 Jackson 的 new TypeReference>() {}
• 反射获取集合字段后，若需强转，先通过 field.getGenericType() 提取 ParameterizedType，再校验实际类型参数
• 关键业务集合可封装为 CheckedList，add 前用 clazz.isInstance(item) 拦截非法元素

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南