128-java-generics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java Generics Best Practices

Java泛型最佳实践

Review and improve Java code using comprehensive generics best practices that enforce compile-time type safety and enable flexible, reusable APIs.

What is covered in this Skill?

Type safety: avoiding raw types, eliminating unsafe casts
Code reusability: generic methods and types for multiple type contexts
PECS wildcards:
```
? extends
```
for producers,
```
? super
```
for consumers
Diamond operator for type inference
Type erasure awareness: type tokens, factory patterns, array creation
Generic inheritance and variance: invariance, covariance, contravariance
```
@SafeVarargs
```
for heap pollution prevention
Wildcard capture helpers, self-bounded generics (CRTP) for fluent builders

Proper wildcard API design:

Comparator<? super T>

Function<? super T, ? extends R>

Arrays-vs-generics covariance pitfalls, serialization with
```
TypeReference
```
/
```
TypeToken
```
Generic naming conventions (
```
T
```
,
```
E
```
,
```
K/V
```
,
```
?
```
), typesafe heterogeneous containers
Integration with Records, sealed types, and pattern matching

Scope: The reference is organized by examples (good/bad code patterns) for each core area. Apply recommendations based on applicable examples.

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

本Skill涵盖哪些内容？

类型安全：避免原始类型，消除不安全的类型转换
代码复用性：适用于多种类型上下文的泛型方法和类型
PECS通配符：生产者使用
```
? extends
```
，消费者使用
```
? super
```
用于类型推断的菱形运算符
类型擦除认知：类型令牌、工厂模式、数组创建
泛型继承与方差：不变性、协变性、逆变性
使用
```
@SafeVarargs
```
防止堆污染
通配符捕获助手、用于流畅构建器的自限定泛型（CRTP）

合理的通配符API设计：

Comparator<? super T>

、

Function<? super T, ? extends R>

数组与泛型协变的陷阱、使用
```
TypeReference
```
/
```
TypeToken
```
进行序列化
泛型命名约定（
```
T
```
、
```
E
```
、
```
K/V
```
、
```
?
```
）、类型安全的异构容器
与Records、密封类型和模式匹配的集成

范围：参考资料按每个核心领域的示例（良好/不良代码模式）组织。根据适用的示例应用建议。

Constraints

约束条件

Before applying any generics changes, ensure the project compiles. If compilation fails, stop immediately — do not proceed until resolved. After applying improvements, run full verification.

MANDATORY: Run
```
./mvnw compile
```
or
```
mvn compile
```
before applying any change
SAFETY: If compilation fails, stop immediately and do not proceed — compilation failure is a blocking condition
VERIFY: Run
```
./mvnw clean verify
```
or
```
mvn clean verify
```
after applying improvements
BEFORE APPLYING: Read the reference for detailed examples, good/bad patterns, and constraints

在进行任何泛型修改之前，确保项目可以编译。如果编译失败，请立即停止——问题解决前不要继续。应用改进后，运行完整验证。

强制要求：在进行任何修改前运行
```
./mvnw compile
```
或
```
mvn compile
```
安全提示：如果编译失败，请立即停止，不要继续——编译失败是阻塞条件
验证：应用改进后运行
```
./mvnw clean verify
```
或
```
mvn clean verify
```
应用前须知：阅读参考资料以获取详细示例、良好/不良模式和约束条件

When to use this skill

何时使用本Skill

Improve the code with Generics
Apply Generics
Refactor the code with Generics

使用泛型改进代码
应用泛型
使用泛型重构代码

Reference

参考资料

For detailed guidance, examples, and constraints, see references/128-java-generics.md.

如需详细指南、示例和约束条件，请参阅references/128-java-generics.md。