php - Laravel RESTful API 版本控制设计

Question

我是 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 :

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 和 http://..../api/v2对于版本 2。这很简单。

我的问题是:
如果我正在构建 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 版本，因为这不是重大升级。

Answer 1

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

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

示例

1. 您从 v1.0 开始
2. 您做了一点改动(例如 git-tag v1.1)，但不会对您的 api 带来重大更改。开发人员是否需要在他们的代码中做任何其他事情？不，那里没有。所以你可以安全地让 URI-Prefix 保持在 V1，这样调用你的 api 的开发人员就不需要更改他们调用你的 API 的所有代码(因此，自动受益于新的次要版本).也许您只是修复了一个错误，这使得他们的代码按预期运行，或者您发布了一项新功能，该功能本身不会破坏现有的功能调用。
3. 您的应用不断发展，您发布了重新设计的 API 新版本，其中包含重大更改。在这种情况下，您发布了一个新的 API-URI 前缀 (V2)。

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

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