用于 API 版本控制的 PHP 命名空间约定？

Question

我正在使用 Laravel 创建一个版本化的 JSON API，然后我将使用 AngularJS 访问它以填充我的页面。目前我正在使用版本控制器返回 JSON（最终我计划实现依赖注入和版本化存储库）。

我试图以这种格式命名我的控制器，App\Controllers\API\v1.0但是当我在浏览器中访问 localhost:800/api/1.0/companies 时，返回 JSON，我收到通知Class App\Controllers\API\v1.0\CompaniesController does not exist 。我猜这是因为.被解释为反斜杠之一？我可以通过将命名空间更改为App\Controllers\API\v1or来使应用程序功能App\Controllers\API\v1\v0，但前者不允许正确的版本控制，而后者似乎有点......不雅。

我应该为我的命名空间使用什么约定来充分版本我的 API？任何意见，将不胜感激！:)

Answer 1

API 应该只在外部使用主要版本。遵循最佳实践语义版本控制，当您向项目引入向后不兼容的更改时，主要版本会更改。

如果您只是添加功能或以向后兼容的方式修改现有功能，那么您只需这样做，您现有的消费者不会受到影响（不过，如果他们愿意，他们可以使用新的更改）。您的 API 可以在内部将版本从 1.0.0 更改为 1.1.0 ，但向您的消费者公开的版本仍然只是“v1”。

如果您只是修补错误，则同样适用。内部从 1.0.1 更改为 1.0.2 ，但 API 应保持在“v1”。

现在，如果您重命名/删除资源，或进行其他一些会破坏现有客户端的剧烈更改，您的内部版本可能会从 1.2.0 变为 2.0.0，因为破坏向后兼容性需要进行主要版本更改。因此，新的主要版本必须作为“v2”公开给 API 的使用者。

因此，与此保持一致，您的命名空间和 URL 都应仅反映主要版本（例如“v1”），并且您应确保永远不会破坏主要版本中的向后兼容性。