122-java-type-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Type Design Thinking in Java

Java类型设计思维

Review and improve Java code using comprehensive type design principles that apply typography concepts to code structure and organization for maximum clarity and maintainability.

What is covered in this Skill?

Clear type hierarchies: nested static classes, logical structure
Consistent naming conventions: domain-driven patterns, uniform interface/implementation naming
Strategic whitespace for readability
Type-safe wrappers: value objects replacing primitive obsession (EmailAddress, Money)
Generic type parameters: flexible reusable types, bounded parameters
Domain-specific fluent interfaces: builder pattern, method chaining
Type "weights": conceptual importance — core domain vs supporting vs utility
Type contrast through interfaces: contract vs implementation separation
Aligned method signatures: consistent parameter and return types across related classes
Self-documenting code: clear descriptive names
BigDecimal for precision-sensitive calculations (financial/monetary operations)
Strategic type selection: Optional, Set vs List, interfaces over concrete types

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

运用全面的类型设计原则审查和改进Java代码，将排版概念应用于代码结构与组织，以实现最高的清晰度和可维护性。

本Skill涵盖哪些内容？

清晰的类型层级：嵌套静态类、逻辑结构
一致的命名规范：领域驱动模式、统一的接口/实现命名
提升可读性的策略性留白
类型安全包装器：用值对象替代原始类型痴迷（如EmailAddress、Money）
泛型类型参数：灵活的可复用类型、有界参数
领域特定流畅接口：构建器模式、方法链式调用
类型“权重”：概念重要性——核心领域 vs 支撑领域 vs 工具类
通过接口实现类型区分：契约与实现分离
对齐的方法签名：相关类之间参数和返回类型保持一致
自文档化代码：清晰的描述性命名
适用于精度敏感计算的BigDecimal（财务/货币运算）
策略性类型选择：Optional、Set与List对比、优先使用接口而非具体类型

适用范围：参考文档按各核心领域的示例（好/坏代码模式）组织。请根据适用示例应用建议。

Constraints

约束条件

Before applying any type design 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
```
应用前须知：阅读参考文档获取详细示例、好/坏模式及约束条件

Reference

参考资料

For detailed guidance, examples, and constraints, see references/122-java-type-design.md.

如需详细指导、示例及约束条件，请查看references/122-java-type-design.md。