> ## Documentation Index
> Fetch the complete documentation index at: https://blog.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spring Boot 4.0来了！API版本控制竟然这么香

![3WDCYP](https://minio.pigx.vip/oss/202505/3WDCYP.png)

Spring 官方已经发布了 Spring Boot 4.0 的快照版本，内置 Spring Framework 7.0。Spring Framework 7.0 引入了对 API 版本控制的原生支持，为服务器端和客户端应用程序提供了强大的工具，以高效处理版本特定的路由和请求。

API 版本控制是现代 Web 开发中的关键实践，它允许开发者在不破坏现有客户端的情况下管理 API 的演进和变更，确保向后兼容性的同时引入新功能。

## 基础使用：RequestMapping version 属性

Spring Framework 7.0 在 `@RequestMapping` 及其变体注解中新增了 `version` 属性，让版本控制变得更加简洁和直观。

```java theme={null}
@RequestMapping
@RestController
public class DemoController {

    @GetMapping(version = "1")
    public String version1() {
        return "API Version 1.0.0";
    }

    @GetMapping(version = "2")
    public String version2() {
        return "API Version 2.0.0";
    }
    
    // 支持多版本
    @GetMapping(version = {"1", "2"})
    public String commonEndpoint() {
        return "支持多个版本的通用端点";
    }
}
```

![EWwINT](https://minio.pigx.vip/oss/202505/EWwINT.png)

## 版本解析配置：ApiVersionConfigurer

通过实现 `WebMvcConfigurer` 接口并重写 `configureApiVersioning` 方法，可以自定义版本解析策略。

```java theme={null}
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        // 方式1：使用请求参数（默认参数名为 "version"）
        configurer.useRequestParam("version");
        
        // 方式2：使用请求头
        // configurer.useRequestHeader("API-Version");
        
        // 方式3：使用路径变量
        // configurer.usePathVariable("version");
    }
}
```

### 常见的版本控制策略

1. **请求参数方式**：`?version=1`
2. **请求头方式**：`API-Version: 1`
3. **路径变量方式**：`/api/v1/users`
4. **Accept 头方式**：`Accept: application/vnd.api+json;version=1`

## 调用测试

使用请求参数进行版本控制的测试示例：

```bash theme={null}
# 调用版本1的API
curl "http://localhost:8080/?version=1"
# 输出：API Version 1.0.0

# 调用版本2的API  
curl "http://localhost:8080/?version=2"
# 输出：API Version 2.0.0

# 不指定版本（可能返回默认版本或错误）
curl "http://localhost:8080/"
```

## 高级配置：自定义版本解析器

对于复杂的业务场景，可以实现自定义的版本解析逻辑：

```java theme={null}
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useVersionResolver(new ApiVersionResolver() {
            @Override
            public @Nullable String resolveVersion(HttpServletRequest request) {
                // 示例1：从用户代理字符串解析版本
                String userAgent = request.getHeader("User-Agent");
                if (userAgent != null && userAgent.contains("mobile")) {
                    return "mobile";
                }
                
                // 示例2：基于客户端IP或其他业务规则
                String clientIp = getClientIp(request);
                if (isTestEnvironment(clientIp)) {
                    return "beta";
                }
                
                // 默认版本
                return "1";
            }
        });
    }
}
```

## 总结

![yrCsJB](https://minio.pigx.vip/oss/202505/yrCsJB.png)

通过 Spring Boot 4.0 的原生版本控制支持，开发者可以更优雅地管理API的演进，提升系统的可维护性和用户体验。