API 版本控制

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

API 版本控制的客户端支持也适用于 RestClientWebClientHTTP 服务 客户端,以及 用于测试的 WebTestClient

ApiVersionStrategy

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

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

ApiVersionResolver

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

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

ApiVersionParser

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

验证

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

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

ApiVersionDeprecationHandler

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

请求映射

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