docs(zh-CN): sync Chinese docs with latest upstream changes

2026-04-01 22:53:27 +08:00 · 2026-03-21 12:55:58 +08:00
parent 0af0fbf40b
commit e73c2ffa34
85 changed files with 11028 additions and 747 deletions
--- a/docs/zh-CN/rules/java/coding-style.md
+++ b/docs/zh-CN/rules/java/coding-style.md
@@ -0,0 +1,117 @@
+---
+paths:
+  - "**/*.java"
+---
+
+# Java 编码风格
+
+> 本文档基于 [common/coding-style.md](../common/coding-style.md)，补充了 Java 特有的内容。
+
+## 格式
+
+* 使用 **google-java-format** 或 **Checkstyle**（Google 或 Sun 风格）进行强制规范
+* 每个文件只包含一个顶层的公共类型
+* 保持一致的缩进：2 或 4 个空格（遵循项目标准）
+* 成员顺序：常量、字段、构造函数、公共方法、受保护方法、私有方法
+
+## 不可变性
+
+* 对于值类型，优先使用 `record`（Java 16+）
+* 默认将字段标记为 `final` —— 仅在需要时才使用可变状态
+* 从公共 API 返回防御性副本：`List.copyOf()`、`Map.copyOf()`、`Set.copyOf()`
+* 写时复制：返回新实例，而不是修改现有实例
+
+```java
+// GOOD — immutable value type
+public record OrderSummary(Long id, String customerName, BigDecimal total) {}
+
+// GOOD — final fields, no setters
+public class Order {
+    private final Long id;
+    private final List<LineItem> items;
+
+    public List<LineItem> getItems() {
+        return List.copyOf(items);
+    }
+}
+```
+
+## 命名
+
+遵循标准的 Java 命名约定：
+
+* `PascalCase` 用于类、接口、记录、枚举
+* `camelCase` 用于方法、字段、参数、局部变量
+* `SCREAMING_SNAKE_CASE` 用于 `static final` 常量
+* 包名：全小写，使用反向域名（`com.example.app.service`）
+
+## 现代 Java 特性
+
+在能提高代码清晰度的地方使用现代语言特性：
+
+* **记录** 用于 DTO 和值类型（Java 16+）
+* **密封类** 用于封闭的类型层次结构（Java 17+）
+* 使用 `instanceof` 进行**模式匹配** —— 避免显式类型转换（Java 16+）
+* **文本块** 用于多行字符串 —— SQL、JSON 模板（Java 15+）
+* 使用箭头语法的**Switch 表达式**（Java 14+）
+* **Switch 中的模式匹配** —— 用于处理密封类型的穷举情况（Java 21+）
+
+```java
+// Pattern matching instanceof
+if (shape instanceof Circle c) {
+    return Math.PI * c.radius() * c.radius();
+}
+
+// Sealed type hierarchy
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
+
+// Switch expression
+String label = switch (status) {
+    case ACTIVE -> "Active";
+    case SUSPENDED -> "Suspended";
+    case CLOSED -> "Closed";
+};
+```
+
+## Optional 的使用
+
+* 从可能没有结果的查找方法中返回 `Optional<T>`
+* 使用 `map()`、`flatMap()`、`orElseThrow()` —— 绝不直接调用 `get()` 而不先检查 `isPresent()`
+* 绝不将 `Optional` 用作字段类型或方法参数
+
+```java
+// GOOD
+return repository.findById(id)
+    .map(ResponseDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// BAD — Optional as parameter
+public void process(Optional<String> name) {}
+```
+
+## 错误处理
+
+* 对于领域错误，优先使用非受检异常
+* 创建扩展自 `RuntimeException` 的领域特定异常
+* 避免宽泛的 `catch (Exception e)`，除非在最顶层的处理器中
+* 在异常消息中包含上下文信息
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+## 流
+
+* 使用流进行转换；保持流水线简短（最多 3-4 个操作）
+* 在可读性好的情况下，优先使用方法引用：`.map(Order::getTotal)`
+* 避免在流操作中产生副作用
+* 对于复杂逻辑，优先使用循环而不是难以理解的流流水线
+
+## 参考
+
+完整编码标准及示例，请参阅技能：`java-coding-standards`。
+JPA/Hibernate 实体设计模式，请参阅技能：`jpa-patterns`。
--- a/docs/zh-CN/rules/java/hooks.md
+++ b/docs/zh-CN/rules/java/hooks.md
@@ -0,0 +1,19 @@
+---
+paths:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+---
+
+# Java 钩子
+
+> 本文件在[common/hooks.md](../common/hooks.md)的基础上扩展了Java相关的内容。
+
+## PostToolUse 钩子
+
+在 `~/.claude/settings.json` 中配置：
+
+* **google-java-format**：编辑后自动格式化 `.java` 文件
+* **checkstyle**：编辑Java文件后运行样式检查
+* **./mvnw compile** 或 **./gradlew compileJava**：变更后验证编译
--- a/docs/zh-CN/rules/java/patterns.md
+++ b/docs/zh-CN/rules/java/patterns.md
@@ -0,0 +1,147 @@
+---
+paths:
+  - "**/*.java"
+---
+
+# Java 模式
+
+> 本文档扩展了 [common/patterns.md](../common/patterns.md) 中的内容，增加了 Java 特有的部分。
+
+## 仓储模式
+
+将数据访问封装在接口之后：
+
+```java
+public interface OrderRepository {
+    Optional<Order> findById(Long id);
+    List<Order> findAll();
+    Order save(Order order);
+    void deleteById(Long id);
+}
+```
+
+具体的实现类处理存储细节（JPA、JDBC、用于测试的内存存储等）。
+
+## 服务层
+
+业务逻辑放在服务类中；保持控制器和仓储层的精简：
+
+```java
+public class OrderService {
+    private final OrderRepository orderRepository;
+    private final PaymentGateway paymentGateway;
+
+    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
+        this.orderRepository = orderRepository;
+        this.paymentGateway = paymentGateway;
+    }
+
+    public OrderSummary placeOrder(CreateOrderRequest request) {
+        var order = Order.from(request);
+        paymentGateway.charge(order.total());
+        var saved = orderRepository.save(order);
+        return OrderSummary.from(saved);
+    }
+}
+```
+
+## 构造函数注入
+
+始终使用构造函数注入 —— 绝不使用字段注入：
+
+```java
+// GOOD — constructor injection (testable, immutable)
+public class NotificationService {
+    private final EmailSender emailSender;
+
+    public NotificationService(EmailSender emailSender) {
+        this.emailSender = emailSender;
+    }
+}
+
+// BAD — field injection (untestable without reflection, requires framework magic)
+public class NotificationService {
+    @Inject // or @Autowired
+    private EmailSender emailSender;
+}
+```
+
+## DTO 映射
+
+使用记录（record）作为 DTO。在服务层/控制器边界进行映射：
+
+```java
+public record OrderResponse(Long id, String customer, BigDecimal total) {
+    public static OrderResponse from(Order order) {
+        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
+    }
+}
+```
+
+## 建造者模式
+
+用于具有多个可选参数的对象：
+
+```java
+public class SearchCriteria {
+    private final String query;
+    private final int page;
+    private final int size;
+    private final String sortBy;
+
+    private SearchCriteria(Builder builder) {
+        this.query = builder.query;
+        this.page = builder.page;
+        this.size = builder.size;
+        this.sortBy = builder.sortBy;
+    }
+
+    public static class Builder {
+        private String query = "";
+        private int page = 0;
+        private int size = 20;
+        private String sortBy = "id";
+
+        public Builder query(String query) { this.query = query; return this; }
+        public Builder page(int page) { this.page = page; return this; }
+        public Builder size(int size) { this.size = size; return this; }
+        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
+        public SearchCriteria build() { return new SearchCriteria(this); }
+    }
+}
+```
+
+## 使用密封类型构建领域模型
+
+```java
+public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
+    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+}
+
+// Exhaustive handling (Java 21+)
+String message = switch (result) {
+    case PaymentSuccess s -> "Paid: " + s.transactionId();
+    case PaymentFailure f -> "Failed: " + f.errorCode();
+};
+```
+
+## API 响应封装
+
+统一的 API 响应格式：
+
+```java
+public record ApiResponse<T>(boolean success, T data, String error) {
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(true, data, null);
+    }
+    public static <T> ApiResponse<T> error(String message) {
+        return new ApiResponse<>(false, null, message);
+    }
+}
+```
+
+## 参考
+
+有关 Spring Boot 架构模式，请参见技能：`springboot-patterns`。
+有关实体设计和查询优化，请参见技能：`jpa-patterns`。
--- a/docs/zh-CN/rules/java/security.md
+++ b/docs/zh-CN/rules/java/security.md
@@ -0,0 +1,101 @@
+---
+paths:
+  - "**/*.java"
+---
+
+# Java 安全
+
+> 本文档在 [common/security.md](../common/security.md) 的基础上，补充了 Java 相关的内容。
+
+## 密钥管理
+
+* 切勿在源代码中硬编码 API 密钥、令牌或凭据
+* 使用环境变量：`System.getenv("API_KEY")`
+* 生产环境密钥请使用密钥管理器（如 Vault、AWS Secrets Manager）
+* 包含密钥的本地配置文件应放在 `.gitignore` 中
+
+```java
+// BAD
+private static final String API_KEY = "sk-abc123...";
+
+// GOOD — environment variable
+String apiKey = System.getenv("PAYMENT_API_KEY");
+Objects.requireNonNull(apiKey, "PAYMENT_API_KEY must be set");
+```
+
+## SQL 注入防护
+
+* 始终使用参数化查询——切勿将用户输入拼接到 SQL 语句中
+* 使用 `PreparedStatement` 或你所使用框架的参数化查询 API
+* 对用于原生查询的任何输入进行验证和清理
+
+```java
+// BAD — SQL injection via string concatenation
+Statement stmt = conn.createStatement();
+String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
+stmt.executeQuery(sql);
+
+// GOOD — PreparedStatement with parameterized query
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
+ps.setString(1, name);
+
+// GOOD — JDBC template
+jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
+```
+
+## 输入验证
+
+* 在处理前，于系统边界处验证所有用户输入
+* 使用验证框架时，在 DTO 上使用 Bean 验证（`@NotNull`, `@NotBlank`, `@Size`）
+* 在使用文件路径和用户提供的字符串前，对其进行清理
+* 对于验证失败的输入，应拒绝并提供清晰的错误信息
+
+```java
+// Validate manually in plain Java
+public Order createOrder(String customerName, BigDecimal amount) {
+    if (customerName == null || customerName.isBlank()) {
+        throw new IllegalArgumentException("Customer name is required");
+    }
+    if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
+        throw new IllegalArgumentException("Amount must be positive");
+    }
+    return new Order(customerName, amount);
+}
+```
+
+## 认证与授权
+
+* 切勿自行实现认证加密逻辑——请使用成熟的库
+* 使用 bcrypt 或 Argon2 存储密码，切勿使用 MD5/SHA1
+* 在服务边界强制执行授权检查
+* 清理日志中的敏感数据——切勿记录密码、令牌或个人身份信息
+
+## 依赖项安全
+
+* 运行 `mvn dependency:tree` 或 `./gradlew dependencies` 来审计传递依赖项
+* 使用 OWASP Dependency-Check 或 Snyk 扫描已知的 CVE
+* 保持依赖项更新——设置 Dependabot 或 Renovate
+
+## 错误信息
+
+* 切勿在 API 响应中暴露堆栈跟踪、内部路径或 SQL 错误
+* 在处理器边界将异常映射为安全、通用的客户端消息
+* 在服务器端记录详细错误；向客户端返回通用消息
+
+```java
+// Log the detail, return a generic message
+try {
+    return orderService.findById(id);
+} catch (OrderNotFoundException ex) {
+    log.warn("Order not found: id={}", id);
+    return ApiResponse.error("Resource not found");  // generic, no internals
+} catch (Exception ex) {
+    log.error("Unexpected error processing order id={}", id, ex);
+    return ApiResponse.error("Internal server error");  // never expose ex.getMessage()
+}
+```
+
+## 参考
+
+关于 Spring Security 认证与授权模式，请参见技能：`springboot-security`。
+关于通用安全检查清单，请参见技能：`security-review`。
--- a/docs/zh-CN/rules/java/testing.md
+++ b/docs/zh-CN/rules/java/testing.md
@@ -0,0 +1,133 @@
+---
+paths:
+  - "**/*.java"
+---
+
+# Java 测试
+
+> 本文档扩展了 [common/testing.md](../common/testing.md) 中与 Java 相关的内容。
+
+## 测试框架
+
+* **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
+* **AssertJ** 用于流式断言 (`assertThat(result).isEqualTo(expected)`)
+* **Mockito** 用于模拟依赖
+* **Testcontainers** 用于需要数据库或服务的集成测试
+
+## 测试组织
+
+```
+src/test/java/com/example/app/
+  service/           # Unit tests for service layer
+  controller/        # Web layer / API tests
+  repository/        # Data access tests
+  integration/       # Cross-layer integration tests
+```
+
+在 `src/test/java` 中镜像 `src/main/java` 的包结构。
+
+## 单元测试模式
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() {
+        orderService = new OrderService(orderRepository);
+    }
+
+    @Test
+    @DisplayName("findById returns order when exists")
+    void findById_existingOrder_returnsOrder() {
+        var order = new Order(1L, "Alice", BigDecimal.TEN);
+        when(orderRepository.findById(1L)).thenReturn(Optional.of(order));
+
+        var result = orderService.findById(1L);
+
+        assertThat(result.customerName()).isEqualTo("Alice");
+        verify(orderRepository).findById(1L);
+    }
+
+    @Test
+    @DisplayName("findById throws when order not found")
+    void findById_missingOrder_throws() {
+        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> orderService.findById(99L))
+            .isInstanceOf(OrderNotFoundException.class)
+            .hasMessageContaining("99");
+    }
+}
+```
+
+## 参数化测试
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "100.00, 10, 90.00",
+    "50.00, 0, 50.00",
+    "200.00, 25, 150.00"
+})
+@DisplayName("discount applied correctly")
+void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
+    assertThat(PricingUtils.discount(price, pct)).isEqualByComparingTo(expected);
+}
+```
+
+## 集成测试
+
+使用 Testcontainers 进行真实的数据库集成：
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
+
+    private OrderRepository repository;
+
+    @BeforeEach
+    void setUp() {
+        var dataSource = new PGSimpleDataSource();
+        dataSource.setUrl(postgres.getJdbcUrl());
+        dataSource.setUser(postgres.getUsername());
+        dataSource.setPassword(postgres.getPassword());
+        repository = new JdbcOrderRepository(dataSource);
+    }
+
+    @Test
+    void save_and_findById() {
+        var saved = repository.save(new Order(null, "Bob", BigDecimal.ONE));
+        var found = repository.findById(saved.getId());
+        assertThat(found).isPresent();
+    }
+}
+```
+
+关于 Spring Boot 集成测试，请参阅技能：`springboot-tdd`。
+
+## 测试命名
+
+使用带有 `@DisplayName` 的描述性名称：
+
+* `methodName_scenario_expectedBehavior()` 用于方法名
+* `@DisplayName("human-readable description")` 用于报告
+
+## 覆盖率
+
+* 目标为 80%+ 的行覆盖率
+* 使用 JaCoCo 生成覆盖率报告
+* 重点关注服务和领域逻辑 — 跳过简单的 getter/配置类
+
+## 参考
+
+关于使用 MockMvc 和 Testcontainers 的 Spring Boot TDD 模式，请参阅技能：`springboot-tdd`。
+关于测试期望，请参阅技能：`java-coding-standards`。