API版本控制

Spring MVC 支持 API 版本控制。本节将概述所提供的支持及底层策略。spring-doc.cadn.net.cn

请参阅相关主题内容:spring-doc.cadn.net.cn

API版本控制的客户端支持同样适用于RestClientWebClient版本,以及 HTTP服务客户端,同时在MockMvc和WebTestClient中也支持测试。spring-doc.cadn.net.cn

Api版本策略

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

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

ApiVersionResolver

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

路径解析器会从指定索引的路径段中选择版本,或者抛出InvalidApiVersionException,因此除非配置为使用Predicate<RequestPath>来判断路径是否带有版本,否则永远不会导致null(无版本)的情况。spring-doc.cadn.net.cn

ApiVersionParser

此策略有助于将原始版本值解析为Comparable<?>,从而便于比较、排序和选择版本。默认情况下,内置的SemanticApiVersionParser 将版本解析为majorminorpatch的整数值。如果不存在,次要和补丁版本号将被设置为0。spring-doc.cadn.net.cn

验证

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

默认情况下,当API版本控制启用时,需要指定版本号, 若未提供,则会引发MissingApiVersionException导致400响应。您可以将其设置为可选, 此时将使用最新版本。您也可以指定一个默认版本来使用。spring-doc.cadn.net.cn

ApiVersion废弃处理器

此策略可配置为通过响应头向客户端发送关于废弃版本的提示和信息。内置的StandardApiVersionDeprecationHandler 可以设置“Deprecation”和“Sunset”头以及遵循 RFC 9745RFC 8594定义的“Link”头。您也可以为不同头配置自定义 处理器。spring-doc.cadn.net.cn

请求映射

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