README

此包已 功能锁定

随着PHP、Laravel及其包社区的最新发展，管理版本化API的路由已经变得前所未有的简单。

我们发现了一些更好的方法，可以在更简洁的方式下完成这个包的功能。我们建议您查看 spatie/laravel-route-attributes 或 spatie/laravel-route-discovery。

尽管如此，我们仍将继续提供支持，直到任何重大破坏。

一个简单的Laravel包，用于简单的API版本管理。

Lapiv简单地代表（L）aravel（API）（V）ersioning。

安装

您可以通过composer安装此包

composer require juliomotol/lapiv

配置

如果您想更改配置，可以使用以下命令发布配置文件：

php artisan vendor:publish --provider="JulioMotol\Lapiv\LapivServiceProvider"

设置

现在是最有趣的部分，我们将向您介绍如何设置版本化控制器。

FooV1Controller.php

这与您的标准控制器非常相似。这里实际上没有什么特别之处。所有操作方法都必须在这里声明，例如 index、create、show 等。

namespace App\Http\Controllers\Api\Foo;

use App\Http\Controllers\Controller;

class FooV1Controller extends Controller
{
    public function index()
    {
        return response()->json(['message' => 'This is Foo V1']);
    }
}

FooGatewayController.php

现在到了精彩的部分。这个控制器 必须 继承 \JulioMotol\Lapiv\GatewayController 才能使整个系统正常工作。这将负责根据请求的版本分发请求。让我们看看里面。

namespace App\Http\Controllers\Api\Foo;

use JulioMotol\Lapiv\GatewayController;

class FooGatewayController extends GatewayController
{
    protected array $apiControllers = [
        FooV1Controller::class, // The first version of you API endpoint.
        // Preceeding version implementations...
    ];
}

$apiControllers 的顺序至关重要。首先声明的控制器将是我们的 v1，然后是 v2，依此类推。

路由

有了这些准备好的控制器，让我们创建我们的路由。转到 routes/api.php。

/**
 * Registers a versioned API endpoint.
 *
 * Router::lapiv($callback = null)
 *
 * @param $callback
 */
Route::lapiv(function () {
    Route::get('/foo', [FooGatewayController::class, 'index']);
    Route::get('/bar', [BarGatewayController::class, 'index']);
});

注意我们没有指向 [FooV1Controller::class, 'index']。正如我们所说的，FooGatewayController 将做大部分繁重的工作，所以我们只需调用它即可。

当您运行 php artisan route:list 时，您应该看到这个。

现在，当我们尝试访问 /api/v1/foo 时，它应该由 FooV1Controller 处理。

升级版本

当您准备好将API版本升级到v2时，只需添加一个新的 FooV2Controller，并别忘了将其添加到 FooGatewayController 的 $apiControllers 中。

版本化方法

此包支持两种API版本化方法，uri 和 query_string。

uri 方法

这是版本化方法的默认值。在这里，API版本将在uri路径中声明（例如 example.com/api/v1/foo）。

在配置中，您可以更改uri的前缀。

"methods" => [
    "uri" => [
        "prefix" => '/version-{version}' // will generate `example.com/api/version-1/foo`
    ]
]

别忘了在前缀中添加 version 参数。

query_string 方法

在这里，API版本将在查询字符串中声明（例如 example.com/api/foo?v=1）。

在配置中，您可以更改查询字符串的键。

"methods" => [
    "query_string" => [
        "key" => 'version' // will accept `example.com/api/foo?version=1`
    ]
]

想处理自己的版本化方法吗？

您可以通过扩展 JulioMotol\Lapiv\Drivers\BaseDriver 来定义您想要如何处理API的版本化。

use JulioMotol\Lapiv\Drivers\BaseDriver;
use Illuminate\Support\Facades\Request;

class HeaderDriver extends BaseDriver
{
    public function getVersion(): string|int
    {
        $headerValue = Request::header($methodOptions['key']) ?? null;
        $matches = [];

        preg_match('/application\/vnd\.my_application\.v(\d*)\+json/', $headerValue, $matches);

        return $matches[1] ?? null;
    }
}

您还可以通过在 BaseDriver 中覆盖 routeGroup() 方法来处理路由。

然后，在您的 AppServiceProvider::boot() 中添加您的新API驱动程序。

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        ApiVersioningManager::extend('header', fn () => new HeaderDriver());
    }
}

最后，在 config/lapiv.php 中使用您的新驱动程序。

    'default' => 'header', // the value here will be the first parameter you've set in ApiVersioningManager::extend()

变更日志

请参阅CHANGELOG以获取更多信息，了解最近有哪些变化。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件julio.motol89@gmail.com联系，而不是使用问题跟踪器。

致谢

• Julio Motol
• 所有贡献者

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

Laravel软件包模板

此软件包是使用Laravel软件包模板生成的。