311-frameworks-spring-jdbc

Spring JDBC — JdbcClient（Spring Framework 7 以降）

Spring JDBC のガイドラインを適用し、JdbcClient をデフォルトとして使用します。JdbcClient で対応していないレガシーコードや API（バッチ更新、KeyHolder、RowCallbackHandler によるストリーミング）に限り、JdbcTemplate / NamedParameterJdbcTemplate を使用します。

このスキルの対象範囲

• パラメーター化された SQL（ユーザー入力を連結しない）
• JdbcClient の流れるような API（Spring Framework 7 以降）— クエリと更新で優先的に使用
• JdbcClient による名前付きパラメーター。レガシーコードの移行では NamedParameterJdbcTemplate を使用
• RowMapper、query(Class)、レコード
• バッチ処理と生成キー（必要に応じて JdbcTemplate / JdbcOperations）
• 生成キーの安全な取り扱い（KeyHolder、単一行の JdbcClient 更新）
• サービス層の @Transactional 境界
• 読み取り専用トランザクション（@Transactional(readOnly = true)）
• 単一行の安全な取得（queryForObject ではなく optional() / findFirst()）
• 大規模な結果セットのストリーミング（RowCallbackHandler、ResultSetExtractor）
• DataAccessException の処理（DuplicateKeyException、EmptyResultDataAccessException）
• @Sql フィクスチャを使った @JdbcTest スライステスト

スコープ： 参照ルールと適切なコード例・不適切なコード例に基づいて推奨事項を適用します。

制約

Spring JDBC に変更を加える前に、プロジェクトがコンパイルできることを確認してください。コンパイルに失敗した場合は、ただちに作業を中止してください。改善を適用した後は、完全な検証を実行してください。

• 必須： 変更を加える前に ./mvnw compile または mvn compile を実行します
• 安全性： コンパイルに失敗した場合は、ただちに作業を中止します
• 検証： 改善を適用した後に ./mvnw clean verify または mvn clean verify を実行します
• SQL インジェクション： 信頼できない入力を SQL 文字列に連結しないでください。必ずバインドパラメーターを使用します
• 適用前： 詳細なルールと適切なパターン・不適切なパターンについて、参照資料を読みます

このスキルを使う場面

• Spring JDBC（JdbcTemplate、JdbcClient、NamedParameterJdbcTemplate）を使った Java コードをレビューする
• Java コードの Spring JDBC データアクセスに関するベストプラクティスを適用する
• JDBC コードの SQL インジェクションのリスクを検出して修正する
• JDBC 操作のトランザクション境界や例外処理を改善する
• Spring Framework 7 の JdbcClient の使用状況をレビューする

ワークフロー

1. 参照資料を読み、プロジェクトの状況を把握する

変更を提案する前に、references/311-frameworks-spring-jdbc.md を読み、現在のプロジェクト設定を確認します。

2. 対象範囲を把握し、改善内容を決める

依頼された成果、制約、適用する変更のうち安全な最小限の範囲を特定します。

3. フレームワークに沿った変更を適用する

参照パターンとプロジェクトの規約に従って、設定やコードを実装またはリファクタリングします。

4. 検証を実行し、結果を報告する

適切なビルドやテストを実行し、変更内容、検証内容、今後の対応事項をまとめます。

参照資料

詳細なガイダンス、例、制約については、references/311-frameworks-spring-jdbc.md を参照してください。