如何在Symfony中优雅地管理多版本API-php教程-PHP中文网

symfony api版本控制推荐用addprefix()批量挂载路径前缀（如/api/v1），配合requirements约束合法版本号（如v{version}），并用condition按accept头分流；弃用旧版时通过_defaults._deprecated触发弃用日志与426状态码。

如何在symfony中优雅地管理多版本api

用 `addPrefix()` 批量挂载版本路由前缀

URL路径前缀（如 /api/v1、/api/v2）是最直接、调试最方便的版本控制方式，Symfony 的 RouteCollection 原生支持它。关键不是手动给每个路由加前缀，而是用 addPrefix() 对整组路由统一处理：

在自定义路由加载器或 routes.yaml 中定义分组时，先创建独立的 RouteCollection 实例
调用 $v1Routes->addPrefix('/api/v1')，再把整个集合挂到主路由树上
避免在控制器注解里硬编码前缀（比如 @Route("/api/v1/users")），否则 v2 复制粘贴容易漏改
注意：前缀会作用于所有子路由，包括嵌套路由和通配符路径，所以 /users/{id} 会自动变成 /api/v1/users/{id}

用 `condition` 属性做请求头版本路由

当需要隐藏版本信息或兼容旧客户端（比如只允许 Accept: application/vnd.myapp.v2+json）时，condition 是更干净的选择。它不改变 URL 结构，只靠匹配逻辑分流：

Symfony Linux版

Symfony Linux版整理 Symfony CLI 5.17.1 官方下载入口和 Symfony 框架安装配置说明。

下载

在 routes.yaml 中为同一路径配置多个路由，用 condition 区分版本：

api_users_v1:
    path: /api/users
    controller: App\Controller\UserController::listV1
    condition: "request.headers.get('Accept') matches '/v1/'"

api_users_v2:
    path: /api/users
    controller: App\Controller\UserController::listV2
    condition: "request.headers.get('Accept') matches '/v2/'"

条件表达式必须是合法的 Symfony 表达式语言（ExpressionLanguage），不能写正则字面量，要用 matches 函数
注意执行顺序：路由匹配是按定义顺序从上到下扫描的，v1 写在前面但被 v2 条件误匹配，会导致 v1 永远不生效
调试时可临时加 dump(request.headers.get('Accept')) 确认实际传入值，避免空格或大小写导致匹配失败

别忽略 `requirements` 对版本号的约束

路径前缀法看似简单，但放任用户访问 /api/v999/users 会暴露无效端点。用 requirements 显式限定合法版本号，既能拦截非法请求，也能让 API 文档更准确：

在路由定义中加入版本号捕获和正则限制：

api_v1_users:
    path: /api/v1/users
    controller: App\Controller\UserController::listV1
    requirements:
        _method: GET

api_v2_users:
    path: /api/v{version}/users
    controller: App\Controller\UserController::listV2
    requirements:
        _method: GET

v{version} 中的是 Symfony 路由的“要求约束”，只接受 1 或 2；不匹配则整个路由跳过，交由下一个候选路由处理
不要用这种宽泛写法，否则 v123 也会被当作有效版本，后续控制器还得二次校验
这个约束也会影响生成的 URL（比如 $this->generateUrl('api_v2_users', ['version' => 3]) 会抛出 RouteNotFoundException），所以模板或测试里传参要严格对齐

版本升级时，`deprecations` 日志比文档更重要

当你准备弃用 v1 并引导用户迁移到 v2，光靠文档提醒远远不够。Symfony 提供了运行时提示机制，能在每次 v1 请求发生时记录弃用日志，甚至返回 HTTP 426 Upgrade Required：

在 v1 路由定义中加 defaults：

api_v1_users:
    path: /api/v1/users
    controller: App\Controller\UserController::listV1
    defaults:
        _deprecated: 'API v1 is deprecated, please use v2'
        _status_code: 426

_deprecated 会触发 trigger_error(..., E_USER_DEPRECATED)，被 Monolog 捕获并写入 deprecation.log
_status_code 只影响该路由响应状态码，不会自动加 Upgrade 响应头，需在控制器里手动设置：$response->headers->set('Upgrade', 'v2')
真正容易被忽略的是：这些配置只在 dev 环境默认启用，在 prod 环境需确保 php.ini 中 error_reporting 包含 E_USER_DEPRECATED，否则日志静默丢失