API 版本控制

Spring MVC 支持 API 版本控制。本节概述了其支持和底层策略。 另请参阅以下相关内容:

客户端对 API 版本控制的支持也适用于 RestClientWebClientHTTP 服务 客户端,以及 用于在 MockMvc 和 WebTestClient 中进行测试。

ApiVersionStrategy

这是 API 版本控制的核心策略,它包含了所有与版本控制相关的配置偏好。它执行以下操作:

ApiVersionStrategy 有助于将请求映射到 @RequestMapping 控制器方法, 并由 MVC 配置初始化。通常,应用程序不会直接与它交互。

ApiVersionResolver

此策略从请求中解析 API 版本。MVC 配置提供了内置选项,可以从请求头、查询参数、媒体类型参数 或 URL 路径中解析版本。您也可以使用自定义的 ApiVersionResolver

路径解析器总是从指定的路径段解析版本,否则会引发 InvalidApiVersionException, 因此它不能让位给其他解析器。

ApiVersionParser

此策略有助于将原始版本值解析为 Comparable<?>,这有助于比较、排序和选择版本。 默认情况下,内置的 SemanticApiVersionParser 将版本解析为 majorminorpatch 整数值。如果不存在,次版本和补丁版本值将设置为 0。

验证

如果请求版本不受支持,则会引发 InvalidApiVersionException,导致 400 响应。 默认情况下,支持的版本列表从带注解的控制器映射中声明的版本初始化, 但您可以通过 MVC 配置中的标志将其关闭,并仅使用配置中明确配置的版本。

默认情况下,启用 API 版本控制时,版本是必需的,如果不存在,则会引发 MissingApiVersionException, 导致 400 响应。您可以将其设置为可选,在这种情况下将使用最新版本。 您还可以指定要使用的默认版本。

ApiVersionDeprecationHandler

此策略可以配置为通过响应头向客户端发送有关已弃用版本的提示和信息。 内置的 StandardApiVersionDeprecationHandler 可以设置 "Deprecation"、"Sunset" 头以及 "Link" 头,如 RFC 9745RFC 8594 中所定义。 您还可以为不同的头配置自定义处理程序。

请求映射

ApiVersionStrategy 支持将请求映射到带注解的控制器方法。 有关更多详细信息,请参阅 API 版本