最稳妥的PHP RESTful API版本控制方式是用Accept请求头（如application/vnd.myapp.v2+json），而非URL路径或查询参数；因路径式版本破坏缓存共享、污染文档与路由、违背REST资源语义。
PHP RESTful API 的版本控制没有标准答案，但最稳妥、最易维护的方式是用请求头 Accept 携带版本信息（如 application/vnd.myapp.v2+json），而不是放在 URL 路径或查询参数里。
为什么别把版本塞进 URL 路径（/v1/users）
路径式版本（如 /v1/users、/v2/users）看似直观，实际会带来三个硬伤：
- 缓存系统（CDN、代理、浏览器）把不同路径视为完全不同的资源，无法共享缓存逻辑，v1 和 v2 的相同响应可能重复计算、重复存储
- API 文档、SDK 生成、客户端路由绑定全部被版本号“污染”，升级 v2 就得批量改所有调用点和文档链接
- 语义错误：REST 强调 URI 表达资源，
/v1/users暗示“v1 版本的 users 是一种独立资源”，而实际它只是同一资源的不同表现形式
怎么用 Accept 头实现版本路由（Slim/FastRoute/Laravel 都适用）
核心思路是解析请求头中的 Accept，提取版本号，再交由对应控制器处理。以原生 PSR-7 + FastRoute 为例：
// 解析 Accept 头获取版本
$accept = $request->getHeaderLine('Accept');
$version = 'v1'; // 默认版本
if (preg_match('/v(\d+)/', $accept, $matches)) {
$version = 'v' . $matches[1];
}
// 根据版本分发到不同 handler
switch ($version) {
case 'v2':
return $handlerV2($request);
default:
return $handlerV1($request);
}
关键点：
立即学习“PHP免费学习笔记（深入）”；
- 必须设置合理的默认版本（
v1），否则缺失Accept头时直接报错 - 正则要宽松：
v\d+比v1或v2更可持续，避免每新增一版就改匹配逻辑 - 不要在
Accept中混用多个 vendor type，如application/json,application/vnd.myapp.v2+json—— 实际解析应取第一个匹配项，或按 RFC 7231 的 quality factor 排序
如何让 Laravel 的 Resource 和 Validation 也按版本分支
Laravel 自身不内置多版本支持，需手动隔离逻辑层。重点不是改路由，而是拆开响应构造与校验规则：
- Resource 类按版本命名：创建
App\Http\Resources\V1\UserResource和App\Http\Resources\V2\UserResource，各自定义toArray()输出结构 - Request 验证类同样分版本：如
App\Http\Requests\V2\StoreUserRequest，重写rules()返回适配 v2 的字段规则（比如 v2 新增timezone必填，v1 不校验） - 控制器中根据版本实例化对应类：
new V2\UserResource($user)，而非硬编码UserResource::make(...) - 切忌在同一个 Resource 里用
if ($version === 'v2')分支——这会让测试变难、违反单一职责
兼容性陷阱：Content-Type 和 Accept 的组合容易翻车
有些客户端误设 Content-Type: application/vnd.myapp.v2+json，以为能触发版本路由，但这是错的 —— Content-Type 描述请求体格式，Accept 才声明期望响应格式。
更隐蔽的问题是：当客户端同时发送 Accept: application/json 和 Accept: application/vnd.myapp.v2+json 时，没做 quality factor 解析的代码可能取错顺序。RFC 规定应优先选 q 值高的，例如：
Accept: application/json;q=0.9, application/vnd.myapp.v2+json;q=1.0
此时必须解析 q 值，不能简单取第一个匹配项。生产环境建议用现成库如 willdurand/negotiation 处理，它已覆盖所有边界情况。
版本控制真正的难点不在路由分发，而在于如何让数据库迁移、事件监听、队列任务、第三方回调这些后端环节也感知版本差异 —— 这些往往被忽略，直到 v2 上线后发现老订单通知模板被新逻辑覆盖才踩坑。
