Laravel RESTful API版本设计

Question

我是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将是简单的http://..../api/v1 1版和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,因为这不是主要升级.

Answer 1

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

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

例

1. 你从v1.0开始
2. 你做了一点改动(例如git-tag v1.1),这不会给你的api带来重大变化.开发人员是否需要在代码中执行任何其他操作？不,那里没有.因此,您可以安全地让URI-Prefix保持不变V1,以便调用您的api的开发人员无需更改调用您的API的所有代码(因此,自动受益于新的次要版本).也许你刚刚修复了一个错误,这使得他们的代码表现得像预期的那样,或者你发布了一个新功能,它本身不会破坏现有的功能调用.
3. 您的应用程序不断增长,并且您发布了包含重大更改的新重新设计的API版本.在这种情况下,您发布一个新的API-URI-prefix(V2).

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

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

Answer 2

你不能使用点,而是使用下划线.

但...

精心设计的api必须在次要版本之间具有BC,因此您不需要为次要更新创建新版本,而是需要编写兼容代码.