laravel-best-practices

Laravel のベストプラクティス

Laravel アプリケーション向けの包括的なベストプラクティスガイドです。10 のカテゴリにわたる 40 のルールを収録し、自動リファクタリングとコード生成の指針となるよう、影響度順に優先順位を付けています。

適用するタイミング

次のような場合に、これらのガイドラインを参照してください。

• 新しい Laravel コントローラー、サービス、モデルを作成するとき
• 認証と認可を実装するとき
• アーキテクチャやセキュリティの問題がないかコードをレビューするとき
• 既存の Laravel コードベースをリファクタリングするとき
• パフォーマンスやデータベースクエリを最適化するとき
• マイクロサービスやキューベースのアーキテクチャを構築するとき

優先順位別のルールカテゴリ

優先順位	カテゴリ	影響度	接頭辞
1	アーキテクチャ	CRITICAL	arch-
2	依存性注入	CRITICAL	di-
3	エラー処理	HIGH	error-
4	セキュリティ	HIGH	security-
5	パフォーマンス	HIGH	perf-
6	テスト	MEDIUM-HIGH	test-
7	データベースと ORM	MEDIUM-HIGH	db-
8	API 設計	MEDIUM	api-
9	マイクロサービス	MEDIUM	micro-
10	DevOps とデプロイ	LOW-MEDIUM	devops-

クイックリファレンス

1. アーキテクチャ（CRITICAL）

• arch-avoid-circular-deps - サービスプロバイダー間の循環依存を避ける
• arch-feature-modules - 技術レイヤーではなく、ドメイン／機能単位で整理する
• arch-single-responsibility - 「何でも屋」のサービスではなく、役割を絞ったサービスにする
• arch-use-repository-pattern - テスト容易性を高めるため、データベースロジックを抽象化する
• arch-use-events - 疎結合を実現するため、イベント駆動型アーキテクチャを採用する

2. 依存性注入（CRITICAL）

• di-avoid-service-locator - サービスロケーターとして app() ヘルパーを使わない
• di-interface-segregation - インターフェース分離の原則（ISP）
• di-liskov-substitution - リスコフの置換原則（LSP）
• di-prefer-constructor-injection - Facade／ヘルパーによる注入より、コンストラクター注入を優先する
• di-scope-awareness - singleton／bind／scoped バインディングを理解する
• di-use-interfaces-tokens - インターフェースを実装にバインドする

3. エラー処理（HIGH）

• error-use-exception-handler - 例外処理を一元化する
• error-throw-http-exceptions - 適切な HTTP 例外を使用する
• error-handle-queue-errors - キューとジョブのエラーを適切に処理する

4. セキュリティ（HIGH）

• security-auth-jwt - Sanctum／Passport を使って認証を安全に実装する
• security-validate-all-input - Form Requests を使って入力を検証する
• security-use-guards - 認証ガード、ゲート、ポリシーを使用する
• security-sanitize-output - XSS 攻撃を防ぐ
• security-rate-limiting - レート制限を実装する

5. パフォーマンス（HIGH）

• perf-service-provider-lifecycle - サービスプロバイダーの boot／register ライフサイクルを適切に管理する
• perf-use-caching - キャッシュ戦略を実装する
• perf-optimize-database - データベースクエリを最適化する
• perf-lazy-loading - Lazy Collection とルートキャッシュを使用する

6. テスト（MEDIUM-HIGH）

• test-use-testcase-refresh-database - Laravel TestCase と RefreshDatabase を使用する
• test-e2e-http - Laravel を使った HTTP／機能テストを実施する
• test-mock-external-services - Facade を使って外部依存関係をモックする

7. データベースと ORM（MEDIUM-HIGH）

• db-use-transactions - トランザクションを管理する
• db-avoid-n-plus-one - Eager Loading を使って N+1 クエリの問題を避ける
• db-use-migrations - スキーマ変更にはマイグレーションを使用する

8. API 設計（MEDIUM）

• api-use-dto-serialization - API Resources とシリアライズを使用する
• api-use-interceptors - 横断的関心事にはミドルウェアを使用する
• api-versioning - API のバージョン管理戦略を採用する
• api-use-pipes - 入力変換には Form Requests を使用する

9. マイクロサービス（MEDIUM）

• micro-use-patterns - メッセージングとイベントのパターンを使用する
• micro-use-health-checks - オーケストレーション向けのヘルスチェックを実装する
• micro-use-queues - キューを使ってバックグラウンドジョブを処理する

10. DevOps とデプロイ（LOW-MEDIUM）

• devops-use-config-module - config() を使って環境設定を行う
• devops-use-logging - チャネルを使って構造化ログを記録する
• devops-graceful-shutdown - ダウンタイムなしでデプロイする

使用方法

詳細な説明とコード例については、各ルールファイルをお読みください。

rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md

各ルールファイルには、以下が含まれています。

• 重要な理由の簡単な説明
• 説明付きの不適切なコード例
• 説明付きの適切なコード例
• 追加の背景情報と参考資料

特定のルールについて実装の詳細を確認する必要がある場合にのみ、AGENTS.md または個別の rules/*.md ファイルをお読みください。事前に読み込まないでください。

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。

Laravel Boost との互換性

Laravel Boost がインストールされている場合、以下のルールはコアガイドラインですでにカバーされているため、省略できます。

security-validate-all-input、security-auth-jwt、db-avoid-n-plus-one、 db-use-migrations、perf-use-caching、test-use-testcase-refresh-database、 devops-use-logging、api-versioning