機能マニフェスト: Spring Boot Enterprise

このブループリントは、Antigravity Agent Factory における高精度の Spring Boot 3+ サービスのエンジニアリング、テスト、デプロイメントに関する手順的な真実を提供します。

運用環境

• JDK: 21 (LTS) - records、sealed classes、switch expressions の必須使用。
• ビルド: Maven 3.9+ (ラップ済み)。
• 主要スタック: Boot 3.4、Spring Data JPA (PostgreSQL)、Spring Security (OIDC)、Micrometer (OTEL)。

プロセス

エンタープライズグレードの Spring Boot アプリケーションを構築するには、以下の手順に従ってください:

手順 1: サービスのスキャフォルディング

標準的なファクトリ衛生を確保するために、以下のステップを順序立てて実行してください:

1. 生成: mvn archetype:generate -Dfilter=antigravity-service-pattern を実行します(または内部の scaffold.py を使用)。
2. 構造確認: src/main/java が com.antigravity.[domain].[service] パターンに従っていることを確認します。
3. 真実確認: pom.xml に spring-boot-starter-validation と spring-boot-starter-actuator が含まれていることを検証します。

手順 2: ドメイン機能の実装 (Red-Green-Refactor)

1. Red: スライステストを作成します(例: API の場合は @WebMvcTest、永続化の場合は @DataJpaTest)。
   • ツール: mvn test -Dtest=MyFeatureTest
2. Green: サービスロジックを実装します。
   • 公理チェック: DTO には record を使用します。Entity をコントローラーを通して公開しないようにします。
3. Refactor: 静的解析を実行します。
   • ツール: mvn checkstyle:check と mvn pmd:check。

手順 3: レジリエンスと可観測性のセットアップ

1. Actuator を追加: /actuator/health と /actuator/metrics が公開されていても保護されていることを確認します。
2. ロギング設定: ELK/Loki 向けに JSON 出力を備えた logback-spring.xml を使用します。
3. サーキットブレーカー: すべての外部 API 呼び出しに Resilience4j を使用します。

プロセス (障害状態とリカバリー)

症状	原因の可能性	リカバリー操作
BeanDefinitionOverrideException	コンテキスト内で重複する Bean 名。	@Configuration クラス内の @Component と @Bean の重複をチェックします。@Primary は最後の手段としてのみ使用してください。
LazyInitializationException	トランザクション外でプロキシにアクセス。	決して spring.jpa.open-in-view=true を使用しないでください。@Service レイヤー内または EntityGraph で DTO マッピングを使用します。
ConnectionTimeout	DB コネクションプールの飽和。	hikari.maximum-pool-size をチェックします。すべての DB ストリーム/コネクションが try-with-resources 内にあることを確認します。

慣例的コードパターン (金標準)

"Truthful" Record DTO

public record UserResponse(
    UUID id,
    @NotBlank String username,
    @Email String email,
    LocalDateTime createdAt
) {}

"Observable" Service

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class OrderService {
    private final ObservationRegistry observationRegistry;

    @Transactional
    public OrderResponse placeOrder(OrderRequest request) {
        return Observation.createNotStarted("order.place", observationRegistry)
            .observe(() -> {
                // Business logic here
                return new OrderResponse(...);
            });
    }
}

前提条件

アクション	コマンド
ビルド & チェック	mvn clean verify
高速テストループ	mvn test -DskipITs
脆弱性チェック	mvn ossindex:audit
コード フォーマット	mvn spotless:apply

使用時期

このブループリントは、Java/Spring サービスを構築、リファクタリング、またはデバッグする際に使用してください。これは「Spring とは何か」に対する「どのように構築するか」の権威的なソースです。

ベストプラクティス

• システム公理 (A1-A5) に従ってください
• すべての変更が検証可能であることを確認してください
• 将来のメンテナンスに備えて複雑なロジックを文書化してください