moai-lang-java

クイックリファレンス（30 秒）

Java 21 LTS のエキスパート向けです。Spring Boot 3.3、仮想スレッド、最新の Java 機能を活用したエンタープライズ開発に対応します。

自動トリガー：拡張子が .java の Java ファイル、および pom.xml、build.gradle、build.gradle.kts などのビルドファイル

主な機能：

• Java 21 LTS：仮想スレッド、パターンマッチング、レコードパターン、シールドクラス
• Spring Boot 3.3：REST コントローラー、サービス、リポジトリ、WebFlux リアクティブ
• Spring Security 6：JWT 認証、OAuth2、ロールベースのアクセス制御
• JPA/Hibernate 7：エンティティマッピング、関連付け、クエリ、トランザクション
• JUnit 5：単体テスト、モック、TestContainers 統合
• ビルドツール：Maven 3.9、Kotlin DSL を使用する Gradle 8.5

---

実装ガイド（5 分）

Java 21 LTS の機能

Project Loom による仮想スレッド：

Executors.newVirtualThreadPerTaskExecutor に対して try-with-resources を使用します。IntStream.range を 0 から 10000 まで呼び出し、forEach で 1 秒間スリープして反復値を返すタスクを送信します。

構造化並行処理のプレビュー版パターン：

new StructuredTaskScope.ShutdownOnFailure に対して try-with-resources を使用します。scope.fork をラムダ式で呼び出し、ユーザーと注文を取得するタスクを fork します。scope.join を呼び出してから throwIfFailed を呼び出します。両方のタスクサプライヤーの結果を含む新しい複合オブジェクトを返します。

switch のパターンマッチング：

Object パラメーターを受け取る describe メソッドを作成します。switch 式で、ガード条件が i が 0 より大きい Integer i のケースでは正の整数を示すメッセージを返し、Integer i のケースでは非正の値を示すメッセージを返し、String s のケースでは長さを示すメッセージを返し、ワイルドカードを使用する List のケースではサイズを示すメッセージを返し、null のケースでは null 値を返し、default では未知の型を示すメッセージを返します。

レコードパターンとシールドクラス：

int x と int y を持つ Point レコードを定義します。Point topLeft と Point bottomRight を持つ Rectangle レコードを定義します。両方の Point コンポーネントを変数に分解する Rectangle パターンを switch で使用し、幅と高さの積の絶対値を返す area メソッドを作成します。Circle と Rectangle を許可する sealed Shape インターフェースを定義します。半径の二乗に PI を掛けた値を area メソッドで返す Circle レコードを実装します。

Spring Boot 3.3

REST コントローラーパターン：

RestController アノテーション、api/users に対する RequestMapping、RequiredArgsConstructor を使用して UserController を作成します。UserService を注入します。GetMapping と id に対する PathVariable を使用する getUser メソッドを作成し、findById の結果を ok にマッピングする ResponseEntity を返すか、notFound を返します。PostMapping、Valid アノテーション、CreateUserRequest に対する RequestBody を使用する createUser メソッドを作成します。ユーザーを作成し、URI の location を構築して、body を含む created レスポンスを返します。DeleteMapping を使用する deleteUser メソッドを作成し、サービスの結果に応じて noContent または notFound を返します。

サービスレイヤーパターン：

Service、RequiredArgsConstructor、Transactional readOnly true の各アノテーションを使用して UserService を作成します。UserRepository と PasswordEncoder を注入します。Optional を返す findById メソッドを作成します。重複するメールアドレスを確認して DuplicateEmailException をスローし、ビルダーパターンを使ってパスワードをエンコードした User を構築し、リポジトリに保存する、transactional な create メソッドを作成します。

Spring Security 6

セキュリティ設定パターン：

Configuration と EnableWebSecurity のアノテーションを使用して SecurityConfig を作成します。HttpSecurity を受け取る filterChain Bean を定義します。authorizeHttpRequests を設定し、公開 API のパスには permitAll、管理者用パスには hasRole ADMIN、その他すべてのリクエストには authenticated を指定します。デフォルト設定で oauth2ResourceServer に jwt を設定します。sessionManagement を STATELESS に設定し、csrf を無効にします。BCryptPasswordEncoder を返す passwordEncoder Bean を定義します。

JPA/Hibernate パターン

エンティティ定義パターン:

Entity アノテーションと Table アノテーションを付けて User エンティティを作成します。Lombok の Getter、Setter、NoArgsConstructor、Builder アノテーションを追加します。id を Id と GeneratedValue IDENTITY で定義します。name と email を Column nullable false で定義し、email には unique も指定します。status を Enumerated STRING で定義します。orders を OneToMany mappedBy user、cascade ALL、orphanRemoval true で定義します。

カスタムクエリ付きリポジトリパターン:

JpaRepository を継承した UserRepository を作成します。Optional を返す findByEmail を追加します。boolean を返す existsByEmail を追加します。Param アノテーションを使った findByIdWithOrders 用に、LEFT JOIN FETCH を使った JPQL の Query アノテーションを追加します。ページネーション用に Pageable を伴う findByNameContainingIgnoreCase を追加します。

レコードとしての DTO パターン:

id、name、email、status を持つ UserDto レコードを作成します。User エンティティからレコードを構築する静的ファクトリメソッド from を追加します。name に NotBlank と Size、email に NotBlank と Email、password に NotBlank と Size min 8 のアノテーションを付けた CreateUserRequest レコードを作成します。

---

高度なパターン

仮想スレッドの統合

Service と RequiredArgsConstructor アノテーションを付けた AsyncUserService を作成します。try-with-resources 内で StructuredTaskScope.ShutdownOnFailure を使用する fetchUserDetails メソッドを作成します。user と orders のクエリのタスクをフォークし、join して失敗した場合はスローし、複合結果を返します。newVirtualThreadPerTaskExecutor を使用し、ユーザー ID をストリーミングして処理タスクを送信する processUsersInParallel メソッドを作成します。

ビルド構成

Maven 3.9 パターン:

spring-boot-starter-parent バージョン 3.3.0 の parent を持つプロジェクトを定義します。java.version プロパティを 21 に設定します。spring-boot-starter-web と spring-boot-starter-data-jpa の依存関係を追加します。

Gradle 8.5 Kotlin DSL パターン:

org.springframework.boot、io.spring.dependency-management、java のプラグインを適用します。toolchain の languageVersion を 21 に設定します。web と data-jpa スターターの implementation 依存関係、test スターターの testImplementation を追加します。

JUnit 5 によるテスト

単体テストパターン:

ExtendWith MockitoExtension を付けたテストクラスを作成します。UserRepository に Mock アノテーションを追加します。UserService に InjectMocks を追加します。existsByEmail が false を返し、save が id 付きの user を返すようにスタブする shouldCreateUser テストを作成します。service の create を呼び出し、assertThat で result の id が 1 と等しいことを確認します。

TestContainers による統合テストパターン:

Testcontainers と SpringBootTest アノテーションを付けたテストクラスを作成します。postgres:16-alpine イメージの PostgreSQL 用の静的 Container を定義します。コンテナから datasource.url を設定する DynamicPropertySource を追加します。repository を Autowire します。user を保存し、assertThat で id が isNotNull であることを確認するテストを作成します。

---

Context7 統合

最新ドキュメント用のライブラリマッピング:

• spring-projects/spring-boot — Spring Boot 3.3 ドキュメント用
• spring-projects/spring-framework — Spring Framework コア用
• spring-projects/spring-security — Spring Security 6 用
• hibernate/hibernate-orm — Hibernate 7 ORM パターン用
• junit-team/junit5 — JUnit 5 テストフレームワーク用

---

相性の良い組み合わせ

• moai-lang-kotlin — Kotlin の相互運用性と Spring Kotlin 拡張用
• moai-domain-backend — REST API、GraphQL、マイクロサービスアーキテクチャ用
• moai-domain-database — JPA、Hibernate、R2DBC パターン用
• moai-foundation-quality — JUnit 5、Mockito、TestContainers 統合用
• moai-infra-docker — JVM コンテナ最適化用

---

トラブルシューティング

よくある問題:

• バージョンの不一致: java -version を実行し、JAVA_HOME が Java 21 を指していることを確認します
• コンパイルエラー: mvn clean compile -X または gradle build --info を実行します
• 仮想スレッドの問題: 必要に応じて --enable-preview を付けて Java 21 以上であることを確認します
• JPA の遅延読み込み: Transactional アノテーションまたは JOIN FETCH クエリを使用します

パフォーマンスのヒント:

• spring.threads.virtual.enabled を true に設定して仮想スレッドを有効にします
• 起動を高速化するために GraalVM Native Image を使用します
• HikariCP でコネクションプーリングを構成します

---

高度なドキュメント

包括的なリファレンス資料については、以下をご覧ください。

• Java 21 の機能、Context7 のマッピング、パフォーマンスについては reference.md
• 本番環境ですぐに使える Spring Boot の例については examples.md

---

最終更新日：2026-01-11 ステータス：本番環境対応済み（v1.1.0）