🦜一种新的API 版本控制规范：基于自定义媒体类型

本规范旨在指导开发者使用自定义媒体类型（Content Negotiation）进行 API 版本控制，以实现更优雅、更可持续的 API 设计。

1. 概述

传统的 URL 版本化（例如 /v1/orders）存在诸多问题，如 URI 不稳定、客户端耦合度高、代码冗余等。本规范推荐使用自定义媒体类型，将版本信息嵌入 HTTP 的媒体类型（MIME type）中，通过内容协商来决定后端该使用哪一版逻辑。

2. 媒体类型定义

根据 RFC 6838 规范，自定义媒体类型的格式如下：

<type>/vnd.<vendor>.<resource>-v<version>+<suffix>

<type>: 顶级类型，通常为 application。
vnd: 表示厂商特定的媒体类型。
<vendor>: 厂商或组织的名称。
<resource>: 资源名称。
-v<version>: API 的版本号，可选。
<suffix>: 结构化后缀，指示底层编码格式，如 json、xml。

示例：

application/vnd.example.order-v1+json：Example 厂商的 Order 资源的第一个版本，使用 JSON 格式。
application/vnd.example.order-v2+xml：Example 厂商的 Order 资源的第二个版本，使用 XML 格式。
application/vnd.example.order+json：Example 厂商的 Order 资源的最新版本（未指定版本号）。

3. 客户端请求

客户端通过 Accept 请求头指定期望的 API 版本。

示例：

GET /orders/123 HTTP/1.1
Accept: application/vnd.example.order-v2+json

在 POST/PUT 请求中，客户端可以通过 Content-Type 请求头指定请求体的版本。

示例：

POST /orders HTTP/1.1
Content-Type: application/vnd.example.order-v1+json

4. 服务端实现 (Java)

4.1 Spring MVC 配置

在 Spring MVC 中，可以使用 @RequestMapping 注解的 produces 和 consumes 属性来指定支持的媒体类型。

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping(value = "/{orderId}", produces = "application/vnd.example.order-v1+json")
    public ResponseEntity<OrderV1> getOrderV1(@PathVariable String orderId) {
        // 处理 V1 版本的逻辑
        OrderV1 order = new OrderV1(orderId, "Order V1 Details");
        return ResponseEntity.ok(order);
    }

    @GetMapping(value = "/{orderId}", produces = "application/vnd.example.order-v2+json")
    public ResponseEntity<OrderV2> getOrderV2(@PathVariable String orderId) {
        // 处理 V2 版本的逻辑
        OrderV2 order = new OrderV2(orderId, "Order V2 Details with extra fields");
        return ResponseEntity.ok(order);
    }

    @PostMapping(consumes = "application/vnd.example.order-v1+json", produces = "application/vnd.example.order-v1+json")
    public ResponseEntity<OrderV1> createOrderV1(@RequestBody OrderV1 order) {
        // 处理 V1 版本的创建订单逻辑
        return ResponseEntity.ok(order);
    }

    @PostMapping(consumes = "application/vnd.example.order-v2+json", produces = "application/vnd.example.order-v2+json")
    public ResponseEntity<OrderV2> createOrderV2(@RequestBody OrderV2 order) {
        // 处理 V2 版本的创建订单逻辑
        return ResponseEntity.ok(order);
    }
}

// V1 版本的订单类
class OrderV1 {
    private String orderId;
    private String details;

    public OrderV1(String orderId, String details) {
        this.orderId = orderId;
        this.details = details;
    }

    public String getOrderId() { return orderId; }
    public String getDetails() { return details; }
}

// V2 版本的订单类
class OrderV2 {
    private String orderId;
    private String details;

    public OrderV2(String orderId, String details) {
        this.orderId = orderId;
        this.details = details;
    }

    public String getOrderId() { return orderId; }
    public String getDetails() { return details; }
}

4.2 版本解析器 (Version Resolver)

如果需要更灵活的版本控制，可以自定义版本解析器，根据 Accept 头动态选择处理逻辑。

import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.condition.AbstractRequestCondition;

import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class ApiVersionCondition extends AbstractRequestCondition<ApiVersionCondition> {

    private static final Pattern VERSION_PATTERN = Pattern.compile(".*-v(\\d+).*");
    private final int version;

    public ApiVersionCondition(int version) {
        this.version = version;
    }

    public int getVersion() {
        return version;
    }

    @Override
    protected Collection<?> getContent() {
        return List.of(version);
    }

    @Override
    protected String getToStringInfix() {
        return "apiVersion=";
    }

    @Override
    public ApiVersionCondition combine(ApiVersionCondition other) {
        // 总是使用最新的版本
        return other;
    }

    @Override
    public ApiVersionCondition getMatchingCondition(ServerWebExchange exchange) {
        String accept = exchange.getRequest().getHeaders().getFirst("Accept");
        if (accept != null) {
            Matcher matcher = VERSION_PATTERN.matcher(accept);
            if (matcher.find()) {
                int version = Integer.parseInt(matcher.group(1));
                if (version == this.version) {
                    return this;
                }
            }
        }
        return null;
    }

    @Override
    public int compareTo(ApiVersionCondition other, ServerWebExchange exchange) {
        // 优先匹配版本号大的
        return other.version - this.version;
    }
}

4.3 使用自定义版本解析器

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping("/{orderId}")
    @ApiVersion(1)
    public ResponseEntity<OrderV1> getOrderV1(@PathVariable String orderId) {
        // 处理 V1 版本的逻辑
        OrderV1 order = new OrderV1(orderId, "Order V1 Details");
        return ResponseEntity.ok(order);
    }

    @GetMapping("/{orderId}")
    @ApiVersion(2)
    public ResponseEntity<OrderV2> getOrderV2(@PathVariable String orderId) {
        // 处理 V2 版本的逻辑
        OrderV2 order = new OrderV2(orderId, "Order V2 Details with extra fields");
        return ResponseEntity.ok(order);
    }
}

5. 版本废弃策略

提前通知： 在 API 响应头中添加 Deprecation 字段，告知客户端该版本即将废弃。
提供迁移指南： 提供详细的迁移指南，帮助客户端升级到新版本。
逐步下线： 逐步降低旧版本的优先级，最终停止支持。

示例：

HTTP/1.1 200 OK
Content-Type: application/vnd.example.order-v1+json
Deprecation: version=v1, sunset=2024-12-31, link="https://example.com/api/migration"