laravel-routes-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routes Best Practices

路由最佳实践

Keep your route files clean and focused on mapping requests to controllers. Routes should never contain business logic, validation, or database operations.

保持路由文件简洁，专注于将请求映射到控制器。路由中绝不能包含业务逻辑、验证或数据库操作。

Anti-Pattern: Business Logic in Routes

反模式：路由中包含业务逻辑

php

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

php

// 错误示例：直接在路由中编写业务逻辑
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']);
});

// 错误示例：路由中包含验证逻辑
Route::post('/users', function (Request $request) {
    $validated = $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users',
    ]);

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

Best Practice: Clean Route Definitions

最佳实践：简洁的路由定义

php

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

php

// 正确示例：路由仅映射到控制器
Route::post('/order/{order}/cancel', [OrderController::class, 'cancel']);
Route::post('/users', [UserController::class, 'store']);

// 正确示例：使用路由组进行组织
Route::prefix('api/v1')->group(function () {
    Route::apiResource('orders', OrderController::class);
    Route::post('orders/{order}/cancel', [OrderController::class, 'cancel']);
});

// 正确示例：使用命名路由提升可维护性
Route::post('/order/{order}/cancel', [OrderController::class, 'cancel'])
    ->name('orders.cancel');

// 正确示例：路由中使用中间件，逻辑放在控制器
Route::middleware(['auth', 'verified'])->group(function () {
    Route::resource('admin/users', AdminUserController::class);
});

Controller Implementation

控制器实现

php

// 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',
        ];
    }
}

php

// 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',
        ];
    }
}

Route File Organization

路由文件组织

php

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

php

// routes/web.php - 保持极简
Route::get('/', [HomeController::class, 'index']);
Route::get('/about', [PageController::class, 'about']);

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

// routes/admin.php - 分离关注点
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路由
Route::prefix('v1')->group(function () {
    Route::apiResource('products', Api\ProductController::class);
    Route::post('products/{product}/reviews', [Api\ReviewController::class, 'store']);
});

Key Principles

核心原则

Routes are declarations, not implementations
- Define the HTTP verb, path, and controller method
- Nothing more

Use route model binding

php

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

Group related routes

php

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

Use resource controllers when appropriate

php

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

Leverage route caching in production
bash
```
sail artisan route:cache
```

路由是声明，而非实现
- 定义HTTP请求方法、路径和控制器方法
- 仅此而已

使用路由模型绑定

php

// Laravel会自动解析Order模型
Route::put('/orders/{order}', [OrderController::class, 'update']);

对相关路由进行分组

php

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

适当的时候使用资源控制器

php

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

在生产环境中利用路由缓存
bash
```
sail artisan route:cache
```

Common Mistakes to Avoid

需避免的常见错误

❌ Database queries in route closures
❌ Complex conditionals or loops in routes
❌ Direct model manipulation in routes
❌ Sending emails or notifications from routes
❌ File operations in route definitions
❌ API calls to external services in routes
❌ Session or cache manipulation in routes

❌ 在路由闭包中执行数据库查询
❌ 在路由中编写复杂的条件判断或循环
❌ 在路由中直接操作模型
❌ 在路由中发送邮件或通知
❌ 在路由定义中执行文件操作
❌ 在路由中调用外部服务的API
❌ 在路由中操作会话或缓存

When to Use Route Closures

何时使用路由闭包

Route closures are acceptable only for:

Simple static page renders
Temporary debugging/testing (remove before committing)
Quick prototypes (refactor to controllers before production)

php

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

仅在以下场景中可以使用路由闭包：

简单的静态页面渲染
临时调试/测试（提交前移除）
快速原型开发（上线前重构为控制器）

php

// 简单静态视图可以使用
Route::view('/terms', 'legal.terms');
Route::view('/privacy', 'legal.privacy');

// 或者简单的重定向
Route::redirect('/home', '/dashboard');
Route::permanentRedirect('/old-about', '/about');

Testing Routes

路由测试

php

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

Remember: If you're writing more than one line of code in a route definition, it belongs in a controller!

php

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

记住：如果你的路由定义中编写了超过一行代码，那它就应该放到控制器中！