解读

在国内一线互联网公司的 PHP 后端面试里，"版本控制策略"是区分初中级的分水岭。面试官真正想考察的是：

1. 你是否理解 RESTful 设计原则；
2. 能否结合 PHP 运行特点（FastCGI 无状态、OPcache 常驻、Nginx 反向代理）选择对性能与可维护性最友好的方案；
3. 对缓存、CDN、灰度发布等工程链路的副作用是否心里有数。

三种策略各有适用场景，没有银弹，必须给出"权衡"而非"优劣"。

知识点

1. URI 版本：将版本号直接放在 URL 路径或参数，如 /api/v1/orders。路由层即可识别，调试直观，但破坏资源唯一性，长期产生"地址债"。
2. Header 版本：通过自定义请求头（例如 Accept-Version: v2）或 X-API-Version 实现。URL 保持不变，资源定位纯粹，适合多端复用；缺点是调试门槛高，CDN 默认不缓存头差异，需要额外配置。
3. 媒体类型版本：利用 Accept / Content-Type 的 vendor tree，如 application/vnd.myapi.v3+json。完全符合 HTTP 语义，可表达"同一个资源多种表现"；解析略重，需要 Negotiation 中间件，对新人不友好。
4. PHP 技术细节：
   • Laravel/Symfony 路由都支持正则约束，可轻松实现 URI 版本；
   • 中间件可读取 Accept 头完成媒体类型版本分发；
   • OPcache 以文件路径为 key，URL 变化不会导致额外编译，但 Header 变化也不会触发新编译，性能差异可忽略；
   • swoole/roadrunner 常驻内存时，需在 WorkerStart 阶段把版本策略写进 DI 容器，避免每次请求重新解析。

答案

"三种策略的本质差异在于'版本信息放在哪一层'，没有绝对好坏，只有场景取舍。

1. URI 版本 优点：调试简单，浏览器、Postman、curl 一把梭；Nginx 日志里就能直接看到版本号，方便排障；国内大部分 CDN 默认缓存 KEY 包含 URI，无需额外配置。 缺点：URL 会随版本爆炸式增长，v1、v2、v3 同时在线时，搜索引擎权重分散；老接口下线需要 301 跳转，维护成本高。 适用：对外 OpenAPI、ToB 交付，需要客户一眼看懂；或者项目早期快速迭代，团队规模小，追求'先跑起来'。

2. Header 版本 优点：资源地址稳定，前端/小程序/APP 复用同一 Host，减少域名连接数；版本升级对 SEO 零影响；方便做金丝雀发布，只改网关规则即可。 缺点：国内运维同学更习惯看 URL，排查问题时需额外抓包；CDN 需配置 vary: Accept-Version，否则可能把 v1 响应缓存给 v2 请求；老版本安卓客户端发不出自定义头，需要兼容。 适用：公司内网高并发、接口数量大、生命周期长（5 年以上）；或者已经采用 GraphQL 网关，统一入口。

3. 媒体类型版本 优点：最符合 REST 论文原教旨，同一个 /orders/123 既能返回 v1 也能返回 v2，完全解耦；可以细粒度到字段级别，如 v3 增加字段但保持兼容，客户端用旧 mime 就看不到新字段。 缺点：PHP 原生 $_SERVER['HTTP_ACCEPT'] 需要自行解析权重（q 值），代码量上升；对接 Swagger/OpenAPI 时，每种 mime 都要单独写 Schema，文档维护负担大；国内很多测试只会改 URL，不会改 Accept，导致"版本未生效"的误报。 适用：对 HTTP 规范有洁癖的团队；或者做 SaaS 平台，需要同时支持 JSON、XML、Protobuf 多种表现格式。

落地建议（PHP 视角）：

• 对外 OpenAPI：URI 版本 + 301 升级，半年发一次大版本，老版本保留 18 个月。
• 对内微服务：Header 版本 + 灰度网关，Laravel 用 middleware 读取 X-API-Version，转发到不同的 Service 容器。
• 多端同构：媒体类型版本，Symfony 的 Request::getAcceptableContentTypes() 做协商，配合 serialization 组件自动裁剪字段。

无论哪种方案，都要在 CI 里做'版本扩散检测'：新代码不能无意中改旧版本响应格式；上线前跑一遍契约测试，把差异落到 PHPUnit 数据提供器里，防止'暗改'。"

拓展思考

1. 版本策略与"零停机"发布如何联动？PHP 的 OPcache 重启脚本、Kubernetes 的滚动更新、Nginx 的 upstream hash 策略，三者如何配合才能做到用户无感？
2. 如果公司把接口迁到 Service Mesh，Envoy 默认用 Header 做路由，老项目却全是 URI 版本，怎样写一份"兼容网关"PHP 中间件，让两种策略同时存在且互不干扰？
3. 国内信创环境要求国密算法，v1 响应还是 RSA，v2 已切到 SM2，此时用媒体类型版本，如何在不破坏旧客户端的前提下完成算法协商？是否需要自定义"cipher"子媒体类型？
4. 当版本号走到 v10，URL 长度、Header 大小、Accept 复杂度都接近 HTTP 规范上限，PHP-FPM 的默认 8K 头缓冲区会不会成为隐形瓶颈？如何监控并调优？