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對於版本 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-prefix ( V2 )。

請注意，您當然可以在內部跟蹤次要版本（例如在 SCM 中），但開發人員無需更改他們所有的 API 調用只是為了從您發布的那個小錯誤修復中受益。 無論如何，如果您將較新的次要版本以及他們提供的錯誤修復或增強功能（博客、時事通訊等）通知您的客戶，那當然很好。

讓我補充一點，我不知道任何帶有次要 API-URL 前綴的 RESTful API，所以我想這是一種很常見的做法。

Answer 2

您不能使用點，而是使用下划線。

但...

一個精心設計的api必須在次要版本之間有BC，所以你不需要為次要更新創建新版本，而是需要編寫兼容的代碼。

Answer 3

我創建了一個簡單的 Laravel 包來支持 Laravel API 版本控制，它為路由添加了回退功能。 我個人很久以前就需要這個，但沒有意識到用這么小的包裝就能實現。

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