0

[Microservices Series] Bài 20: API Versioning – Nâng cấp hệ thống bay cao mà không bỏ rơi "người cũ"

Chào anh em! Ở bài 19, chúng ta đã đưa BFF (Backend for Frontend) vào để gom API lại cho Frontend "dễ thở" hơn. Nhưng mọi chuyện đâu có êm đềm mãi.

Tháng trước, hệ thống của bạn hoạt động hoàn hảo với API /users trả về {"name": "Hiếu", "address": "Quận 1"}. Tháng này, Business yêu cầu tách địa chỉ ra chi tiết hơn: {"name": "Hiếu", "address": {"city": "Hồ Chí Minh", "district": "Quận 1"}}. Bạn tung code mới lên Server. Boom! 50% người dùng chưa kịp update Mobile App mới lập tức bị văng ứng dụng (App Crash) vì Frontend cũ đang mong đợi address là một chuỗi (String), nhưng giờ lại nhận về một Object.

Trong Microservices (và bất kỳ hệ thống nào có Mobile App/Partner API), bạn không thể bắt khách hàng update App ngay lập tức được. Bạn phải duy trì mã nguồn chạy song song cả chuẩn cũ lẫn chuẩn mới. Đó là lúc chúng ta phải dùng đến API Versioning (Đánh phiên bản API).

1. Các chiến thuật API Versioning "Quốc dân"

Làm sao để hệ thống biết request này đến từ App cũ hay App mới? Có 3 cách phổ biến nhất:

Cách 1: URI Versioning (Nhúng thẳng vào URL)

  • App cũ gọi: GET /api/v1/users

  • App mới gọi: GET /api/v2/users

  • Điểm cộng: Dễ nhìn, dễ debug, copy link dán vào trình duyệt là test được ngay.

  • Điểm trừ: Sai nguyên lý chuẩn của RESTful (vì /v1/ và /v2/ không đại diện cho tài nguyên thực tế).

Cách 2: Header Versioning (Giấu trong Custom Header)

  • URL giữ nguyên: GET /api/users

  • App truyền thêm Header: X-API-Version: 2

  • Điểm cộng: URL sạch sẽ, đúng chuẩn RESTful.

  • Điểm trừ: Khó test hơn một chút (không dán thẳng vào trình duyệt được, phải dùng Postman thêm Header).

Cách 3: Query Parameter Versioning

  • URL: GET /api/users?version=2

  • (Ít dùng trong các hệ thống lớn, thường chỉ dùng cho các public API đơn giản).

2. Nỗi đau khi bảo trì Versioning trong Microservices

Dù bạn chọn cách nào, vấn đề thực sự nằm ở phần Code Backend.

Nhiều anh em xử lý rất "cồng kềnh": Viết ra hẳn 2 Controllers riêng biệt UserControllerV1 và UserControllerV2. Hậu quả là: Nếu có một bug bảo mật ở phần "Đổi mật khẩu", bạn phải chui vào sửa ở cả V1, V2, V3... Code bị lặp lại (Duplicate) ở khắp nơi. Càng nâng cấp, code càng "thối" và phình to.

3. Thực chiến Versioning tại hệ thống AFC

Trong hệ thống vận hành Metro, mình ưu tiên chiến thuật: Định tuyến ngay tại tầng API Gateway (hoặc BFF) để bảo vệ các Core Services bên trong.

Nguyên lý thiết kế của mình là: Core Service chỉ chạy phiên bản mới nhất (Current Version). Việc "hạ cấp" (Downgrade) dữ liệu cho App cũ là trách nhiệm của BFF.

Kịch bản thực chiến:

  1. Core Service (Go): Mình update Database và sửa code để trả về address dạng Object. Service này không quan tâm V1 hay V2 gì cả, nó chỉ biết cung cấp data xịn nhất hiện tại.

  2. Tại BFF (Node.js):

    • BFF nhận request. Nó kiểm tra xem App đang gọi lên là V1 hay V2 (qua URL /api/v1/... hoặc Header).

    • BFF gọi xuống Core Service lấy cục dữ liệu mới nhất (chứa address dạng Object).

    • Nếu là App V2: BFF ném thẳng cục dữ liệu đó về.

    • Nếu là App V1: BFF gọi một hàm Transformer (Data Mapper). Hàm này sẽ lấy Object Address, "nghiền" nó ra thành một chuỗi (String) rồi mới đẩy về cho App cũ.

Nhờ cách này: Các Core Services (nơi chứa logic phức tạp) được giữ cực kỳ sạch sẽ, không có bất kỳ dòng lệnh if (version == 1) nào rác rưởi. Tất cả sự lộn xộn, chuyển đổi phiên bản đều bị nhốt vào một góc riêng biệt ở tầng BFF.

Lời khuyên "xương máu" về vòng đời (Lifecycle)

Đừng duy trì phiên bản cũ mãi mãi. Nếu bạn cứ giữ V1, V2, V3... đến V10, đội Dev của bạn sẽ chết chìm trong đống code duy trì (Legacy Code).

  • Thông báo khai tử (Deprecation): Khi ra mắt V3, hãy thêm Header Deprecation: true vào các response của V1.

  • Force Update (Ép cập nhật): Hãy code tính năng này vào Mobile App ngay từ ngày đầu tiên. Khi số lượng người dùng V1 rớt xuống dưới 5%, hãy bật cờ Force Update. App V1 lúc này khi mở lên sẽ bật ra popup: "Phiên bản của bạn đã quá cũ, vui lòng cập nhật để tiếp tục" và không cho dùng nữa. Lúc đó, bạn có thể tự tin xóa sạch code V1 khỏi hệ thống.

Tạm kết

Với API Versioning, chúng ta đã giải quyết được bài toán phát triển hệ thống mà không làm gián đoạn trải nghiệm của người dùng cũ.

Nhưng, nếu bạn để ý, từ bài 1 đến bài 20, chúng ta liên tục nói về chuyện "chia nhỏ", "tách rời", "độc lập". 20 cái Services đang hoạt động vô cùng hiệu quả. Tuy nhiên, điều tồi tệ nhất của sự "chia nhỏ" là Tìm kiếm dữ liệu.

Giả sử bạn cần làm một thanh Search để tìm: "Tất cả các giao dịch của người dùng A (Service 1) mua vé loại B (Service 2) trong tháng 10 (Service 3)". Bạn không thể viết lệnh JOIN giữa 3 cái Database của 3 Services khác nhau được.

Làm sao để tìm kiếm siêu tốc (Full-text search) xuyên suốt các Microservices? Ở bài tiếp theo (Bài 21), chúng ta sẽ mang cỗ máy tìm kiếm hạng nặng Elasticsearch – "Kính lúp" của kiến trúc phân tán vào hệ thống.

Anh em ở công ty đang chia version API bằng URL hay Header? Có từng bị sếp chửi vì lỡ xóa code V1 mà quên khách hàng vẫn đang dùng chưa? Cùng kể chuyện nhé!


All Rights Reserved

Viblo
Let's register a Viblo Account to get more interesting posts.