laravel-routes-best-practices

ルートのベストプラクティス

ルートファイルは、リクエストをコントローラーにマッピングすることに専念させ、シンプルに保ちましょう。ルートにビジネスロジック、バリデーション、データベース操作を含めてはいけません。

アンチパターン：ルートにビジネスロジックを記述する

// BAD: Business logic directly in routes
Route::post('/order/{order}/cancel', function (Order $order) {
    if ($order->status !== 'pending') {
        return response()->json(['error' => 'Cannot cancel'], 400);
    }

    $order->status = 'cancelled';
    $order->cancelled_at = now();
    $order->save();

    Mail::to($order->user)->send(new OrderCancelled($order));

    return response()->json(['message' => 'Order cancelled']);
});

// BAD: Validation in routes
Route::post('/users', function (Request $request) {
    $validated = $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users',
    ]);

    return User::create($validated);
});

ベストプラクティス：クリーンなルート定義

// GOOD: Routes only map to controllers
Route::post('/order/{order}/cancel', [OrderController::class, 'cancel']);
Route::post('/users', [UserController::class, 'store']);

// GOOD: Use route groups for organization
Route::prefix('api/v1')->group(function () {
    Route::apiResource('orders', OrderController::class);
    Route::post('orders/{order}/cancel', [OrderController::class, 'cancel']);
});

// GOOD: Named routes for maintainability
Route::post('/order/{order}/cancel', [OrderController::class, 'cancel'])
    ->name('orders.cancel');

// GOOD: Middleware in routes, logic in controllers
Route::middleware(['auth', 'verified'])->group(function () {
    Route::resource('admin/users', AdminUserController::class);
});

コントローラーの実装

// app/Http/Controllers/OrderController.php
class OrderController extends Controller
{
    public function __construct(
        private readonly OrderCancellationService $cancellationService
    ) {}

    public function cancel(CancelOrderRequest $request, Order $order)
    {
        $this->cancellationService->cancel($order);

        return response()->json([
            'message' => 'Order cancelled successfully'
        ]);
    }
}

// app/Http/Requests/CancelOrderRequest.php
class CancelOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->can('cancel', $this->route('order'));
    }

    public function rules(): array
    {
        return [
            'reason' => 'nullable|string|max:500',
        ];
    }
}

ルートファイルの構成

// routes/web.php - Keep it minimal
Route::get('/', [HomeController::class, 'index']);
Route::get('/about', [PageController::class, 'about']);

require __DIR__ . '/auth.php';
require __DIR__ . '/admin.php';

// routes/admin.php - Separate concerns
Route::prefix('admin')
    ->middleware(['auth', 'admin'])
    ->name('admin.')
    ->group(function () {
        Route::get('/dashboard', [AdminDashboardController::class, 'index'])
            ->name('dashboard');
        Route::resource('users', AdminUserController::class);
    });

// routes/api.php - API routes
Route::prefix('v1')->group(function () {
    Route::apiResource('products', Api\ProductController::class);
    Route::post('products/{product}/reviews', [Api\ReviewController::class, 'store']);
});

主な原則

1. ルートは宣言であり、実装ではありません

   • HTTP メソッド、パス、コントローラーメソッドを定義します
   • それ以外は何も記述しません

2. ルートモデルバインディングを使用する

   // Laravel automatically resolves the Order model
   Route::put('/orders/{order}', [OrderController::class, 'update']);
   

3. 関連するルートをグループ化する

   Route::controller(OrderController::class)->group(function () {
       Route::get('/orders', 'index');
       Route::get('/orders/{order}', 'show');
       Route::post('/orders', 'store');
   });
   

4. 適切な場合はリソースコントローラーを使用する

   Route::resource('photos', PhotoController::class)
       ->only(['index', 'show'])
       ->names('gallery.photos');
   

5. 本番環境ではルートキャッシュを活用する

   sail artisan route:cache
   

避けるべきよくある間違い

• ❌ ルートクロージャ内でのデータベースクエリ
• ❌ ルート内の複雑な条件分岐やループ
• ❌ ルート内でのモデルの直接操作
• ❌ ルートからのメールや通知の送信
• ❌ ルート定義内でのファイル操作
• ❌ ルートから外部サービスへの API 呼び出し
• ❌ ルート内でのセッションやキャッシュの操作

ルートクロージャを使用する場合

ルートクロージャを使用できるのは、次の場合に限られます。

• シンプルな静的ページの表示
• 一時的なデバッグやテスト（コミット前に削除してください）
• 手早く作成するプロトタイプ（本番環境に投入する前にコントローラーへリファクタリングしてください）

// Acceptable for simple static views
Route::view('/terms', 'legal.terms');
Route::view('/privacy', 'legal.privacy');

// Or simple redirects
Route::redirect('/home', '/dashboard');
Route::permanentRedirect('/old-about', '/about');

ルートのテスト

test('order cancellation route requires authentication', function () {
    $order = Order::factory()->create();

    $response = $this->postJson("/orders/{$order->id}/cancel");

    $response->assertUnauthorized();
});

test('route names are properly defined', function () {
    expect(route('orders.cancel', ['order' => 1]))
        ->toBe('http://localhost/orders/1/cancel');
});

覚えておきましょう。ルート定義にコードを1行より多く記述するなら、そのコードはコントローラーに記述すべきです！