SpringBoot4系列22 - 使用API版本管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

public @interface RequestMapping {
    String name();
    String[] value();
    String[] path();
    RequestMethod[] method();
    String[] params();
    String[] headers();
    String[] consumes();
    String[] produces();
    String version();          // 版本声明在这里
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

ApiVersionResolver            接口：String resolveVersion(HttpServletRequest)
HeaderApiVersionResolver      从请求头取版本
QueryApiVersionResolver       从查询参数取版本
MediaTypeParamApiVersionResolver  从 media type 参数取版本
PathApiVersionResolver        从路径段取版本
ApiVersionStrategy            接口：解析、校验、默认版本、废弃提示的总入口
DefaultApiVersionStrategy     唯一内置实现
ApiVersionParser              接口：字符串转版本对象
SemanticApiVersionParser      默认实现，产出 Version(major, minor, patch)
ApiVersionHolder              每个请求的版本载体，挂在 request attribute 上
ApiVersionDeprecationHandler  版本废弃提示的回调接口
MissingApiVersionException    无版本且必填时抛出
InvalidApiVersionException    版本非法时抛出，NotAcceptableApiVersionException 继承它

1
2
3
4
5
6
7
8

spring.mvc.apiversion.default                    String    无版本请求按这个版本处理
spring.mvc.apiversion.required                   Boolean   每个请求是否必须带版本
spring.mvc.apiversion.supported                  List<String>  受支持的版本白名单
spring.mvc.apiversion.detect-supported           Boolean   是否从 controller 映射探测受支持版本
spring.mvc.apiversion.use.header                 String    用指定名字的请求头取版本
spring.mvc.apiversion.use.query-parameter        String    用指定名字的查询参数取版本
spring.mvc.apiversion.use.media-type-parameter   Map<MediaType, String>  用 media type 参数取版本
spring.mvc.apiversion.use.path-segment           Integer   用指定下标的路径段取版本

1
2
3
4
5
6
7
8
9

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

server:
  port: ${SERVER_PORT:18220}

spring:
  application:
    name: springboot4-apiversion
  mvc:
    problemdetails:
      enabled: true
    apiversion:
      default: 1
      required: false
      supported: 1, 2, 3
      use:
        header: X-Api-Version
        query-parameter: api-version

logging:
  level:
    com.xncoding.apiversion: DEBUG

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

@Service
public class OrderService {

    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public Order getById(Long id) {
        return repository.findById(id)
                .orElseThrow(() -> new IllegalArgumentException("订单不存在: " + id));
    }

    public List<Order> findAll() {
        return repository.findAll();
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@RestController
@RequestMapping(value = "/api/orders", version = "1")
public class OrderControllerV1 {

    private final OrderService service;

    public OrderControllerV1(OrderService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public OrderResponseV1 detail(@PathVariable Long id) {
        return toDto(service.getById(id));
    }

    static OrderResponseV1 toDto(Order order) {
        return OrderResponseV1.of(order.getId(), order.getOrderNo(),
                order.getCustomerName(), order.getCustomerPhone(),
                order.getUnitPrice(), order.getQuantity(), order.getDiscount(),
                order.getShippingFee(), order.getTotalAmount(),
                order.getStatus(), order.getCreatedAt());
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@RestController
@RequestMapping(value = "/api/orders", version = "2")
public class OrderControllerV2 {

    private final OrderService service;

    public OrderControllerV2(OrderService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public OrderResponseV2 detail(@PathVariable Long id) {
        return toDto(service.getById(id));
    }

    static OrderResponseV2 toDto(Order order) {
        return OrderResponseV2.of(order.getId(), order.getOrderNo(),
                order.getCustomerName(), order.getCustomerPhone(),
                order.getUnitPrice(), order.getQuantity(), order.getDiscount(),
                order.getShippingFee(), order.getTotalAmount(),
                order.getStatus(), order.getCreatedAt());
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public class OrderResponseV2 {

    private Long id;
    private String orderNo;
    private Customer customer;      // 客户聚合：name + phone
    private List<AmountItem> items; // 金额明细：三行 label + value
    private Amount amount;          // 金额汇总：四个分量

    public static class Customer {
        private String name;
        private String phone;
    }

    public static class AmountItem {
        private String label;
        private BigDecimal value;
    }

    public static class Amount {
        private BigDecimal goodsAmount;
        private BigDecimal discountAmount;
        private BigDecimal shippingFee;
        private BigDecimal totalAmount;
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

@RestController
public class VersionProbeController {

    @GetMapping(value = "/api/version/echo", version = "2+")
    public Map<String, Object> echo(Version version) {
        return Map.of(
                "resolved", version.toString(),
                "major", version.getMajor(),
                "minor", version.getMinor(),
                "patch", version.getPatch()
        );
    }
}

1
2
3
4

1. 不带任何版本        → 200  v1 快照结构（default: 1 生效）
2. X-Api-Version: 1    → 200  v1 快照结构
3. X-Api-Version: 2    → 200  v2 拆分结构
4. ?api-version=2      → 200  v2 拆分结构（与 header 等价）

1
2
3

5. X-Api-Version: abc       → 400  {"detail":"Invalid API version: 'abc'.", "status":400}
6. X-Api-Version: 9         → 400  {"detail":"Invalid API version: '9.0.0'.", "status":400}
7. X-Api-Version: 3 打订单   → 400  {"detail":"Invalid API version: '3.0.0'.", "status":400}

1
2
3
4

8. X-Api-Version: 3 打 echo（2+）   → 200  {"resolved":"3.0.0","major":3,"minor":0,"patch":0}
9. X-Api-Version: 2 打 echo（2+）   → 200
10. X-Api-Version: 2.4.1 打 echo    → 400  白名单精确匹配，小版本不自动包含
11. X-Api-Version: 1 打 echo（2+）  → 404  不满足基线，且无其他映射

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

@Configuration
public class ApiVersionDeprecationConfig {

    @Bean
    public ApiVersionDeprecationHandler apiVersionDeprecationHandler() {
        StandardApiVersionDeprecationHandler handler =
                new StandardApiVersionDeprecationHandler();
        handler.configureVersion("1")
                .setDeprecationDate(ZonedDateTime.of(2026, 10, 1, 0, 0, 0, 0,
                        ZoneId.of("Asia/Shanghai")))
                .setDeprecationLink(URI.create(
                        "https://example.com/docs/api-v2-migration"))
                .setSunsetDate(ZonedDateTime.of(2027, 4, 1, 0, 0, 0, 0,
                        ZoneId.of("Asia/Shanghai")));
        return handler;
    }
}

1
2
3
4

HTTP/1.1 200
Deprecation: @1790784000
Link: <https://example.com/docs/api-v2-migration>; rel="deprecation"; type="text/html"
Sunset: Thu, 1 Apr 2027 00:00:00 +0800

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ApiVersionEndToEndTest {

    @LocalServerPort
    private int port;

    private RestTestClient client;

    @BeforeEach
    void setUp() {
        client = RestTestClient.bindToServer()
                .baseUrl("http://localhost:" + port)
                .build();
    }

    @Test
    void headerRouteSelectsVersion() {
        String v1 = client.get().uri("/api/orders/1")
                .header("X-Api-Version", "1")
                .exchange()
                .expectStatus().isEqualTo(HttpStatusCode.valueOf(200))
                .expectBody(String.class)
                .returnResult().getResponseBody();
        assertThat(v1).contains("customerPhone").contains("unitPrice");

        String v2 = client.get().uri("/api/orders/1")
                .header("X-Api-Version", "2")
                .exchange()
                .expectStatus().isEqualTo(HttpStatusCode.valueOf(200))
                .expectBody(String.class)
                .returnResult().getResponseBody();
        assertThat(v2).contains("\"customer\":{\"name\"").contains("\"items\"");
    }
}

1
2

ApiVersionEndToEndTest    8    4.062s    默认版本 / 双路线路由 / 白名单 / 范围 / 并存
合计                      8    BUILD SUCCESS