Java 编码风格¶

本文件通过 Java 特定内容扩展 common/coding-style.md。

格式¶

• 强制使用 google-java-format 或 Checkstyle（Google 或 Sun 风格）
• 每个文件仅包含一个 public 顶层类型
• 一致的缩进：2 或 4 个空格（遵循项目标准）
• 成员顺序：常量、字段、构造器、public 方法、protected、private

不可变性¶

• 值类型优先使用 record（Java 16+）
• 字段默认使用 final — 仅在必要时使用可变状态
• 从 public API 返回防御性副本：List.copyOf()、Map.copyOf()、Set.copyOf()
• 写时复制：返回新实例，而不是修改现有实例

// GOOD — 不変の値型
public record OrderSummary(Long id, String customerName, BigDecimal total) {}

// GOOD — final フィールド、setter なし
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+）

// パターンマッチング instanceof
if (shape instanceof Circle c) {
    return Math.PI * c.radius() * c.radius();
}

// シールド型階層
public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}

// Switch 式
String label = switch (status) {
    case ACTIVE -> "Active";
    case SUSPENDED -> "Suspended";
    case CLOSED -> "Closed";
};

Optional 用法¶

• 从可能没有结果的查找方法返回 Optional<T>
• 使用 map()、flatMap()、orElseThrow() — 不要在没有 isPresent() 的情况下调用 get()
• 不要将 Optional 用作字段类型或方法参数

// GOOD
return repository.findById(id)
    .map(ResponseDto::from)
    .orElseThrow(() -> new OrderNotFoundException(id));

// BAD — パラメータとしての Optional
public void process(Optional<String> name) {}

错误处理¶

• 领域错误优先使用非受检异常
• 创建继承自 RuntimeException 的领域特定异常
• 除顶层处理器外，避免宽泛的 catch (Exception e)
• 在异常消息中包含上下文

public class OrderNotFoundException extends RuntimeException {
    public OrderNotFoundException(Long id) {
        super("Order not found: id=" + id);
    }
}

流¶

• 转换时使用流；保持管道简短（最多 3 到 4 个操作）
• 在可读性允许时优先使用方法引用：.map(Order::getTotal)
• 避免在流操作中产生副作用
• 对于复杂逻辑，优先使用循环而不是嵌套的流管道

参考¶

技能：java-coding-standards 中可查阅完整的编码规范和示例。 技能：jpa-patterns 中可查阅 JPA/Hibernate 实体设计模式。