入口から記録まで一つの操作を追い、ファイルの海で迷わない読み方を身につけます。
このページでわかること
- 読む順番の決め方
- 送金を例にした追跡
- 設計書と実装を照合する方法
送金の道筋
src/app/app/transfer/page.tsx で入力と送信を見て、src/app/api/v1/transfers のルートで入口を見ます。次に TransferService から execute_transfer の呼び出しを探します。最後に該当するマイグレーションで、権限や帳簿への書き込みを確認します。
重要なのは全行を理解することではなく、どの層が何を保証するか言えるようになることです。
状態が変わる場所を特定する
コードを読むとき、画面に表示する関数と、実際に状態を変える関数を区別します。送金ではTransferServiceがRPCを呼び、口座ロックや仕訳の確定はデータベース関数側にあります。関数名だけで判断せず、どの表を書き込むかを追います。
正常な一件を追った後で、残高不足と通信切断の二例を追うと、エラーの戻し方と再試行の意味が分かります。
文書と実装が食い違ったら
設計書は意図を知る地図ですが、変更の途中で古い説明が残ることがあります。v1.0.0タグのコード、マイグレーション、テストを照合し、どの時点の話かを確認します。
読んだコードから「入力」「権限」「更新」「戻り値」「失敗時」の五点をメモすると、細部に迷わず動きを説明できます。
最初の15分の読み方
画面ファイルで送金ボタンの送信先と渡す値を探します。次にAPIのルートで、誰の認証情報を使い、何を検証し、どのサービスを呼ぶかを見ます。サービスでRPC名を見つけたら、マイグレーション内の同名関数へ進みます。
この順番なら、型定義やUI部品から読み始めて迷うことを減らせます。分からない関数名は、その場で全実装を追わず、流れに関わる入口と出口を先に押さえます。
一件の値を追跡する
送金先口座番号と金額を例に、画面の変数名、APIの入力名、RPCの引数名を横に並べます。どこでUUIDへ変わるか、どこで円整数の制約がかかるか、どの表に残るかが見えてきます。
同じ「口座」という言葉でも、顧客に見える口座番号と内部の口座IDは用途が違います。値の変換点を見逃さないことが、コード理解の近道です。
失敗経路から責任を見つける
残高不足ならどの層が拒否し、APIがどのエラーへ変換し、画面が何と表示するかを追います。OTP誤入力なら、送金は成立していないが申請の試行回数は変わるかもしれません。
成功経路だけでなく失敗経路を見ると、データベース、API、画面の責任がはっきりします。どこでロールバックするかも確認できます。
テストを答え合わせに使う
設計書で分からない点は、回帰テストの名前と期待結果を見ます。たとえば同じキーの再送、凍結口座の拒否、同時送金など、文章より具体的な条件が書かれています。
ただしテストが通ることと、考え得る全条件が網羅されていることは別です。テストから仕様を読み取り、まだ試されていない境界を自分で考えると理解が深まります。
一つの変更の影響を見積もる
送金額の上限を変えるだけでも、画面の案内、APIの入力検証、データベース関数、エラー表示、テストに影響します。コードを読めるようになるとは、ファイルを探せることに加え、変更時にどこを一緒に直すべきか見積もれることです。
マイグレーションは実装の履歴
現在の表定義だけでは、なぜ関数や制約がその形になったか分からないことがあります。マイグレーションを時系列で読むと、最初の表、権限の追加、送金関数、後から直した競合条件の順に設計判断を追えます。
ただし途中のファイル一つを最新仕様として読まないようにします。v1.0.0までに適用される後続の変更も確認して、最終的な動きを判断します。