结论：别用url路径硬编码版本，优先用accept请求头（如accept: application/vnd.myapp.v2+json）；若需兼容老客户端，再以url版本作降级，且必须通过中间件统一解析并明确优先级（accept > x-api-version > ?version > 路径版本）。
直接说结论：别用 URL 路径硬编码版本（如 /api/v2/users），优先用 Accept 请求头（如 Accept: application/vnd.myapp.v2+json）；若必须支持老客户端，再用 URL 版本作降级，且两者必须通过中间件统一解析、明确优先级。
为什么 Accept 头比 URL 路径更可靠
URL 里的 v1 看起来直观，但会污染资源标识——/api/v1/users 和 /api/v2/users 在 HTTP 语义上是两个不同资源，导致缓存失效、CDN 配置复杂、OpenAPI 文档难维护。而 Accept 是标准 HTTP 头，网关、CDN、浏览器都认，且不改变 URI 本身。
常见错误现象：
- 客户端发
Accept: application/vnd.myapp.v12+json，正则只写/v\d+/，结果误判成 v1 - 没处理大小写，
accept（小写）在 Swoole 或 Nginx + FastCGI 下可能变成$_SERVER['HTTP_ACCEPT']或$_SERVER['http_accept'] - 每次请求都
preg_match()解析，没缓存结果，QPS 上万时 CPU 明显抖动
实操建议：
- 用带边界的正则：
/application\/vnd\.myapp\.v(\d+)(?![\d.])\+json/ - 统一从
$_SERVER提取，兼容大小写：array_change_key_case($_SERVER)后取['http_accept'] - 解析后立刻存入请求上下文，如
$request->attributes->set('api_version', 'v2')，后续控制器直接读，不重复解析
URL 版本怎么配才不翻车
ThinkPHP/Laravel 等框架里写一堆 Route::group(['prefix' => 'v1']) 是自找麻烦——v3 一来就得复制整套路由+命名空间，测试用例全重写。
正确做法是把版本当变量提取，不是当静态前缀：
- ThinkPHP：用
Route::rule(':version/user/:id', 'api.User/read')->pattern(['version' => 'v[12]'])，:version必须加pattern限制，否则匹配任意字符串 - Laravel：别用多个
prefix分组，改用Route::middleware(ParseVersion::class)->group(...)，中间件里从$request->route('version')取值 - 原生 PHP：
$parts = explode('/', parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)); $version = $parts[2] ?? null;，但必须校验$version === 'v1' || $version === 'v2'，不能直接拼类名
关键点：所有版本最终调用同一控制器，只是传入不同 $version 参数，业务逻辑用策略类隔离，比如 UserResponseV1Strategy 和 UserResponseV2Strategy 实现同一接口。
Header 和 URL 同时存在时以谁为准
框架不会自动协商——/api/v1/users 加 Accept: v2，不定义规则就等于没定义行为。线上出问题往往就卡在这儿。
必须显式声明优先级并记录日志：
- 推荐顺序：
Accept > X-API-Version > ?version=v2 > 路径中的 v2 - 冲突时写 warning 日志，例如：
["version_conflict", "url=v1", "header=v2", "client_ip" => $_SERVER['REMOTE_ADDR']] - 绝对不要静默覆盖：前端以为发了 v2 就走 v2 逻辑，结果后端按 v1 执行，字段缺失或格式错乱很难排查
废弃旧版本时，别删代码，而是检测到 v1 就返回 410 Gone，响应体带迁移提示和截止时间，比如：{"error": "API version v1 is deprecated", "sunset": "2026-08-01"}。
最容易被忽略的三个细节
一是 Accept 值必须带 vnd. 前缀，纯 application/json; version=2 不合法，部分 WAF 和 CDN 会拦截；二是中间件里提取版本后，必须白名单校验值是否为 'v1' 或 'v2'，不能直接拼接类路径，防路径遍历；三是 OpenAPI 文档里得明确定义 Accept 支持哪些值，否则生成的 SDK 默认不带这个头，前端调用永远走默认版本。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
