/api/v1/users
。Accept
头)指定版本,例如 application/vnd.company.app-v1+json
。/api/users?version=1
。Accept
头的媒体类型确定版本。@RequestMapping
注解中的版本范围将请求映射到不同的控制器方法。这种方法简化了多版本 API 的管理,使开发者能够在一个应用程序中处理多个 API 版本。
@RequestMapping
注解中指定版本范围,Spring 会根据请求中的版本信息将请求路由到相应的控制器方法。版本可以从以下来源解析:
/api/v1/users
或 /api/v2/users
。Accept: application/vnd.company.app-v1+json
。/api/users
端点根据请求的版本(1.0
或 2.0
)调用不同的方法。版本可以通过 URL 路径(如 /api/v1/users
)或请求头指定。
策略 | 描述 | 优点 | 缺点 |
---|---|---|---|
URI 版本控制 | 在 URL 路径中包含版本号(如 /api/v1/users ) | 简单直观,易于在浏览器中测试 | 可能导致 URL 路径过长,难以维护 |
请求头版本控制 | 通过请求头指定版本(如 Accept 头) | 保持 URL 简洁,适合复杂版本控制 | 需要客户端支持自定义头,调试较复杂 |
查询参数版本控制 | 通过查询参数传递版本号(如 /api/users?version=1 ) | 实现简单,URL 结构清晰 | 不够语义化,可能影响缓存策略 |
内容协商版本控制 | 基于 Accept 头的媒体类型确定版本 | 灵活,符合 REST 原则 | 实现复杂,客户端配置要求较高 |
WebClient
或其他客户端工具时,开发者可以在发送请求时指定所需的 API 版本。这确保客户端与正确的 API 版本交互,特别是在多个 API 版本同时部署的情况下。
WebClient
指定 API 版本的示例:
Accept
头为 application/vnd.company.app-v1+json
来请求版本 1.0 的 API。这种方法确保客户端与目标 API 版本保持一致,避免版本不匹配的问题。
ApiVersionResolver
是一个函数式接口,定义了从请求中解析版本的契约:
PathApiVersionResolver
是 ApiVersionResolver
的一个实现,用于从 URL 路径中提取版本信息:
/api/v1/users
,如果设置 pathSegmentIndex
为 1,则会提取 v1
作为版本值。
DefaultApiVersionStrategy
是 API 版本策略的默认实现,提供了版本解析、比较和验证的核心功能:
VersionRequestCondition
类,它作为请求映射的条件之一,用于根据请求中的版本将请求路由到合适的处理方法:
ApiVersionResolver
、ApiVersionStrategy
和 VersionRequestCondition
协同工作,提供了从请求解析版本、验证版本并路由到适当处理方法的完整流程。这种设计不仅支持常见的版本控制策略,还允许开发者实现自定义的版本解析和验证逻辑,以满足特定的业务需求。