API 版本控制

Spring WebFlux 支持 API 版本控制。本节概述了相关支持及底层策略。spring-doc.cadn.net.cn

另请参阅以下相关内容:spring-doc.cadn.net.cn

RestClientWebClientHTTP Service 客户端也提供了对 API 版本控制的客户端支持, 在 WebTestClient 中进行测试时也同样支持。spring-doc.cadn.net.cn

ApiVersionStrategy

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

ApiVersionStrategy 用于帮助将请求映射到 @RequestMapping 控制器方法, 并由 WebFlux 配置进行初始化。通常情况下,应用程序不会直接与它交互。spring-doc.cadn.net.cn

ApiVersionResolver

该策略从请求中解析 API 版本。WebFlux 配置提供了内置选项,可从请求头、查询参数、媒体类型参数或 URL 路径中解析版本。你也可以使用自定义的 ApiVersionResolverspring-doc.cadn.net.cn

路径解析器从由索引指定的路径段中选择版本,或者抛出 InvalidApiVersionException 异常,因此除非配置了 null 来判断路径是否包含版本信息,否则永远不会返回 Predicate<RequestPath>(即无版本)。spring-doc.cadn.net.cn

ApiVersion 解析器

该策略有助于将原始版本值解析为 Comparable<?>,从而便于比较、排序和选择版本。默认情况下,内置的 SemanticApiVersionParser 会将版本解析为 major(主版本)、minor(次版本)和 patWebFluxch(修订版本)三个整数值。如果未提供次版本或修订版本,则其值默认设为 0。spring-doc.cadn.net.cn

验证

如果请求的版本不受支持,将抛出 InvalidApiVersionException 异常,从而返回 400 响应。默认情况下,受支持的版本列表会从带注解的控制器映射中声明的版本进行初始化,但你可以通过 WebFlux 配置中的一个标志将其关闭,并仅使用在配置中显式设置的版本。spring-doc.cadn.net.cn

默认情况下,启用 API 版本控制时必须提供版本号;如果未提供,则会抛出 MissingApiVersionException 异常,并返回 400 响应。 你可以将其设为可选,此时将使用最新版本。 你也可以指定一个默认使用的版本。spring-doc.cadn.net.cn

ApiVersionDeprecationHandler

该策略可配置为通过响应头向客户端发送有关已弃用版本的提示和信息。内置的 StandardApiVersionDeprecationHandler 可以设置 “Deprecation”、“Sunset” 和 “Link” 响应头,这些响应头遵循 RFC 9745RFC 8594 中的定义。您也可以配置一个自定义处理器来使用不同的响应头。spring-doc.cadn.net.cn

请求映射

ApiVersionStrategy 支持将请求映射到带注解的控制器方法。 更多详情请参见 API 版本spring-doc.cadn.net.cn