Java 编码规范

适用于 Spring Boot 服务中易读且可维护的 Java (17+) 代码标准。

核心原则

• 清晰度优先于巧妙性
• 默认不可变；最小化共享的可变状态
• 抛出有意义的异常以实现早期失败（Fail fast）
• 一致的命名与包结构

命名

// ✅ 类/记录（Record）: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// ✅ 方法/字段: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

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

不可变性

// ✅ 优先使用 record 和 final 字段
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // 仅有 getter，没有 setter
}

Optional 的使用

// ✅ find* 方法返回 Optional
Optional<Market> market = marketRepository.findBySlug(slug);

// ✅ 使用 map/flatMap 代替 get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

流（Stream）最佳实践

// ✅ 使用流进行转换，保持流水线（Pipeline）简洁
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// ❌ 避免复杂的嵌套流；为了清晰起见，优先使用循环

异常

• 对于领域错误（Domain errors）使用非检查异常（Unchecked Exceptions）；使用上下文包装技术异常
• 创建领域特定的异常（例如：MarketNotFoundException）
• 避免捕获过于宽泛的 catch (Exception ex)（除非在中心位置重新抛出或记录日志）

throw new MarketNotFoundException(slug);

泛型与类型安全

• 避免使用原始类型（Raw types）；声明泛型参数
• 优先在可重用的工具类中使用受限泛型（Bounded Generics）

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/... (镜像 main 目录)

格式与样式

• 始终一致地使用 2 或 4 个空格（遵循项目标准）
• 每个文件仅包含一个 public 顶级类型
• 保持方法短小且专注；提取助手方法（Helper methods）
• 成员顺序：常量、字段、构造函数、public 方法、protected、private

应避免的代码异味 (Code Smells)