API 版本

在响应式栈中查看等效项

要启用 API 版本控制，请使用 WebMvcConfigurer 的 ApiVersionConfigurer 回调：

Java

@Configuration
public class WebConfiguration implements WebMvcConfigurer {

	@Override
	public void configureApiVersioning(ApiVersionConfigurer configurer) {
		configurer.useRequestHeader("API-Version");
	}
}

Kotlin

@Configuration
class WebConfiguration : WebMvcConfigurer {

	override fun configureApiVersioning(configurer: ApiVersionConfigurer) {
		configurer.useRequestHeader("API-Version")
	}
}

您可以通过下面列出的内置选项之一来解析版本，或者使用自定义的 ApiVersionResolver：

• 请求头 (Request header)
• 请求参数 (Request parameter)
• 路径段 (Path segment)
• 媒体类型参数 (Media type parameter)

要从路径段解析，您需要指定预期包含版本的路径段索引。路径段必须声明为 URI 变量，例如 "/{version}"、"/api/{version}" 等，实际名称并不重要。由于版本通常位于路径的开头，请考虑通过 路径匹配 选项将其外部配置为所有处理程序的通用路径前缀。

默认情况下，版本使用 SemanticVersionParser 进行解析，但您也可以配置自定义的 ApiVersionParser。

为方便起见，支持的版本会从请求映射中声明的版本中透明地检测到，但您可以通过 MVC 配置中的标志关闭该功能，并仅考虑配置中显式配置的版本为支持的版本。对于版本不受支持的请求，将通过 InvalidApiVersionException 拒绝，从而导致 400 响应。

您可以设置 ApiVersionDeprecationHandler 以向客户端发送有关已弃用版本的信息。内置的标准处理程序可以根据 RFC 9745 和 RFC 8594 设置 "Deprecation"、"Sunset" 和 "Link" 标头。

一旦配置了 API 版本控制，您就可以开始根据请求版本将请求映射到 控制器方法。

---

补充教学

1. 为什么需要 API 版本？

随着业务发展，API 的入参或返回结构可能会发生破坏性变更（Breaking Changes）。通过版本控制，你可以让旧版本的客户端继续访问 v1 接口，同时让新客户端使用 v2 接口，实现平滑过渡。

2. 什么是语义化版本 (Semantic Versioning)？

Spring 默认解析器支持语义化版本（如 1.0.0）。

• Major: 大版本更迭，通常有不兼容变更。
• Minor: 新功能增加，保持向后兼容。
• Patch: 隐蔽的 Bug 修复。

3. 过期通知 (Deprecation)

通过 ApiVersionDeprecationHandler，你可以在响应头中告知客户端某个版本即将停用（Sunset）。这在大型分布式系统中是非常负责任的做法，能有效推动合作伙伴进行升级。