既存コードはどこから読む？画面からDBまで1機能を追う手順

初めて担当するリポジトリを開いたら、クラスが何百個も並んでいた。どれが大事か分からず、上から開いているうちに何を調べていたか忘れてしまう。そんなときは「問い合わせ一覧を開く」のように、利用者の操作を一つだけ決めて読み始めると進めやすくなります。

最初の到達点は、すべてのクラスを理解することではありません。「この操作で、どの入力がどこへ渡り、どのデータが画面へ戻るのか」を説明できることです。この記事では架空の問い合わせ管理を使って、その経路と調査メモの作り方を示します。

調べる動作と、読み終える条件を決める

題材の問い合わせには、件名、投稿者、担当者と、下書き・受付済み・対応中・完了の状態があります。件名は必須で1〜100文字です。今回は登録や更新には広げず、「受付済みの問い合わせだけを一覧表示する」動作に絞ります。

読み終える条件は「一覧のリクエスト、呼ばれるメソッド、検索条件、返す項目、0件時の結果を説明できる」です。認証やページ送りが出てきたら、今回の表示に関わる部分だけ確認し、残りは未確認欄へ置きます。調査範囲を小さくしても、アクセス制御の有無など結果を変える条件まで無視してよいわけではありません。

実案件では、まずREADMEや起動方法、使用する版、テストの入口を読みます。動かす場合は開発用データであることも確認してください。ここで起動できなければ「静的に読んだ範囲」と「実行して確かめた範囲」を分けたまま調査できます。

画面からDB、戻り値までを一本で追う

今回追う経路は次のとおりです。Controllerの戻り値も、画面へ着くまで追うのがポイントです。

問い合わせ一覧の「受付済み」を選ぶ
  → GET /api/inquiries?status=受付済み
  → InquiryController.list(status)
  → InquiryService.list(status)
  → InquiryRepository.findByStatus(status)
  → DB: inquiriesをstatusで検索
  → List<Inquiry> → JSON応答 → 一覧の行を表示

図は説明用の構成です。検証ではJava 17.0.8、Spring Framework 6.1.1のMockMvc、H2 2.2.224を使い、リクエストの振り分けからDB検索、JSON応答まで確認しました。これらは今回の再現環境で、現在の推奨版を示すものではありません。ブラウザでの描画、実ネットワーク、認証、登録機能は検証に含めていません。

1. 画面で起きた通信を入口にする

利用者が「受付済み」を選んだとき、画面のURLが変わるのか、裏でAPIを呼ぶのかを確認します。ブラウザの開発者向け機能で通信を調べられる環境なら、操作直前に記録を始め、パス、HTTPメソッド、パラメーター、応答を見ます。認証ヘッダーやCookieをそのまま共有資料に貼らないでください。

この例ではGETのパスが/api/inquiries、検索条件がstatus=受付済みです。ボタンの文言だけでコードを探すより、リクエストのパスを探すほうが入口へつながることがあります。文言が翻訳ファイルや共通部品にある場合も、通信という観測結果が手がかりになります。

通信が発生しないなら、その事実も有用です。取得済みデータを画面内で絞っている可能性があります。ただし「通信なし＝DBは無関係」とは言えません。元のデータをどの通信で取得したかへ一つ戻ります。

2. Controllerの入力と呼び出し先を読む

次はパスに対応するメソッドを探します。Spring MVCでは、クラスの@RequestMappingとメソッドの@GetMappingなどを合わせて読む必要があります。URLに加えてHTTPメソッド等も対応条件になります。Spring公式のリクエストマッピングで仕組みを確認できます。

以下は検証用コードから抜き出した断片です。クラス全体や必要なimportは省略しています。

@GetMapping("/api/inquiries")
public List<Inquiry> list(@RequestParam("status") String status)
        throws SQLException {
    return service.list(status);
}

読む情報は「どこから来るか」「どんな値を受け取るか」「何を呼ぶか」「何を返すか」です。この断片ではstatusを受け取り、Serviceへそのまま渡します。入力の妥当性、ログイン利用者、権限のチェックは読み取れないので、実案件なら別の設定や処理を確認します。メソッドが短いことを、調査が終わった根拠にはしません。

Controllerの役割を整理したくなったら、Controllerでやってはいけないことへ進めます。経路を読んでいる最中に、設計の修正まで始める必要はありません。

3. Serviceから検索条件とDBまで降りる

この例のServiceは、RepositoryのfindByStatusへstatusを渡すだけです。しかし実案件では、利用者の所属で検索範囲を狭めたり、状態を別の値へ変換したりすることがあります。引数名が同じでも、値が途中で変わらないかを見ます。

Repositoryで使うSQLは次のとおりです。ここでも、実装から抜き出した断片を示しています。

SELECT id, title, status
FROM inquiries
WHERE status = ?
ORDER BY id

?にはJava側からstatusを設定します。JDBCのPreparedStatementは、パラメーターへ値を設定して実行する仕組みです。この例は文字列をSQLへ連結しません。

ここで確認するのは、テーブル名だけではありません。「受付済み」という画面の条件がWHERE句に届くか、並び順は何か、どの列を返すかを対応づけます。ORMでSQLがソースに書かれていないなら、Repositoryの定義やマッピングから調べ、必要に応じて開発環境のSQL記録で補います。ログに出なかったことだけで、SQLが実行されていないとは断定できません。

4. DBの結果が、どの形で戻るかを見る

検索の先まで降りたら、戻り道を逆に確認します。DBの1行をどのオブジェクトへ変換し、Serviceが加工し、Controllerがどんな応答を返すのか。APIと画面の名前が違う項目や、一覧に出していない列もあります。

今回のテストでは、受付済みのデータがID 1と3の2件になり、次のJSONを返しました。完了は0件なので、応答は空配列[]でした。

[
  {"id":1,"title":"ログイン方法","status":"受付済み"},
  {"id":3,"title":"設定相談","status":"受付済み"}
]

これはMockMvcによる確認です。Spring公式の説明のとおり、MockMvcは実際のHTTPサーバーを動かさずにSpring MVCの処理を試します。したがって、JSONが正しいことから「ブラウザで0件メッセージが表示された」までは言えません。画面側の配列の描画、0件表示、通信失敗時の表示を別に追います。

調査メモは、観測した経路を残す

ファイル名を大量に並べるより、次の担当者が追い直せる短いメモにします。以下は今回の検証に対応する記入例です。

実案件のメモには、確認したブランチやコミット、ファイルとメソッド、実行条件も添えます。「たぶんこの処理」なら仮説と書き、呼び出された証拠がある場所と区別します。コメントは手がかりですが、変更前の仕様が残ることもあるため、コメントの書き方も意識しつつ実装と照合します。

一本つながったら、次は「担当者で絞るとどこが変わるか」のように隣の条件へ広げられます。Serviceが大きく読みづらいときは、Serviceの分割例が判断を補います。

作る側からつながりを学び直すなら

Java・HTML・CSS・SQLの基礎があり、画面と処理のつながりを自分で作りながら学びたい人には、『作って学ぶ Spring Boot入門』が選書候補です。出版社の紹介を確認し、脱初心者の本棚で案内しています。本人の読後体験としての紹介ではありません。

本棚にはアフィリエイトリンクを含みます。この記事の調査手順は、購入せずに使えます。まず今担当する一つの操作について、入口・入力・出力・未確認を一枚に残してみてください。