Quản lý các phiên bản khác nhau của API trong Spring Boot như thế nào?

Quản lý phiên bản API trong Spring Boot có thể thực hiện bằng nhiều cách khác nhau, tùy vào yêu cầu của hệ thống. Dưới đây là một số phương pháp phổ biến:

1. Sử dụng Đường dẫn (URI Versioning)

Phương pháp này đặt phiên bản API trong URL, ví dụ:

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    @GetMapping
    public String getUsers() {
        return "Danh sách users - v1";
    }
}

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    @GetMapping
    public String getUsers() {
        return "Danh sách users - v2 với dữ liệu khác";
    }
}

✅ Ưu điểm: Dễ dàng triển khai, trực quan với người dùng.
❌ Nhược điểm: Làm phình to số lượng endpoint, URL có thể trở nên rối rắm.

2. Sử dụng Header Versioning

Phương pháp này sử dụng HTTP Header để chỉ định phiên bản API.

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping(value = "", headers = "X-API-VERSION=1")
    public String getUsersV1() {
        return "Danh sách users - v1";
    }

    @GetMapping(value = "", headers = "X-API-VERSION=2")
    public String getUsersV2() {
        return "Danh sách users - v2";
    }
}

✅ Ưu điểm: URL giữ nguyên, dễ dàng mở rộng API.
❌ Nhược điểm: Yêu cầu client phải thêm header, khó test trên trình duyệt.

3. Sử dụng Query Parameter Versioning

Truyền phiên bản API thông qua tham số query, ví dụ:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping(value = "", params = "version=1")
    public String getUsersV1() {
        return "Danh sách users - v1";
    }

    @GetMapping(value = "", params = "version=2")
    public String getUsersV2() {
        return "Danh sách users - v2";
    }
}

✅ Ưu điểm: Linh hoạt, dễ kiểm tra bằng trình duyệt.
❌ Nhược điểm: Không phải là cách tiếp cận phổ biến cho API REST.

4. Sử dụng Content Negotiation (Accept Header Versioning)

Dùng header Accept để chỉ định phiên bản:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping(value = "", produces = "application/vnd.company.app-v1+json")
    public String getUsersV1() {
        return "Danh sách users - v1";
    }

    @GetMapping(value = "", produces = "application/vnd.company.app-v2+json")
    public String getUsersV2() {
        return "Danh sách users - v2";
    }
}

✅ Ưu điểm: Giữ URL gọn gàng, tuân theo RESTful hơn.
❌ Nhược điểm: Yêu cầu client hỗ trợ Accept header.

5. Sử dụng Spring API Versioning Library

Có thể sử dụng thư viện như springfox-swagger2 hoặc springdoc-openapi để hỗ trợ versioning:

@Tag(name = "Users", description = "API cho người dùng")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "Lấy danh sách users v1", description = "API version 1")
    @GetMapping(value = "", produces = "application/vnd.company.app-v1+json")
    public String getUsersV1() {
        return "Danh sách users - v1";
    }

    @Operation(summary = "Lấy danh sách users v2", description = "API version 2")
    @GetMapping(value = "", produces = "application/vnd.company.app-v2+json")
    public String getUsersV2() {
        return "Danh sách users - v2";
    }
}

🎯 Nên chọn phương pháp nào?

Nếu API của bạn đơn giản → Sử dụng URI versioning (/api/v1/...).
Nếu bạn muốn linh hoạt & RESTful → Sử dụng Header versioning hoặc Content negotiation.
Nếu muốn dễ test và backward-compatible → Sử dụng Query parameter versioning.
Nếu API có thể mở rộng nhiều trong tương lai → Dùng Spring API Versioning Library.

Quản lý các phiên bản khác nhau của API trong Spring Boot như thế nào?