Laravel RESTful API 版本控制设计
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/30239823/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Laravel RESTful API versioning design
提问by Sam Wong
I am new to Laravel (4 and 5) and recently I am working on a RESTful API. In order to allow multiple version of the API, I am using URL to determine the version.
我是 Laravel 的新手（4 和 5），最近我正在研究 RESTful API。为了允许多个版本的 API，我使用 URL 来确定版本。
I read follow this post and it seem most people following this approach: How to organize different versioned REST API controllers in Laravel 4?
我阅读了这篇文章，似乎大多数人都遵循这种方法： 如何在 Laravel 4 中组织不同版本的 REST API 控制器？
Folders structures:
文件夹结构：
/app
/controllers
/Api
/v1
/UserController.php
/v2
/UserController.php
And in UserController.php files I set the namespace accordingly:
在 UserController.php 文件中，我相应地设置了命名空间：
namespace Api\v1;
or
或者
namespace Api\v2;
and in routes:
并在路线中：
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 will be simple http://..../api/v1for version 1 and http://..../api/v2for version. This is straight forward.
URL 将是简单的http://..../api/v1版本 1 和http://..../api/v2版本。这是直接的。
My questions is:What if I am building minor upgrade of api, say v1.1 , how do I organize my folder structure? My thought was this and it should be still fine as dot is valid name of folders?
我的问题是：如果我正在构建 api 的小升级，比如 v1.1 ，我该如何组织我的文件夹结构？我的想法是这样，它应该仍然没问题，因为点是文件夹的有效名称？
/app
/controllers
/Api
/v1
/UserController.php
/v1.1
/UserController.php
/v1.2
/UserController.php
/v2
/UserController.php
Also, how should I write the namespace?This is no namespace like this
另外，我应该如何编写命名空间？这不是这样的命名空间
namespace Api\v1.1;
Is there naming convention I can refer to for using "dot" ?
我可以参考使用“点”的命名约定吗？
Note: I do not want to call it as version v2 because this is not a major upgrade.
注意：我不想将其称为版本 v2，因为这不是重大升级。
采纳答案by nozzleman
IMO, minor upgrades should not publish breaking changes to an API. So my suggestion is to stick to integer versioned APIs. Enhancements are no problems, but existing endpoints should behave as usual.
IMO，小升级不应发布对 API 的重大更改。所以我的建议是坚持使用整数版本的 API。增强没有问题，但现有端点应该像往常一样工作。
This way your API-Versions would be in sync with the route-prefixes and the namespaces as well as the tests.
这样您的 API 版本将与路由前缀、命名空间以及测试同步。
EXAMPLE
例子
- You begin with v1.0
- You make a little change (eg. git-tag v1.1) which does not bring breaking changes to your api. Is there a need for developers to do anything else in their code? No, there is not. So you can safeley let the URI-Prefix stay at
V1, so that developers calling your api do not need to change all their code which is calling your API (and therefore, automatically benefit from the new minor version). Maybe you just fixed a bug, which makes their code behave just as expected or you published a new feature, which by its self does not break existing feature-calls. - Your App grows and you publish new redesigned version of you API which contains breaking changes. In this case, you publish a new API-URI-prefix (
V2).
- 你从 v1.0 开始
- 您进行了一些更改（例如 git-tag v1.1），它不会对您的 api 带来重大更改。开发人员是否需要在他们的代码中做其他事情？不，那里没有。因此，您可以安全地让 URI-Prefix 保持在
V1，以便调用您的 api 的开发人员无需更改调用您的 API 的所有代码（因此，自动受益于新的次要版本）。也许你只是修复了一个错误，这使得他们的代码表现得像预期的那样，或者你发布了一个新功能，它本身不会破坏现有的功能调用。 - 您的应用程序增长，您发布了包含重大更改的 API 的重新设计的新版本。在这种情况下，您发布一个新的 API-URI-prefix (
V2)。
Be aware that you can of course keep track of the minor versions internally (e.g in SCM), but there should be no need for developers to change all of their API-Calls just to benefit from that little bugfix you published. Anyways, it is nice of course if you notify your clients of the newer minor versions and the bugfixes or enhancements they offer (blog, newsletter, ..)
请注意，您当然可以在内部跟踪次要版本（例如在 SCM 中），但开发人员无需更改他们所有的 API 调用只是为了从您发布的那个小错误修复中受益。无论如何，如果您将较新的次要版本以及他们提供的错误修复或增强功能（博客、时事通讯等）通知您的客户，那当然很好。
Let me add, that i am not aware of any RESTful APIs with minor API-URL-prefixes, so i guess this is quite a common practice.
让我补充一点，我不知道任何带有次要 API-URL 前缀的 RESTful API，所以我想这是一种很常见的做法。
回答by aeryaguzov
You can not use dots, use underscores instead.
您不能使用点，而是使用下划线。
But...
但...
A well-designed api must have BC between minor versions, so you do not need to create new version for minor update, instead you need to write compatible code.
一个精心设计的api必须在次要版本之间有BC，所以你不需要为次要更新创建新版本，而是需要编写兼容的代码。
