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

Question

我正在使用 Laravel 创建一个版本化的 JSON API，然后我将使用 AngularJS 访问它来填充我的页面。目前我正在使用版本化 Controller 返回 JSON(最终我计划改为实现依赖注入(inject)和版本化存储库)。

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

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

Answer 1

API 应该只在外部使用主要版本。遵循最佳实践 semantic versioning ，当您向项目中引入向后不兼容的更改时，主要版本会发生变化。

如果您只是添加功能，或以向后兼容的方式修改现有功能，那么您只需这样做，您现有的消费者不会受到影响(不过，他们可以根据需要使用新的更改)。您的 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 都应该只反射(reflect)主要版本(例如“v1”)，并且您应该确保您永远不会破坏主要版本中的向后兼容性。