Laravel RESTful API 版本控制设计

Posted 2023-03-15

【中文标题】Laravel RESTful API 版本控制设计

【英文标题】：Laravel RESTful API versioning design

【发布时间】：2015-07-26 05:11:45

【问题描述】：

我是 Laravel（4 和 5）的新手，最近一直在研究 RESTful API。 为了允许 API 的多个版本，我使用 URL 来确定版本。

似乎大多数人都在遵循这种方法： How to organize different versioned REST API controllers in Laravel 4?

文件夹结构：

/app
  /controllers
    /Api
      /v1
        /UserController.php
      /v2
        /UserController.php

在UserController.php 文件中，我相应地设置了命名空间：

namespace Api\v1;

或

namespace Api\v2;

在路线中：

Route::group(['prefix' => 'api/v1'], function () 
  Route::get('user',      'Api\v1\UserController@index');
  Route::get('user/id', 'Api\v1\UserController@show');
);

Route::group(['prefix' => 'api/v2'], function () 
  Route::get('user',      'Api\v2\UserController@index');
  Route::get('user/id', 'Api\v2\UserController@show');
);

版本 1 的 URL 将是 http://..../api/v1，版本 2 的 URL 将是 http://..../api/v2。这很简单。

我的问题是： 如果我正在构建 API 的小升级，比如 v1.1，我该如何组织我的文件夹结构？ 我的想法如下，因为 dot 是文件夹的有效名称，这应该还可以吗？

/app
  /controllers
    /Api
      /v1
        /UserController.php
      /v1.1
        /UserController.php
      /v1.2
        /UserController.php
      /v2
        /UserController.php

还有，命名空间应该怎么写？没有这样的命名空间

namespace Api\v1.1;

我可以参考使用“点”的命名约定吗？

注意：我不想将其称为 v2 版本，因为这不是重大升级。

【问题讨论】：

如果你将使用 apiResource 路由，你应该使用“name”属性。 ->name('v2') 或 'name' => 'v2' 靠近前缀。

【参考方案1】：

IMO，次要升级不应发布对 API 的重大更改。所以我的建议是坚持使用整数版本的 API。增强没有问题，但现有端点应该像往常一样运行。

这样，您的 API 版本将与路由前缀和命名空间以及测试同步。

示例

从 v1.0 开始 您进行了一点更改（例如 git-tag v1.1），但不会对您的 api 带来重大更改。开发人员是否需要在他们的代码中做其他事情？不，那里没有。因此，您可以放心地将 URI-Prefix 保留在 V1，以便调用您的 api 的开发人员无需更改调用您的 API 的所有代码（因此，自动受益于新的次要版本）。也许您只是修复了一个错误，使他们的代码按预期运行，或者您发布了一个新功能，该功能本身不会破坏现有的功能调用。 您的应用程序不断增长，并且您发布了重新设计的新 API 版本，其中包含重大更改。在这种情况下，您发布一个新的 API-URI-prefix (V2)。

请注意，您当然可以在内部跟踪次要版本（例如在 SCM 中），但开发人员无需更改所有 API 调用即可从您发布的小错误修复中受益。无论如何，如果您将较新的次要版本以及他们提供的错误修复或增强功能（博客、新闻通讯等）通知您的客户，那当然很好。

让我补充一下，我不知道任何带有次要 API-URL 前缀的 RESTful API，所以我想这是一种很常见的做法。

【讨论】：

您好，喷嘴人，您的观点与 aeryaguzov 不同。你的意思是它应该是 v2 而不是 v1.1 ，并且不对现有的 v1 代码进行任何更改？

感谢您的回复！我编辑了答案。我希望我的观点更清楚一点。

我也在考虑实现 API 版本。如果对 v1、v2 等使用此版本控制结构...在运行 composer 并执行自动加载转储时会出现任何问题吗？

我不明白你的意思。也许这符合如此独立的问题。

@JBMcClure jetamn 想说的是，对于 1.1 到 1.2 之类的版本，它们可能不会有重大变化，而这可以通过仅在该特定 API 中使用 if else 来完成。

【参考方案2】：

您不能使用点，而是使用下划线。

但是……

一个设计好的api必须在小版本之间有BC，所以小更新不需要创建新版本，而是需要编写兼容的代码。

【讨论】：

明白你的意思。这意味着我应该向 v1 控制器扩展或添加新代码。

【参考方案3】：

我创建了一个简单的 Laravel 包来支持 Laravel API 版本控制 它为路由添加了回退功能。 我个人很久以前就需要这个，但没有意识到用这么小的包就能实现。

https://github.com/mbpcoder/laravel-api-versioning