java-coding-standards

Java 编码规范

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

何时启用

• 在 Spring Boot 项目中编写或审查 Java 代码
• 强制执行命名、不可变性或异常处理约定
• 使用 record、sealed class 或模式匹配（Java 17+）
• 审查 Optional、流或泛型的使用
• 规划包和项目结构

核心原则

• 清晰优先于巧妙
• 默认不可变；尽量减少共享可变状态
• 尽早失败，并抛出有意义的异常
• 采用一致的命名和包结构

命名

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

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

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

不可变性

// ✅ 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 的使用

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

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

流的最佳实践

// ✅ Use streams for transformations, keep pipelines short
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// ❌ Avoid complex nested streams; prefer loops for clarity

异常

• 对领域错误使用非受检异常；包装技术异常时附带上下文
• 创建特定于领域的异常（例如 MarketNotFoundException）
• 除非要在统一位置重新抛出或记录日志，否则避免使用宽泛的 catch (Exception ex)

throw new MarketNotFoundException(slug);

泛型与类型安全

• 避免使用原始类型；声明泛型参数
• 编写可复用工具时优先使用有界泛型

public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }

项目结构（Maven/Gradle）

src/main/java/com/example/app/
  config/
  controller/
  service/
  repository/
  domain/
  dto/
  util/
src/main/resources/
  application.yml
src/test/java/... (mirrors main)

格式与风格

• 统一使用 2 或 4 个空格（遵循项目标准）
• 每个文件只放置一个顶层公共类型
• 方法应简短且聚焦；提取辅助方法
• 成员顺序：常量、字段、构造函数、公共方法、受保护方法、私有方法

应避免的代码异味

• 参数列表过长 → 使用 DTO/构建器
• 嵌套过深 → 提前返回
• 魔法数字 → 使用具名常量
• 静态可变状态 → 优先使用依赖注入
• 静默捕获异常 → 记录日志并处理，或重新抛出

日志记录

private static final Logger log = LoggerFactory.getLogger(MarketService.class);
log.info("fetch_market slug={}", slug);
log.error("failed_fetch_market slug={}", slug, ex);

空值处理

• 只有在不可避免时才接受 @Nullable；否则使用 @NonNull
• 对输入使用 Bean Validation（@NotNull、@NotBlank）

测试要求

• 使用 JUnit 5 + AssertJ 进行流畅断言
• 使用 Mockito 进行模拟；尽可能避免部分模拟
• 优先编写确定性测试；不要使用隐藏的 sleep

请牢记：让代码有明确意图、类型明确且可观测。除非有证据表明微优化确有必要，否则应优先考虑可维护性。