Symfony推荐URL路径前缀法管理API版本，如/api/v1，并辅以Accept-Version请求头匹配；避免使用查询参数（?v=2），因其破坏REST语义、无法被路由缓存识别且导致功能隔离失效。
Symfony API 版本管理没有“标准答案”，但有明确的推荐路径：优先用 URL 路径前缀，辅以 Accept-Version 请求头匹配；避免用查询参数（?v=2）做版本路由，它无法被 Symfony 的路由缓存机制有效识别，也破坏 REST 资源语义。
URL 路径前缀法：最稳、最易调试的实现
这是 Symfony 官方文档和 API Platform 默认采用的方式。核心是让每个版本拥有独立的路由集合，并通过 addPrefix() 统一注入路径前缀。
- 所有 v1 路由必须定义在独立的
RouteCollection实例中，再调用$v1Routes->addPrefix('/api/v1')，不能直接写new Route('/api/v1/users', ...)—— 否则无法复用路由组、条件、默认值等高级特性 - YAML 配置更常见，尤其在 API Platform 中：
api/config/routes/api_platform.yaml里可分别导入v1.yaml和v2.yaml，再各自配置prefix: '/api/v1' - 注意路由优先级：v1 和 v2 的路由集合添加到主集合时，顺序不重要；但若某条路由同时匹配
/api/v1/users和/api/v2/users，Symfony 会按定义顺序选择第一个命中项 —— 所以建议把更具体的版本放前面，或确保路径无重叠
Accept-Version 请求头匹配：适合客户端可控、URL 需统一的场景
当客户端能稳定发送 Accept-Version: v2 头（比如内部微服务调用），且你希望对外暴露同一 URL（如 /api/users）时，可用 condition 属性做运行时判断。
- condition 表达式必须是合法的 Symfony 表达式语言（ExpressionLanguage），例如：
request.headers.get('Accept-Version') matches '/^v2$/'—— 注意单引号包裹、正则需锚定（^v2$），否则可能误匹配v2.1 - 不要在 condition 中调用复杂 PHP 函数（如
version_compare()），它只支持表达式语言内置函数和简单方法链 - 这种写法会让路由匹配变慢（每次请求都要执行表达式解析），且无法被
router:match命令静态分析 —— 调试时容易卡住
为什么不用查询参数（?_version=v2）做路由分发
看似简单，但实际踩坑率极高：
- Symfony 路由器默认忽略查询参数，
/api/users?v=2和/api/users被视为同一 route，condition里读取request.query.get('_version')是可行的，但此时已失去“路由分发”意义，变成控制器内手动分支 - API Platform 的数据过滤、分页、序列化上下文等功能都基于路由匹配结果生成，查询参数版本会导致这些功能无法按版本隔离
- CDN、反向代理、浏览器缓存通常不区分查询参数，
/api/users?v=1和/api/users?v=2可能被缓存为同一个响应
真正难的不是写对某一条路由，而是让版本边界清晰地贯穿整个请求生命周期：从路由匹配、控制器执行、数据序列化（ApiPlatform\Serializer\ItemNormalizer 支持版本感知），到响应头（X-API-Version）输出。一旦路径前缀没对齐，后续所有环节都会被迫打补丁。
