128-java-generics

Java 泛型最佳实践

使用全面的泛型最佳实践审查并改进 Java 代码，确保编译时类型安全，并支持灵活、可复用的 API。

此技能涵盖哪些内容？

• 类型安全：避免使用原始类型，消除不安全的强制类型转换
• 代码复用：在多种类型场景中使用泛型方法和类型
• PECS 通配符：生产者使用 ? extends，消费者使用 ? super
• 使用菱形运算符进行类型推断
• 了解类型擦除：类型令牌、工厂模式、数组创建
• 泛型继承与变型：不变、协变、逆变
• 使用 @SafeVarargs 防止堆污染
• 通配符捕获辅助方法、自限定泛型（CRTP）流式构建器
• 正确设计通配符 API：Comparator<? super T>、Function<? super T, ? extends R>
• 数组与泛型的协变陷阱、使用 TypeReference/TypeToken 进行序列化
• 泛型命名约定（T、E、K/V、?）、类型安全的异构容器
• 与 Records、密封类型和模式匹配集成

**范围：**参考文档按示例（良好/不良代码模式）介绍每个核心领域。请根据适用示例应用建议。

约束

应用任何泛型更改之前，请确保项目能够编译。如果编译失败，请立即停止，不要继续操作，直到问题解决。完成改进后，运行完整验证。

• 强制要求：应用任何更改之前，运行 ./mvnw compile 或 mvn compile
• 安全要求：如果编译失败，请立即停止，不要继续操作——编译失败属于阻塞条件
• 验证：应用改进后，运行 ./mvnw clean verify 或 mvn clean verify
• 应用之前：阅读参考文档，了解详细示例、良好/不良模式和约束
• 边界情况：如果请求范围不明确，请先停止并提出澄清问题，再应用更改
• 边界情况：如果缺少必需的输入、文件或工具，请说明缺少的内容，并询问是否需要提供设置指导后继续

何时使用此技能

• 使用泛型改进代码
• 应用泛型
• 使用泛型重构代码
• 提高 Java API 的泛型类型安全性
• 修复 Java 代码中的原始类型和未经检查的强制类型转换

工作流

1. 在更改泛型之前编译项目

运行 ./mvnw compile 或 mvn compile；如果编译失败，请立即停止。

2. 阅读泛型参考文档并评估类型安全性

阅读 references/128-java-generics.md，找出原始类型、不安全的强制类型转换、通配符误用以及 API 变型方面的改进机会。

3. 应用泛型重构

在保留行为的前提下，实施选定的泛型类型和 API 改进。

4. 通过完整构建进行验证

应用改进后，运行 ./mvnw clean verify 或 mvn clean verify。

参考文档

详细指导、示例和约束请参见 references/128-java-generics.md。