Wersjonowanie API w Spring Framework 7
Zastąp zduplikowane kontrolery z prefiksami wersji natywnym wsparciem wersjonowania API w 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);
}
}
Bez duplikacji kontrolerów
Wszystkie wersje żyją w jednej klasie kontrolera; tylko poszczególne metody handlera mają atrybut version.
Scentralizowana strategia wersjonowania
Przełącz się z nagłówka na URL lub wersjonowanie przez parametr zapytania jednym wywołaniem configureApiVersioning.
Stopniowa ewolucja
Dodaj nową wersję do jednej metody bez dotykania niepowiązanych endpointów ani tworzenia nowych plików kontrolerów.
Dostępne od Spring Framework 7.0 (wymaga Java 17+)
Przed Spring Framework 7 wersjonowanie API wymagało osobnych klas kontrolerów na wersję (np. /api/v1/products, /api/v2/products), duplikując mapowania żądań i rozpraszając logikę wersji po wielu plikach. Spring Framework 7 wprowadza natywne wersjonowanie przez nowy atrybut version w @RequestMapping i powiązanych adnotacjach, plus hook configureApiVersioning w WebMvcConfigurer. Wersja może być rozwiązywana z nagłówka żądania, segmentu ścieżki URL lub parametru zapytania — wszystko kontrolowane w jednym miejscu.