Laravel RESTful API 版本控制设计

2022-08-30 10:45:37

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

似乎大多数人都遵循这种方法:如何在Laravel 4中组织不同版本的REST API控制器?

文件夹结构:

/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');
});

该 URL 将仅用于版本 1 和版本 2。这很简单。http://..../api/v1http://..../api/v2

我的问题是:
如果我正在构建API的次要升级,比如v1.1,我该如何组织我的文件夹结构?
我的想法如下,这应该仍然很好,因为点是文件夹的有效名称吗?

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

另外,我应该如何编写命名空间?没有这样的命名空间

namespace Api\v1.1;

有没有一个命名约定,我可以参考使用“点”?

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


答案 1

IMO,次要升级不应发布对 API 的重大更改。所以我的建议是坚持使用整数版本化的API。增强功能没有问题,但现有终结点应照常运行。

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

  1. 从 v1.0 开始
  2. 您进行了一些更改(例如 git-tag v1.1),这不会对 API 带来重大更改。开发人员是否需要在他们的代码中做任何其他事情?没有。因此,您可以安全地让 URI 前缀保留为 ,以便调用 API 的开发人员无需更改调用 API 的所有代码(因此,自动从新的次要版本中受益)。也许你刚刚修复了一个错误,这使得他们的代码表现得像预期的那样,或者你发布了一个新功能,它本身不会破坏现有的功能调用。V1
  3. 你的应用增长,你发布了新的重新设计版本的 API,其中包含重大更改。在这种情况下,您将发布一个新的 API-URI 前缀 ()。V2

请注意,您当然可以在内部跟踪次要版本(例如在SCM中),但是开发人员不需要仅仅为了从您发布的那个小错误修复中受益而更改所有API调用。无论如何,如果您通知您的客户较新的次要版本以及他们提供的错误修复或增强功能(博客,新闻通讯,..),这当然很好。

让我补充一点,我不知道任何带有次要API-URL前缀的RESTful API,所以我想这是一种非常普遍的做法。


答案 2

你不能使用点,而要用下划线。

但。。。

设计良好的 API 必须在次要版本之间具有 BC,因此您无需为次要更新创建新版本,而是需要编写兼容的代码。


推荐