API 版本管理与兼容性：字段演进与平滑下线

GET /users/123
Accept: application/vnd.plume.user.v2+json

// 自定义 Header 版本
GET /users/123
X-API-Version: 2

@RestController
public class UserVersionedController {

    @GetMapping(value = "/users/{id}", produces = "application/vnd.user.v2+json")
    public UserV2Dto getUserV2(@PathVariable Long id) {
        return userService.getV2(id);
    }

    @GetMapping(value = "/users/{id}", produces = "application/vnd.user.v1+json")
    public UserV1Dto getUserV1(@PathVariable Long id) {
        return userService.getV1(id);
    }
}

// 版本号必须沉淀在 API 元数据中
@Configuration
public class OpenApiVersionConfig {
    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                .info(new Info().title("Plume API").version("2.4.1"));
    }
}

破坏性（必须升 MAJOR）：
  - 删除或重命名字段
  - 修改字段类型或格式
  - 收紧必填约束
  - 修改错误码语义
  - 变更认证/鉴权方式
  - 移除端点或改变 HTTP 方法

public record UserV2(
        Long id,
        String name,
        String email,
        String nickname,        // 新增字段，老客户端不感知
        String locale          // 新增字段，缺省时服务端给默认值
) {
    public UserV2 {
        locale = locale == null ? "zh-CN" : locale;
    }
}

@Bean
public ObjectMapper objectMapper() {
    return JsonMapper.builder()
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
            .build();
}

// 阶段一：新增字段，旧字段标记废弃
public record AddressV2(
        String street,
        String oldZipCode,          // @Deprecated
        String postalCode          // 新字段，与旧字段同步
) {}

@Schema(description = "用户昵称", deprecated = true)
private String nickname;

# openapi.yaml 中的废弃字段示例
User:
  type: object
  properties:
    nickname:
      type: string
      deprecated: true

1. 公告：在文档与 API 响应头中声明废弃日期
2. 迁移：提供替代接口与迁移指南
3. 冻结：对新客户端拒绝使用旧版本
4. 观察：监控旧版本调用量，低于阈值后推进
5. 下线：移除实现，返回 410 Gone 并保留错误信息

// 下线后返回 410，而不是 404，语义更准确
@DeleteMapping("/api/v1/legacy/endpoint")
public ResponseEntity<Void> gone() {
    return ResponseEntity.status(410)
            .header("Deprecation", "true")
            .build();
}

// 网关或服务端记录每个请求的版本号，形成使用率趋势
@Component
public class VersionUsageFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req,
                                    HttpServletResponse resp,
                                    FilterChain chain) throws ServletException, IOException {
        String version = resolveVersion(req);
        Counter.builder("api.version.usage")
                .tag("version", version)
                .register(meterRegistry)
                .increment();
        chain.doFilter(req, resp);
    }
}

@Configuration
public class VersionedRequestMappingConfig {

    @Bean
    public HandlerMapping versionedHandlerMapping() {
        PathPatternParser parser = new PathPatternParser();
        RequestMappingHandlerMapping mapping = new RequestMappingHandlerMapping(parser);
        mapping.setOrder(0);
        return mapping;
    }
}

// Controller 中用 @RequestMapping 声明两个版本类即可并行部署
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 { }

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 { }

// Pact 消费者契约示例
def user = [
    id: 1,
    name: '张三',
    email: 'zhangsan@example.com'
]