工作原理
API 版本是契约的持久标签，而不是某次部署的标签。服务器把每个请求路由到实现对应版本的代码路径，每个版本维护自己的校验、序列化和文档。当必须做不兼容变更（删除字段、收紧校验、重命名资源）时，发布新版本并公告，旧版本继续运行，直到流量下降或弃用窗口结束。
GET /v2/orders/123 HTTP/1.1
Authorization: Bearer ...版本也可以放在请求头（X-API-Version: 2）或媒体类型（Accept: application/vnd.shop.v2+json）中。传输方式对缓存和可发现性的影响大于对正确性的影响。关键在于每个请求只解析出一个版本并写入日志，以便统计旧版本的剩余使用量。
何时使用与取舍
当客户端位于外部、会被缓存或按自己的节奏更新时（移动应用、合作伙伴集成、SDK），应显式版本化。对于一起部署的内部服务，优先采用增量变更和兼容性测试，再考虑新增版本。每个存活版本都是维护成本：重复测试、回补和文档。
路径版本化直观、易路由，但会把版本写进书签和分析数据；请求头版本化保持 URL 干净，却让缓存和手工测试更复杂；媒体类型版本化表达力强，但很多客户端并不熟悉。无论哪种方式，都需要带日期的弃用策略、Deprecation 与 Sunset 响应头，以及调用方遥测。
示例与误解
常见错误是把版本号当成兼容性保证。一个悄悄改变字段类型的 v1 仍会破坏客户端，因此契约测试必须进入 CI。相关概念：向后兼容、模式演进、OpenAPI 契约。