Java 编码规范

适用于 Spring Boot 服务中可读、可维护的 Java (17+) 代码的规范。

何时激活

• 在 Spring Boot 项目中编写或审查 Java 代码时
• 强制执行命名、不可变性或异常处理约定时
• 使用记录类、密封类或模式匹配（Java 17+）时
• 审查 Optional、流或泛型的使用时
• 构建包和项目布局时

核心原则

• 清晰优于巧妙
• 默认不可变；最小化共享可变状态
• 快速失败并提供有意义的异常
• 一致的命名和包结构

命名

// PASS: Classes/Records: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS: Methods/fields: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// PASS: Constants: UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;

不可变性

// PASS: Favor records and final fields
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // getters only, no setters
}

Optional 使用

// PASS: Return Optional from find* methods
Optional<Market> market = marketRepository.findBySlug(slug);

// PASS: Map/flatMap instead of get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

Streams 最佳实践

// PASS: Use streams for transfo…