Laravel 13 控制器属性详解

摘要

Laravel 13 扩展了控制器属性的用法，使中间件和授权配置更加声明式。本文将深入讲解控制器属性的使用，包括：

• 中间件属性详解
• 授权属性应用
• 路由属性配置
• 属性组合与优先级
• 实战案例与最佳实践

本文适合希望采用声明式控制器配置的 Laravel 开发者。

1. 中间件属性

1.1 类级别中间件

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
class DashboardController extends Controller
{
    public function index()
    {
        // 所有方法都需要认证
    }
}

1.2 方法级别中间件

class UserController extends Controller
{
    #[Middleware('auth')]
    public function profile()
    {
        // 需要认证
    }
    
    public function public()
    {
        // 不需要认证
    }
}

1.3 多个中间件

#[Middleware(['auth', 'verified', 'subscribed'])]
class PremiumController extends Controller
{
    // 需要认证、邮箱验证、订阅
}

1.4 中间件参数

#[Middleware('throttle:60,1')]
class ApiController extends Controller
{
    // 每分钟 60 次请求
}

#[Middleware('role:admin,editor')]
class AdminController extends Controller
{
    // 需要 admin 或 editor 角色
}

1.5 排除中间件

#[Middleware('auth')]
class UserController extends Controller
{
    public function index()
    {
        // 需要 auth
    }
    
    #[Middleware(except: ['auth'])]
    public function public()
    {
        // 不需要 auth
    }
}

2. 授权属性

2.1 基本授权

use Illuminate\Routing\Attributes\Controllers\Authorize;

class PostController extends Controller
{
    #[Authorize('create', Post::class)]
    public function create()
    {
        // 只有有创建权限的用户可以访问
    }
}

2.2 模型授权

class PostController extends Controller
{
    #[Authorize('update', 'post')]
    public function update(Post $post)
    {
        // 自动解析 'post' 路由参数
    }
}

2.3 复杂授权

#[Authorize('delete', [Post::class, 'post'])]
public function destroy(Post $post)
{
    // 使用路由参数解析模型
}

2.4 组合授权

#[Middleware('auth')]
#[Authorize('access-admin-panel')]
class AdminController extends Controller
{
    // 需要认证且有访问管理面板权限
}

3. 路由属性

3.1 基本路由

use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Post;

class PostController extends Controller
{
    #[Get('/posts')]
    public function index()
    {
        // GET /posts
    }
    
    #[Post('/posts')]
    public function store()
    {
        // POST /posts
    }
}

3.2 路由参数

#[Get('/posts/{post}')]
public function show(Post $post)
{
    // GET /posts/{post}
}

#[Get('/users/{user}/posts/{post}')]
public function showUserPost(User $user, Post $post)
{
    // GET /users/{user}/posts/{post}
}

3.3 路由名称

#[Get('/posts', name: 'posts.index')]
public function index()
{
    // route('posts.index')
}

3.4 路由组

use Illuminate\Routing\Attributes\Prefix;

#[Prefix('api/v1')]
#[Middleware('auth:sanctum')]
class ApiPostController extends Controller
{
    #[Get('/posts')]
    public function index()
    {
        // GET /api/v1/posts
    }
}

4. 属性组合

4.1 完整示例

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Post;
use Illuminate\Routing\Attributes\Put;
use Illuminate\Routing\Attributes\Delete;
use Illuminate\Routing\Attributes\Prefix;
use Illuminate\Routing\Attributes\Controllers\Middleware;
use Illuminate\Routing\Attributes\Controllers\Authorize;

#[Prefix('api/v1/posts')]
#[Middleware(['auth:sanctum', 'throttle:api'])]
class PostController extends Controller
{
    #[Get('/', name: 'api.posts.index')]
    public function index()
    {
        // GET /api/v1/posts
    }
    
    #[Get('/{post}', name: 'api.posts.show')]
    public function show(Post $post)
    {
        // GET /api/v1/posts/{post}
    }
    
    #[Post('/', name: 'api.posts.store')]
    #[Authorize('create', Post::class)]
    public function store()
    {
        // POST /api/v1/posts
    }
    
    #[Put('/{post}', name: 'api.posts.update')]
    #[Authorize('update', 'post')]
    public function update(Post $post)
    {
        // PUT /api/v1/posts/{post}
    }
    
    #[Delete('/{post}', name: 'api.posts.destroy')]
    #[Authorize('delete', 'post')]
    public function destroy(Post $post)
    {
        // DELETE /api/v1/posts/{post}
    }
}

5. 最佳实践

5.1 组织属性

// 推荐：按类型组织
#[Prefix('api/v1')]
#[Middleware('auth:sanctum')]
class Controller
{
    #[Get('/resource')]
    #[Middleware('throttle:60,1')]
    #[Authorize('view', Resource::class)]
    public function show() {}
}

5.2 避免过度使用

// 不推荐：过多属性
#[Get('/posts')]
#[Middleware('auth')]
#[Middleware('verified')]
#[Middleware('admin')]
#[Authorize('view')]
#[Throttle(60)]
public function index() {}

// 推荐：合理组合
#[Get('/posts')]
#[Middleware(['auth', 'verified', 'admin'])]
#[Authorize('view')]
public function index() {}

6. 总结

Laravel 13 的控制器属性提供了声明式的配置方式：

1. 中间件属性：简化中间件配置
2. 授权属性：声明式权限控制
3. 路由属性：路由定义与控制器绑定
4. 属性组合：灵活的配置组合

通过本指南，您已经掌握了控制器属性的核心用法。

参考资料

• Laravel 13 控制器文档
• PHP 8 Attributes