API版本控制需默认分支、宽松路由、q值排序、物理隔离资源类、避免路径版本、数据库变更解耦、坚守旧版契约。
Accept头解析必须容忍缺失和模糊匹配
客户端不带Accept头或只传application/json是常态，硬性要求application/vnd.myapp.v2+json会导致大量406错误。实际路由逻辑必须设默认分支（如v1），且正则匹配要宽松：
- 用
/v(\d+)/而非/v1|v2/，避免每加一版就改路由代码 - 当
Accept含多个类型（如application/json, application/vnd.myapp.v2+json;q=0.8）时，需按RFC 7231的q值排序取最高优先级项，不能简单explode(',', $accept)[0] - 若业务允许降级，可对
v3请求返回v2结构并加X-API-Version: v2响应头提示兼容回退
Laravel中Resource与Request类必须按版本物理隔离
把rules()或toArray()塞进条件判断里（比如if ($version === 'v2') {...}）会快速演变成意大利面条代码。正确做法是让版本成为命名空间的一部分：
- 资源类路径：
App\Http\Resources\V1\UserResource和App\Http\Resources\V2\UserResource，各自独立维护字段映射逻辑 - 验证类路径：
App\Http\Requests\V2\UpdateUserRequest，重写rules()返回适配v2的规则（例如新增timezone必填，而v1无此字段） - 控制器里直接引用对应版本类：
return new V2\UserResource($user)，不依赖运行时判断
URI路径版本不是“错”，但会触发三个隐性成本
用/api/v1/users看似省事，但上线后很快暴露问题：
- CDN和浏览器缓存把
/v1/users和/v2/users当两个完全无关资源，相同数据重复存储、重复计算ETag - OpenAPI文档生成器（如Swagger）需为每个版本单独维护
paths区块，字段微调就得同步改两处，极易遗漏 - 前端路由库（如React Router）或SDK自动生成工具会把
v1硬编码进URL拼接逻辑，升级时需批量搜索替换/v1/——这违背了“版本应由客户端声明而非服务端强约束”的设计本意
数据库变更必须与API版本解耦
别在v2发布时直接删掉custom字段。真实场景中，v1客户端可能持续运行半年以上。安全做法是：
立即学习“PHP免费学习笔记（深入）”；
- 新增字段（如
exhaust）可直接加，v1 Resource忽略它即可 - 废弃字段（如
custom）保留在表中，v2 Resource不映射，但v1仍能读写；等v1流量归零后再归档 - 字段语义变更（如
price从整数变浮点）需通过DTO层转换，而非直接改数据库类型，否则v1写入可能被截断
版本控制最难的不是写分支逻辑，而是守住“旧版本接口行为不可变”这条线——哪怕它背后调用的是同一套Service方法，只要Response结构或状态码变了，就等于破坏了契约。
