README

Laravel API Evolution是一个基于API演进思想的API版本化库。它提供了一种在保持向后兼容的同时修改API的方法。

受Stripe的API版本化策略启发。用户在请求头中指定所需版本，请求和响应数据将被修改以匹配请求的版本。

安装

您可以通过composer安装此包

composer require ejunker/laravel-api-evolution

您可以使用以下命令运行安装命令

php artisan api-evolution:install

api-evolution:install 命令将创建 config/api-evolution.php 配置文件。

您需要将中间件添加到 app/Http/Kernel.php 中的 api 中间件组，或者添加到您想要的组/路由中。

'api' => [
    // \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
    \Ejunker\LaravelApiEvolution\ApiEvolutionMiddleware::class,
],

使用方法

您可以使用以下命令创建API迁移

php artisan make:api-migration FirstLastName

这将创建一个名为 app/Http/Migrations/FirstLastName.php 的文件，您可以对它进行编辑，以对请求和/或响应进行必要的更改。然后您需要将其添加到 config/api-evolution.php 文件中，以便在请求旧版本时运行。为特定版本列出的迁移是使其与上一版本匹配所需的迁移。

API迁移

每个API迁移文件都有一些属性和方法，您可以使用

routeNames - 一个数组，包含此迁移将为其运行的路由名称。您可以使用通配符，例如 api.v1.users.*
isApplicable() - 如果 routeNames 不能提供足够的灵活性，您可以使用此方法根据 Request 来确定迁移是否应该运行
migrateRequest() - 允许您修改 Request，使其与较新版本兼容
migrateResponse() - 允许您修改 Response，使其是请求的旧版本

除了 routeNames 和 isApplicable() 之外，您还可以在配置文件中指定迁移的路线名称。

'versions' => [
    '2022-10-10' => [
        new \App\Http\Migrations\FirstLastName(['api.v1.users.show']),
    ],

    '2022-10-05' => [
        // first version
    ],
],

绑定

虽然API迁移允许您修改 Request 和 Response，但有时使用完全不同的FormRequest、JsonResource或响应转换器可能更容易。在这些情况下，您可以使用 Bind 将不同版本绑定到容器中。

在 config/api-evolution.php

'versions' => [
    '2022-10-10' => [
        \App\Http\Migrations\FirstLastName::class
        new \Ejunker\LaravelApiEvolution\Bind(
            \App\Transformers\UserTransformer::class,
            \App\Transformers\UserTransformer_20221005::class,
        ),
    ],

    '2022-10-05' => [
        // first version
    ],
],

在这个例子中，如果用户请求了 2022-10-05 版本，则会应用 Bind，它会将旧版本的文件绑定到容器中，以便使用。如果用户请求最新版本 2022-10-10，则 Bind 不会运行，将使用文件的最新版本。

确定迁移是否活跃

如果您需要修改除了请求/响应之外的内容，例如根据版本修改SQL查询，则可以使用 ApiEvolution::isActive()。例如，要确定 FirstLastName 迁移是否活跃：ApiEvolution::isActive(FirstLastName::class)

响应头

响应中添加了几个头信息

API-Version - 请求的版本或如果没有请求特定版本，则为最新版本
API-Version-Latest - 如果请求的版本不是最新版本，则此头信息将被添加
已弃用 - 如果此端点有迁移或绑定正在运行，则此头信息将被添加以指示此端点有更新的版本

测试

composer test

变更日志

有关最近更改的详细信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

请查阅我们的安全策略了解如何报告安全漏洞。

致谢

此包基于以下项目

许可证

MIT许可证（MIT）。请参阅许可证文件了解更多信息。

ejunker / laravel-api-evolution

维护者

详细信息