REST API 版本策略笔记

公开 API 迟早要改字段与语义。版本策略的目标，是在「老客户端还能用」与「新能力尽快上线」之间取得平衡，并让调用方一眼知道自己在用哪一代契约。

路径前缀（/v1/users）

优点：缓存、路由与文档最直观，网关层也好分流。缺点：大量重复路径；若同一资源跨版本 URL 不同，书签与日志里的链接会碎片化。适合对外 B2B 或生命周期很长的 API。

Header（Accept-Version 或自定义头）

优点：URL 稳定，资源模型可演进。缺点：调试不如路径直观，CDN 与部分中间件对 Header 变体缓存支持弱；客户端 SDK 若未统一封装容易遗漏。适合内部服务或强 SDK 场景。

内容协商（Accept + profile）

优点：HTTP 语义正统，可细到表示层。缺点：学习成本高，排障难。常与 Header 方案混用；不建议作为唯一手段 unless 团队已习惯。

实践建议：对外公共 API 以路径版本为主，辅以清晰的弃用公告与时间表；对内可评估 Header。无论哪种，错误体里带上可读的 request_id 与文档链接，排障会轻松很多。