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');
});

请记住：如果你在路由定义中编写了多行代码，这些代码就应该放在控制器中！