java-coding-standards

Java コーディング規約 (Java Coding Standards)

Spring Boot サービスにおける、読みやすく保守しやすい Java（17 以降）コードの規約です。

使用するタイミング (When to Activate)

• Spring Boot プロジェクトで Java コードを作成またはレビューするとき
• 命名、不変性（immutability）、例外処理の規約を適用するとき
• records、sealed classes、または pattern matching（Java 17 以降）を使用するとき
• Optional、streams、または generics の使用をレビューするとき
• パッケージ構造やプロジェクトのレイアウトを計画するとき

コア原則 (Core Principles)

• 技巧よりも明瞭さを優先します
• デフォルトでは不変にし、共有される可変状態を最小限に抑えます
• 速やかに失敗（Fail fast）し、意味のある例外メッセージを提供します
• 命名とパッケージ構造の一貫性を保ちます

命名 (Naming)

// ✅ 类/Records：大驼峰（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;

不変性 (Immutability)

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

public class Market {
  private final Long id;
  private final String name;
  // 仅提供 getter，不提供 setter
}

Optional の使用 (Optional Usage)

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

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

ストリームのベストプラクティス (Streams Best Practices)

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

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

例外 (Exceptions)

• ドメインエラーには非検査例外（unchecked exceptions）を使用し、技術的な例外はコンテキストを付与してラップします
• ドメイン固有の例外を作成します（例：MarketNotFoundException）
• 中央の箇所で再スローまたはログ記録を行う場合を除き、広範な catch (Exception ex) の使用は避けます

throw new MarketNotFoundException(slug);

ジェネリクスと型安全性 (Generics and Type Safety)

• raw types の使用を避け、ジェネリック型パラメーターを明示的に指定します
• 再利用可能なユーティリティクラスには、有界ジェネリクス（bounded generics）を優先します

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

プロジェクト構造 (Project Structure - Maven/Gradle)

src/main/java/com/example/app/
  config/
  controller/
  service/
  repository/
  domain/
  dto/
  util/
src/main/resources/
  application.yml
src/test/java/... (与 main 结构镜像)

フォーマットとスタイル (Formatting and Style)

• 2 または 4 個のスペースを一貫して使用します（プロジェクトの規約に従います）
• 1 つのファイルには、public なトップレベル型を 1 つだけ含めます
• メソッドは短く、目的を絞ります。ヘルパーメソッドを切り出します
• メンバーの順序：定数、フィールド、コンストラクター、public メソッド、protected メソッド、private メソッド

避けるべきコードの臭い (Code Smells to Avoid)

• 引数リストが長すぎる → DTO／ビルダーを使用します
• ネストが深すぎる → 早期リターンを使用します
• マジックナンバー → 名前付き定数を使用します
• 静的な可変状態 → 依存性注入（dependency injection）を優先します
• 何もしない catch ブロック → ログを記録して処理するか、再スローします

ログ記録 (Logging)

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

null の処理 (Null Handling)

• @Nullable は避けられない場合にのみ使用し、それ以外では @NonNull を使用します
• 入力には Bean Validation（例：@NotNull、@NotBlank）を使用します

テストの要件 (Testing Expectations)

• 流れるようなアサーションには JUnit 5 + AssertJ を使用します
• モックには Mockito を使用し、可能な限り部分モック（partial mocks）を避けます
• 決定論的なテストを優先し、隠れた sleep 待機などは厳禁です

覚えておきましょう：コードの意図を明確にし、型安全で、観測可能な状態を保ちます。必要性が明確に証明されない限り、微細な最適化よりも保守性を優先します。