跳转至

Java 编码标准

Spring Boot 服务中可读且可维护的 Java（17+）代码标准。

核心原则

  • 优先清晰而非巧妙
  • 默认不可变；最小化共享可变状态
  • 使用有意义的异常尽早失败
  • 一致的命名与包结构

命名

// PASS: クラス/レコード: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS: メソッド/フィールド: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

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

不可变性

// PASS: 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

// PASS: find*メソッドからOptionalを返す
Optional<Market> market = marketRepository.findBySlug(slug);

// PASS: get()の代わりにmap/flatMapを使用
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

Stream 最佳实践

// PASS: 変換にストリームを使用し、パイプラインを短く保つ
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// FAIL: 複雑なネストされたストリームを避ける; 明確性のためにループを優先

异常

  • 领域错误使用非受检异常；技术异常应连同上下文一起包装
  • 创建领域特定异常（例如：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/... (mainをミラー)

格式与风格

  • 一致使用 2 或 4 个空格（项目标准）
  • 每个文件一个 public 顶层类型
  • 保持方法短小且专注；提取辅助方法
  • 成员顺序：常量、字段、构造器、public 方法、protected、private

应避免的代码坏味道

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

日志记录

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

Null 处理

  • 仅在不得已时接受 @Nullable；否则使用 @NonNull
  • 输入使用 Bean Validation（@NotNull、@NotBlank）

测试预期

  • JUnit 5 + AssertJ 流畅断言
  • Mockito 用于模拟；尽可能避免部分模拟
  • 优先确定性测试；无隐藏 sleep

记住：保持代码有意、类型化、可观察。除非证明有必要，否则优先优化可维护性而非微优化。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC