Add explicit @version special route token support for API major versioning within a single module
还没有人认领这个 Issue。
评估
调研方向
首先跟踪 src/Router/PatternCompiler.php、src/Router/RouteBuilder.php、src/Router/RouteDispatcher.php、src/Router/MatchedRoute.php 和 src/Http/Traits/Request/Route.php 中对 @version 的处理；先检查 DemoApi 模板以及依赖项 #546 和 #548。完成的标准是受支持的已配置 major version 相匹配、version-aware controller 能在一个 module 内解析、version 值保留在 route context 中，并且测试覆盖 matching 和 resolution。
由索引模型根据 Issue 内容生成。
描述
Summary
Add API major versioning support based on the explicit special route token:
@version
so a single API module can expose multiple major API versions concurrently, such as:
/api/v1/posts/api/v2/posts
without treating each version as a separate module.
Why
Quantum needs a clean framework-level API versioning model.
The intended ownership model is:
- one logical
Apimodule - multiple supported API major versions inside that module
With the special route token foundation in place, versioning can be expressed explicitly in route patterns instead of relying on:
- duplicated route trees
- positional URL conventions
- separate modules per version
- hidden dispatch tricks
Goal
Allow routes to explicitly declare API major version position using:
@version
and let the framework treat the matched version as framework-owned route context for version-aware controller resolution.
Proposed Direction
API routes that are versioned should explicitly include:
@version
Examples:
$route->get('@version/posts', 'PostController', 'posts');
$route->get('@version/post/[uuid=:any]', 'PostController', 'post');
$route->post('@version/signin', 'AuthController', 'signin');
This should allow URLs such as:
/api/v1/posts/api/v2/posts/api/v1/signin
depending on module prefix configuration and supported versions.
Config Direction
Supported API versions should be declared in module config.
A likely shape is:
'Api' => [
'prefix' => 'api',
'enabled' => true,
'versions' => ['v1', 'v2'],
]
The route token:
@version
should then match only those configured supported versions.
Controller Resolution Direction
Matched version values should be used by the framework to resolve version-specific controllers inside the same module.
Examples:
-
v1+PostController
resolves to:{ModuleBaseNamespace}\Api\Controllers\V1\PostController
-
v2+PostController
resolves to:{ModuleBaseNamespace}\Api\Controllers\V2\PostController
This allows one route shape to map to different major-version controller implementations inside a single module.
Important behavior
The resolved version should be:
- matched through the
@versiontoken - validated against configured supported versions
- made available to framework internals as version route context
- used for version-aware controller resolution
- kept distinct from ordinary controller action parameters by default
Scope
This ticket should focus on major API versioning only.
It should not introduce:
- minor or patch versioning in the URL
- header-based minor/patch runtime negotiation
- separate modules per API version
Minor and patch changes should remain outside the first implementation scope.
Acceptance Criteria
- routes can explicitly declare API version position using
@version - matched
@versionvalues are validated against configured supported versions - a single API module can expose multiple supported major versions concurrently
- matched version values are used for version-aware controller resolution within the same module
- routed version values do not become ordinary positional controller action parameters by default
- tests cover
@versionroute matching and version-aware controller resolution behavior - templates and examples can be updated to use
@versionwhere appropriate
Notes
Relevant code:
src/Router/PatternCompiler.phpsrc/Router/RouteBuilder.phpsrc/Router/RouteDispatcher.phpsrc/Router/MatchedRoute.phpsrc/Http/Traits/Request/Route.phpsrc/Module/Templates/DemoApi
This ticket depends on:
- 主要语言
- PHP
- 星标
- 36
- 派生
- 22
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
quantum-php/framework 的其他 Issue
-
routing testing
难度 2/5 1-3 小时 新手友好度 76/100
quantum-php/framework#547 ·
-
view
难度 1/5 1 小时以内 新手友好度 75/100
quantum-php/framework#542 ·
-
enhancement http
难度 5/5 一周以上 新手友好度 35/100
quantum-php/framework#565 · 1 条评论 ·
-
components view
难度 5/5 一周以上 新手友好度 42/100
quantum-php/framework#551 ·
-
lang routing
难度 5/5 一周以上 新手友好度 45/100
quantum-php/framework#549 ·
查看 quantum-php/framework 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 85/100
维护者通常 3 天内回复
-
难度 1/5 1 小时以内 新手友好度 90/100
维护者通常 1 天内回复
-
sync-en
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
sync-en
难度 2/5 1-2 天 新手友好度 84/100
维护者通常 2 天内回复
-
feature-request needs-triage
难度 2/5 1-3 小时 新手友好度 72/100
aws/aws-sdk-php#3365 ·
维护者通常 1 天内回复