Summary
この文書の要点
- APIは画面コンポーネントではなく業務操作を単位に設計する。
- React側の表示型とLaravel側の永続化モデルを分ける。
- Reactには表示状態と入力補助を置き、確定判断と整合性はLaravel API側に寄せる。
- APIレスポンスはEloquentモデルではなく、画面用途に合わせたDTOとして設計する。
どこが設計の難所か
画面に必要な項目をそのままAPIレスポンスに足し続けると、特定画面専用の巨大なエンドポイントになります。反対に、DBテーブル単位のCRUDだけにすると、フロントエンドが業務ルールを組み立てることになります。
Reactは状態や表示を柔軟に組み立てられますが、業務上の状態遷移や権限はクライアントに任せられません。Laravel側もEloquentモデルをそのまま公開すると、内部構造変更がAPI破壊につながります。
Laravel APIとReactフロントエンドの構成では、どちらにも実装しやすい処理が増えます。入力検証、権限表示、ステータス変更、一覧フィルタを画面側へ寄せすぎると、API利用経路が増えた時にルールが分散します。
境界をどう切るか
APIは、一覧参照、詳細参照、業務操作、補助マスタ取得のように役割を分けます。React側には画面用DTOを返し、更新系はコマンドとして必要な入力だけを受け取ります。状態遷移はLaravel側のサービス層やアクションに集約します。
境界は、確定した業務状態をLaravel側、未確定の操作状態をReact側と考えると整理しやすくなります。Reactは入力中の値、並び替え、フィルタ、楽観表示を扱い、Laravelは保存時の検証、権限、状態遷移、監査ログを担います。
実装で効く細部
LaravelではRequestクラスで入力検証し、ResourceやDTOでレスポンスを整えます。React側ではAPIレスポンス型を画面状態へ変換し、フォームの一時状態と保存済み状態を分けます。エラーはフィールドエラー、権限エラー、状態競合に分類します。
LaravelではForm RequestやActionクラスで入力とユースケースを分け、EloquentモデルをそのままJSON化しないようにします。React側はAPI DTOから画面モデルへ変換し、フォームschemaとサーバーエラーを対応付けます。
- 状態遷移はフロントエンドのボタン表示ではなく、API側の許可ルールとして実装する。
- 一覧APIは検索条件、ソート、ページングを明示し、画面側の暗黙フィルタを避ける。
- APIエラーはfield_errorsとglobal_errorsを分け、Reactで表示位置を制御する。
壊れ方を観測する
検証では、画面からの正常操作だけでなく、直接APIを呼んだ場合に不正な状態遷移が通らないかを確認します。API契約のテストと、主要画面のE2Eを組み合わせると境界の破れを見つけやすくなります。
検証では、ReactのフォームテストとLaravel APIのFeature testを分けます。画面でボタンが隠れていることだけでなく、直接APIを呼んだ場合にも権限や状態遷移が拒否されることを確認します。
捨てた選択肢とトレードオフ
DTOを分けるとコード量は増えます。小規模な管理画面ではEloquentに近いレスポンスで十分なこともあります。ただし、複数画面や外部連携がある場合は、早めに契約を分けた方が変更しやすくなります。
すべての表示条件をAPIから返すと画面は単純になりますが、UI変更のたびにAPI契約が変わりやすくなります。逆に画面側で判断しすぎると業務ルールが漏れます。業務上の正しさに関わる判断だけはAPI側に寄せるのが安全です。
現場に残す判断軸
LaravelとReactの分離は、技術スタックの分離だけでは不十分です。業務ルールをどこに置き、画面都合をどこで吸収するかを決めることで、長く保守できるAPIになります。
LaravelとReactの分離は、技術スタックの分離ではなく責務の分離です。保存後に正しい状態を保証する場所と、保存前に気持ちよく操作できる場所を分けると、長く保守しやすい構成になります。
