Laravel 11 中的 API 版本控制

随着 Laravel 11 的发布，应用程序骨架被精简，去除了每个项目都不需要的额外文件。该更改的一部分是将除了 AppServiceProvider 之外的所有服务提供者从应用程序源代码中删除。

更新后的应用程序骨架的另一个部分是删除默认安装中的 API 路由。假设您计划将 API 添加到您的应用程序或使用 Laravel 专门编写 API，在这种情况下，您可以使用 Artisan 命令设置 api 中间件组和路由

php artisan install:api

install:api 会设置 api.php 路由文件（并配置它）、个人访问令牌的数据库迁移以及 Sanctum 配置文件。如果您不需要对 API 进行版本控制，则只需执行此操作即可。

#在单独的文件中对 API 进行版本控制

在 Laravel 中编写版本化 API 的一种常见方法是将路由分离到不同的文件中。这样做可以简化推理特定 API 版本的开销，并保持整洁。在 Laravel 10 或更早版本中，一种常见的方法是为 RouteServiceProvider 中的每个 API 版本添加额外的路由文件

$this->routes(function () {
    Route::middleware('api')
        ->prefix('api')
        ->group(base_path('routes/api.php'));
 
    Route::middleware('api')
        ->prefix('api/v1')
        ->group(base_path('routes/api_v1.php'));
 
    Route::middleware('api')
        ->prefix('api/v2')
        ->group(base_path('routes/api_v2.php'));
 
    Route::middleware('web')
        ->group(base_path('routes/web.php'));
});

在上面的示例中，routes/api.php 通常为 Laravel Sanctum 提供 /user 端点，其余的 API 路由则放置在相应的版本中。

#在 Laravel 11 中对 API 进行版本控制

随着路由引导从 RouteServiceProvider 转移到 bootstrap/app.php，您可以使用以下几种方法对 API 进行版本控制。

首先，让我们生成一些文件来演示路由设置

touch routes/api_v1.php
touch routes/api_v2.php
 
php artisan make:controller --api Api/V1/PostsController
php artisan make:controller --api Api/V2/PostsController

使用任何适合您的文件名约定和位置。

接下来，打开 routes/api.php 文件，并将以下行添加到文件末尾

Route::prefix('v1')->group(base_path('routes/api_v1.php'));
Route::prefix('v2')->group(base_path('routes/api_v2.php'));

上面的代码位于 api.php 中，这意味着我们已经在 api 路由前缀内工作，并使用 api 中间件组。

接下来，让我们添加每个 API 版本的示例路由，以便我们可以可视化每个版本的路由列表。

这是 api_v1.php 文件

<?php
 
use App\Http\Controllers\Api\V1\PostsController;
 
Route::apiResource('posts', PostsController::class);

以及 api_v2.php 文件

<?php
 
use App\Http\Controllers\Api\V2\PostsController;
 
Route::apiResource('posts', PostsController::class);

定义完路由文件后，运行 route:list，我们可以看到版本化路由！

专业提示： 您可以使用 --path 标志隔离版本化路由，从而可以轻松地专注于特定 API 版本

php artisan route:list --path=api/v1
php artisan route:list --path=api/v2

看看如果您只输出 api/v2 的路由，它看起来多么整洁

#在 App 引导文件中定义版本化路由

我见过的另一种方法是在 bootstrap/app.php 文件中使用 then: 参数（接受 Closure）定义额外的 API 路由

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        then: function () {
            Route::middleware('api')
                ->prefix('api/v1')
                ->group(base_path('routes/api/api_v1.php'));
 
            Route::middleware('api')
                ->prefix('api/v2')
                ->group(base_path('routes/api/api_v2.php'));
        }
    )
    // ...
;

我更喜欢将额外的路由文件直接添加到 routes/api.php 中，但这是一种可行的替代方法。在引导文件中定义路由时，这些组未配置为使用 api 中间件组。请确保在这些路由中包含 api 中间件组！