API 版本控制
Spring MVC 支持 API 版本控制。本节概述了该支持和底层策略。
另请参阅相关内容:
在 RestClient、WebClient 和 HTTP 服务 客户端中,以及在 MockMvc 和 WebTestClient 测试中,也提供了对 API 版本控制的客户端支持。
ApiVersionStrategy
这是 API 版本控制的核心策略,它包含所有与版本控制相关的配置偏好。它执行以下操作:
-
通过 ApiVersionResolver 从请求中解析版本
-
使用 ApiVersionParser 将原始版本值解析为
Comparable<?> -
验证 请求版本
-
在响应中发送弃用提示
ApiVersionStrategy 有助于将请求映射到 @RequestMapping 控制器方法,并由 MVC 配置初始化。通常,应用程序不会直接与其交互。
ApiVersionResolver
此策略从请求中解析 API 版本。MVC 配置提供了内置选项,可从标头、查询参数、媒体类型参数或 URL 路径进行解析。您还可以使用自定义的 ApiVersionResolver。
路径解析器始终从指定的路径段解析版本,否则会引发 InvalidApiVersionException,因此它不能让位给其他解析器。 |
ApiVersionParser
此策略有助于将原始版本值解析为 Comparable<?>,这有助于比较、排序和选择版本。默认情况下,内置的 SemanticApiVersionParser 将版本解析为 major、minor 和 patch 整数值。如果不存在,则次要和补丁值设置为 0。
验证
如果请求版本不受支持,则会引发 InvalidApiVersionException,导致 400 响应。默认情况下,支持的版本列表是从带注解的控制器映射中声明的版本初始化的,但您可以通过 MVC 配置中的一个标志将其关闭,并且只使用配置中明确配置的版本。
默认情况下,启用 API 版本控制时需要一个版本,如果不存在,则会引发 MissingApiVersionException,导致 400 响应。您可以将其设为可选,在这种情况下将使用最新版本。您还可以指定要使用的默认版本。
请求映射
ApiVersionStrategy 支持将请求映射到带注解的控制器方法。有关详细信息,请参阅 API 版本。