管理 API 版本的目标是让接口能演进，同时不惊醒存量客户端。常见做法：

  • URL 路径版本：/v1/users，最直观、便于路由与缓存，应用最广。
  • 请求头版本：自定义头或 Accept 媒体类型（Accept: application/vnd.app.v2+json），URL 干净但对客户端略不友好。
  • 查询参数：?version=2，实现简单，但容易被缓存与日志系统忽略。

无论用哪种，配套策略更重要：尽量做向后兼容的演进——只加字段不删字段、不改字段语义、新增端点优先于改造端点；必须破坏性变更时才升大版本，旧版本保留一个明确的日落期，用文档、响应头（如 Sunset、Deprecation）和监控通知调用方迁移。内部实现上，各版本尽量共享底层服务，只在适配层做请求/响应转换，避免复制整套业务逻辑。

易错点：版本号不该挂到每个端点上（否则排列爆炸），按整个 API 或资源域划版本即可；数据库 schema 变更也要纳入兼容策略。追问方向：契约测试、GraphQL 的无版本演进思路。