跳到主要内容
版本：7.0.3

API版本控制

Hunyuan 7b 中英对照 API Versioning

Spring WebFlux支持API版本控制。本节提供了对此支持的概述以及其背后的策略。

请参阅以下相关内容：

RestClient、WebClient 和 HTTP Service 客户端也支持对 API 版本的管理，WebTestClient 也支持进行相关测试。

ApiVersionStrategy​

这是API版本控制的中心策略，其中包含了与版本控制相关的所有配置偏好设置。它执行以下功能：

  • 通过ApiVersionResolver从请求中解析版本信息。
  • 使用[ApiVersionParser](#webflux-versioning parser)将原始版本值解析为Comparable<?>类型。
  • 验证请求中的版本信息。

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

ApiVersionResolver​

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

备注

路径解析器总是从指定的路径段中解析版本号，否则会抛出InvalidApiVersionException异常，因此它无法依赖其他解析器。

ApiVersionParser​

这种策略有助于将原始的版本值解析为Comparable<?>类型，从而便于进行比较、排序和版本选择。默认情况下，内置的SemanticApiVersionParser会将版本号解析为major（主版本号）、minor（次版本号）和patch（补丁版本号）这三个整数。如果次版本号或补丁版本号不存在，则会将其设置为0。

验证​

如果请求的版本不受支持，将会抛出 InvalidApiVersionException 异常，导致 400 响应。默认情况下，支持的版本列表是根据控制器映射中注解声明的版本来初始化的，但你可以通过 WebFlux 配置中的一个标志来关闭这一功能，从而仅使用配置中明确指定的版本。

默认情况下，如果启用了API版本控制，则需要指定一个版本号；如果没有提供版本号，将会抛出MissingApiVersionException异常，并返回400响应。你可以将其设置为可选字段，在这种情况下将使用最新的版本号。你也可以指定一个默认版本号来使用。

ApiVersionDeprecationHandler​

此策略可以配置为通过响应头向客户端发送关于已弃用版本的提示和信息。内置的StandardApiVersionDeprecationHandler可以根据RFC 9745和RFC 8594中定义的内容，设置“Deprecation”（弃用）头、“Sunset”（终止日期）头以及“Link”（链接）头。您还可以为不同的头部配置自定义处理程序。

请求映射​

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