跳到主要内容
版本：7.0.3

API 版本控制

Hunyuan 7b 中英对照 API Versioning

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

请同时参阅以下相关内容：

RestClient、WebClient和HTTP Service客户端也支持API版本控制，MockMvc和WebTestClient在进行测试时同样也支持这一功能。

ApiVersionStrategy​

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

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

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

ApiVersionResolver​

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

备注

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

ApiVersionParser​

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

验证​

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

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

ApiVersionDeprecationHandler​

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

请求映射​

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