Laravel构建RESTful API：中间件与认证

构建RESTful API：中间件与认证

在本章中，我们将讲解如何使用Laravel构建RESTful API，重点介绍中间件的使用以及实现用户认证与授权的方法。通过学习本章，你将能够创建一个安全、可靠的RESTful API。

1. 构建基础RESTful API

1.1 创建API资源控制器

首先，我们需要创建一个API资源控制器。假设我们要构建一个管理博客文章的API，可以通过以下命令创建控制器：

php artisan make:controller Api/PostController --api

上述命令将在 app/Http/Controllers/Api 目录下创建一个名为 PostController.php 的文件，并自动生成基本的API方法。

1.2 定义API路由

接下来，我们需要在 routes/api.php 文件中定义API路由。打开该文件，添加以下内容：

use App\Http\Controllers\Api\PostController;

Route::apiResource('posts', PostController::class);

这将自动为 PostController 生成标准的RESTful路由，包括 index、store、show、update 和 destroy 方法。

1.3 实现控制器方法

打开 PostController.php 文件，实现API方法。以下是一个示例：

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function index()
    {
        return Post::all();
    }

    public function store(Request $request)
    {
        $validatedData = $request->validate([
            'title' => 'required|string|max:255',
            'content' => 'required|string',
        ]);

        $post = Post::create($validatedData);

        return response()->json($post, 201);
    }

    public function show($id)
    {
        $post = Post::findOrFail($id);

        return response()->json($post);
    }

    public function update(Request $request, $id)
    {
        $validatedData = $request->validate([
            'title' => 'sometimes|required|string|max:255',
            'content' => 'sometimes|required|string',
        ]);

        $post = Post::findOrFail($id);
        $post->update($validatedData);

        return response()->json($post);
    }

    public function destroy($id)
    {
        $post = Post::findOrFail($id);
        $post->delete();

        return response()->json(null, 204);
    }
}

在这个控制器中，我们实现了基本的CRUD操作，并使用 response()->json 方法返回JSON响应。

2. 使用中间件

中间件是处理HTTP请求的过滤器。中间件可以在请求到达控制器之前或响应发送到用户之前执行特定的操作。

2.1 创建中间件

你可以使用 artisan 命令创建一个中间件。例如，创建一个检查API请求是否包含特定头信息的中间件：

php artisan make:middleware CheckHeader

这将在 app/Http/Middleware 目录下创建一个名为 CheckHeader.php 的文件。

2.2 实现中间件

打开 CheckHeader.php 文件，添加以下代码：

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class CheckHeader
{
    public function handle(Request $request, Closure $next)
    {
        if (!$request->hasHeader('X-Example-Header')) {
            return response()->json(['error' => 'Missing X-Example-Header'], 400);
        }

        return $next($request);
    }
}

这个中间件检查请求是否包含 X-Example-Header 头信息，如果没有则返回400错误。

2.3 注册中间件

打开 app/Http/Kernel.php 文件，在 $routeMiddleware 数组中注册中间件：

protected $routeMiddleware = [
    // ...
    'check.header' => \App\Http\Middleware\CheckHeader::class,
];

2.4 应用中间件

你可以在路由中应用中间件。例如，应用到 posts API路由：

Route::middleware('check.header')->apiResource('posts', PostController::class);

这样，每个 posts 路由都会经过 CheckHeader 中间件的验证。

3. 用户认证

Laravel提供了多种用户认证方式，包括基于会话的认证和API认证。在RESTful API中，通常使用API认证，如Token或JWT（JSON Web Token）。

3.1 使用Passport进行API认证

Laravel Passport是一个完整的OAuth2服务器实现，用于API认证。以下是使用Passport进行用户认证的步骤：

3.1.1 安装Passport

首先，安装Passport：

composer require laravel/passport

然后，运行迁移和安装Passport：

php artisan migrate
php artisan passport:install

3.1.2 配置Passport

打开 app/Models/User.php 文件，添加 HasApiTokens trait：

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;

    // 模型代码
}

打开 config/auth.php 文件，将API驱动器设置为 passport：

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

3.1.3 注册Passport中间件

打开 app/Http/Kernel.php 文件，在 $routeMiddleware 数组中注册Passport中间件：

protected $routeMiddleware = [
    // ...
    'auth:api' => \Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,
];

3.1.4 添加认证路由

打开 routes/api.php 文件，添加Passport的认证路由：

use Illuminate\Support\Facades\Route;

Route::post('login', 'AuthController@login');
Route::post('register', 'AuthController@register');

Route::middleware('auth:api')->group(function () {
    Route::get('user', 'AuthController@user');
    Route::post('logout', 'AuthController@logout');
});

3.1.5 实现认证控制器

创建一个 AuthController 控制器：

php artisan make:controller AuthController

打开 AuthController.php 文件，实现注册、登录和用户信息方法：

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Validator;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $validator = Validator::make($request->all(), [
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:8|confirmed',
        ]);

        if ($validator->fails()) {
            return response()->json($validator->errors(), 422);
        }

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => Hash::make($request->password),
        ]);

        $token = $user->createToken('LaravelAuthApp')->accessToken;

        return response()->json(['token' => $token], 201);
    }

    public function login(Request $request)
    {
        $credentials = $request->only('email', 'password');

        if (Auth::attempt($credentials)) {
            $user = Auth::user();
            $token = $user->createToken('LaravelAuthApp')->accessToken;

            return response()->json(['token' => $token], 200);
        } else {
            return response()->json(['error' => 'Unauthorized'], 401);
        }
    }

    public function user(Request $request)
    {
        return response()->json($request->user());
    }

    public function logout(Request $request)
    {
        $request->user()->token()->revoke();

        return response()->json(['message' => 'Successfully logged out']);
    }
}

4. 授权

授权用于控制用户对资源的访问权限。Laravel提供了基于策略和基于门的授权机制。

4.1 基于策略的授权

策略是与模型绑定的类，用于对模型实例进行授权。

4.1.1 创建策略

你可以使用 artisan 命令创建一个策略。例如，创建一个 PostPolicy 策略：

php artisan make:policy PostPolicy --model=Post

4.1.2 定义策略方法

打开 PostPolicy.php 文件，定义策略方法。例如，定义一个 update 方法：

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    public function update(User $user, Post $post)
    {
        return $user->id === $post->user_id;
    }
}

4.1.3 注册策略

打开 app/Providers/AuthServiceProvider.php 文件，在 policies 数组中注册策略：

namespace App\Providers;

use App\Models\Post;
use App\Policies\PostPolicy;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    protected $policies = [
        Post::class => PostPolicy::class,
    ];

    public function boot()
    {
        $this->registerPolicies();
    }
}

4.1.4 使用策略

在控制器或路由中使用策略进行授权：

use Illuminate\Support\Facades\Gate;

public function update(Request $request, Post $post)
{
    Gate::authorize('update', $post);

    // 更新操作
}

4.2 基于门的授权

门是与特定动作绑定的闭包，用于对动作进行授权。

4.2.1 定义门

你可以在 AuthServiceProvider 中定义门。例如，定义一个 update-post 门：

use Illuminate\Support\Facades\Gate;

public function boot()
{
    $this->registerPolicies();

    Gate::define('update-post', function ($user, $post) {
        return $user->id === $post->user_id;
    });
}

4.2.2 使用门

在控制器或路由中使用门进行授权：

use Illuminate\Support\Facades\Gate;

public function update(Request $request, Post $post)
{
    Gate::authorize('update-post', $post);

    // 更新操作
}

5. 处理错误和异常

处理错误和异常是构建可靠API的关键部分。Laravel提供了多种方式来处理错误和异常。

5.1 全局异常处理

打开 app/Exceptions/Handler.php 文件，你可以在 render 方法中处理全局异常：

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    public function render($request, Throwable $exception)
    {
        if ($request->is('api/*')) {
            return response()->json([
                'error' => 'Something went wrong!',
                'message' => $exception->getMessage(),
            ], 500);
        }

        return parent::render($request, $exception);
    }
}

5.2 自定义HTTP异常

你可以在 render 方法中处理特定的HTTP异常。例如，处理404错误：

public function render($request, Throwable $exception)
{
    if ($exception instanceof \Illuminate\Database\Eloquent\ModelNotFoundException) {
        return response()->json(['error' => 'Resource not found'], 404);
    }

    return parent::render($request, $exception);
}

6. API版本控制

API版本控制是为了在不影响现有用户的情况下发布新的API版本。你可以使用路由前缀来实现API版本控制。

6.1 定义版本化路由

在 routes/api.php 文件中定义版本化的路由：

Route::prefix('v1')->group(function () {
    Route::apiResource('posts', 'Api\V1\PostController');
});

Route::prefix('v2')->group(function () {
    Route::apiResource('posts', 'Api\V2\PostController');
});

6.2 创建版本化控制器

你可以为每个版本创建相应的控制器。例如，创建 V1 和 V2 版本的 PostController：

php artisan make:controller Api/V1/PostController --api
php artisan make:controller Api/V2/PostController --api

在不同版本的控制器中实现不同的逻辑。

总结

在本章中，我们详细介绍了如何使用Laravel构建RESTful API，包括API资源控制器的创建、路由的定义和实现，使用中间件进行请求过滤，使用Passport进行用户认证，基于策略和门的授权，以及处理错误和异常。此外，我们还介绍了API版本控制的方法。通过这些知识，你可以构建一个安全、可靠的RESTful API。

希望这篇文章能帮助你更好地理解Laravel的RESTful API构建，欢迎继续关注后续的教学文章！

---