Accept Header 区分 API 版本最符合 REST 原则，应优先于 X-API-Version 和 GET 参数，入口统一解析、白名单校验、废弃版本返回 410 且保持原错误格式。
用 Accept Header 区分版本最干净
PHP 本身不内置 API 版本路由，但客户端通过 Accept Header 带版本（如 application/vnd.myapp.v2+json）是最符合 REST 原则的做法。框架或原生代码都能轻松提取并分发。
常见错误是把版本硬塞进 URL（如 /api/v2/users），导致缓存、书签、文档和资源标识耦合，后续迁移成本高。
- 检查
$_SERVER['HTTP_ACCEPT']，用strpos()或正则匹配v1、v2 - 不要只匹配前缀，比如
v12可能误判为v1，建议用/v\d+(?![\d.])这类带边界限制的正则 - Laravel 用户可用
Route::versioned()（需扩展包），但原生 PHP 更推荐在中间件里统一解析并设置$version变量供后续逻辑使用
index.php 入口统一做版本分发
不建议每个控制器都重复判断版本，也不该让路由层承担语义解析。把版本识别逻辑收拢到入口或中间件，再交给对应版本的控制器处理，结构更清晰、测试更容易。
典型场景：同一资源（如用户列表）在 v1 返回扁平数组，v2 加入嵌套关系和元数据，业务逻辑差异大，但 URL 路径一致。
立即学习“PHP免费学习笔记（深入）”；
- 入口文件里根据
Accept或 fallback 的GET参数（如?version=v2）决定 require 哪个版本的 controller 文件 - 避免用
include动态拼路径（如"controllers/v{$v}/User.php"），易被路径遍历攻击；应白名单校验$v值是否为'v1'或'v2' - 如果用 Swoole 或 RoadRunner，注意
$_SERVER中 Header 键名可能为小写（如http_accept），需统一处理
Header 版本优先级必须明确
当同时存在 Accept、X-API-Version 和 URL 查询参数时，不定义优先级会导致行为不可预测，尤其在调试或代理转发时容易踩坑。
性能影响不大，但兼容性风险高：CDN 或网关可能 strip 自定义 Header，而 Accept 是标准字段，更可靠。
- 推荐顺序：
Accept>X-API-Version>GET version，且三者冲突时记录 warning 日志，不静默覆盖 - 不要在响应头里回写
X-API-Version: v2，除非客户端明确要求——这属于冗余信息，还可能误导前端缓存策略 - 若团队习惯用 Header，务必在 OpenAPI 文档中明确定义
X-API-Version的格式（如是否接受2、v2、2.1），否则前端传错格式就直接 fallback 到默认版
版本废弃不是删代码，而是拒绝请求
下线 v1 不等于删掉 v1/ 目录取代，而是返回 410 Gone 或带迁移提示的 301（仅限 URL 版本）。Header 方式更简单：检测到废弃版本，直接 http_response_code(410) 并输出 JSON 提示。
容易被忽略的是错误响应体格式——v1 已废弃，但它的错误结构（如 {"error": "xxx"}）可能和 v2（{"errors": [{...}]}）不兼容，客户端解析会崩。
- 废弃版本的响应体结构必须保持和它上线时完全一致，哪怕只是静态字符串
- 别在废弃逻辑里调用新版本的 validator 或 DB 层——v1 的字段约束可能更松，强行走 v2 验证会扩大失败范围
- 监控要单独埋点：统计
410请求量，确认下线节奏是否符合预期，而不是等客服反馈“接口突然不能用了”
