Версионирование API в Spring Framework 7
Замените продублированные контроллеры с версионными префиксами на нативную поддержку версионирования API в Spring Framework 7.
// Version 1 controller
@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {
@GetMapping("/{id}")
public ProductDtoV1 getProduct(
@PathVariable Long id) {
return service.getV1(id);
}
}
// Version 2 — duplicated structure
@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {
@GetMapping("/{id}")
public ProductDtoV2 getProduct(
@PathVariable Long id) {
return service.getV2(id);
}
}
// Configure versioning once
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(
ApiVersionConfigurer config) {
config.useRequestHeader("X-API-Version");
}
}
// Single controller, version per method
@RestController
@RequestMapping("/api/products")
public class ProductController {
@GetMapping(value = "/{id}", version = "1")
public ProductDtoV1 getV1(@PathVariable Long id) {
return service.getV1(id);
}
@GetMapping(value = "/{id}", version = "2")
public ProductDtoV2 getV2(@PathVariable Long id) {
return service.getV2(id);
}
}
Без дублирования контроллеров
Все версии живут в одном классе контроллера; только отдельные методы-обработчики несут атрибут version.
Централизованная стратегия версионирования
Переключайтесь с заголовочного на URL- или параметровое версионирование одним вызовом configureApiVersioning.
Инкрементальная эволюция
Добавляйте новую версию к методу, не затрагивая несвязанные эндпоинты и не создавая новых файлов контроллеров.
Доступно начиная с Spring Framework 7.0 (требует Java 17+)
До Spring Framework 7 версионирование API требовало отдельных классов контроллеров для каждой версии (например, /api/v1/products, /api/v2/products), что дублировало маппинги запросов и рассредотачивало логику версий по множеству файлов. Spring Framework 7 вводит нативное версионирование через новый атрибут version в @RequestMapping и связанных аннотациях, а также хук configureApiVersioning в WebMvcConfigurer. Версия может извлекаться из заголовка запроса, сегмента URL-пути или параметра запроса — всё управляется централизованно.