OpenApi - Bài viết này là một phần của loạt bài.
Ở bài đầu tiên trong loạt bài này, tôi đã giải thích vì sao các đội nên thống nhất một bản hợp đồng API (contract) theo chuẩn OpenAPI trước khi ai bắt tay vào viết mã. Bài này nói về công cụ giúp bản hợp đồng đó thực sự phát huy tác dụng: Orval.
Tự tay viết lớp gọi API cho frontend là một trong những việc chẳng ai dám nhận là mình thích. Bạn chép các kiểu dữ liệu (type) từ tài liệu của backend, viết đi viết lại hàm bọc (wrapper) cho yêu cầu lần thứ bốn mươi, rồi ba tuần sau có ai đó đổi tên một trường và thế là một nửa số chỗ gọi API của bạn âm thầm hỏng. Orval xóa sổ luôn công việc đó. Chỉ cần trỏ nó tới bản đặc tả (spec) OpenAPI, Orval sẽ sinh mã máy khách cho bạn: hàm có định kiểu cho từng endpoint, mô hình dữ liệu khớp chính xác với hợp đồng, và cả dữ liệu giả lập (mock) để bạn phát triển trước khi backend kịp làm xong.
Vì sao đội frontend thích Orval#
Phần sinh dữ liệu giả lập là phần bị đánh giá thấp nhất. Một khi đặc tả đã chốt, frontend có thể dựng một máy chủ giả rồi làm toàn bộ giao diện dựa trên nó, thay vì ngồi chờ những endpoint lúc nào cũng “sắp xong rồi”. Khi backend thật được triển khai, bạn chỉ việc trỏ máy khách sang đó và gần như mọi thứ chạy được luôn, vì cả hai bên đều làm dựa trên cùng một tài liệu.
Cái lợi còn lại là phần mã nhàm chán giờ đúng ngay từ khi được sinh ra. Không còn ai gõ nhầm tên trường trong phần thân yêu cầu (request body) tự viết, vì đơn giản là chẳng còn ai phải tự viết phần đó nữa.
Vì sao đội backend cũng thích#
Khi bản đặc tả là nguồn dữ liệu gốc duy nhất, những trao đổi hằng ngày giữa hai bên cũng thay đổi hẳn. Thay vì những chuỗi tin nhắn kiểu “endpoint này trả về gì ấy nhỉ?”, frontend chỉ việc đọc các kiểu dữ liệu đã được sinh ra. Lập trình viên backend ít bị làm phiền hơn, mà lại nhận được góp ý sớm hơn: nếu frontend làm dựa trên dữ liệu giả lập rồi thấy API có chỗ nào khó dùng, bạn sẽ biết ngay từ lúc sửa còn rẻ, chứ không phải đợi đến khi nó đã lên môi trường production.
Orval nằm ở đâu trong quy trình làm việc#
Chẳng có gì cầu kỳ cả. Backend đề xuất bản đặc tả, hai đội cùng rà soát, frontend dùng Orval để sinh mã máy khách và dữ liệu giả lập rồi bắt đầu làm, còn backend thì hiện thực các endpoint thật theo đúng hợp đồng đó. Khi đặc tả thay đổi, cả hai bên sinh lại mã, và trình biên dịch sẽ chỉ ra chính xác chỗ nào bị hỏng. Phần cuối đó mới là mấu chốt: những chỗ lệch nhau giữa frontend và backend sẽ hiện ra thành lỗi biên dịch, thay vì thành lỗi trên production.
Đây không phải loại công cụ hào nhoáng gì. Nó chỉ lặng lẽ dẹp bỏ cả một kiểu tranh cãi giữa các đội, và lần nào có cơ hội đổi như vậy, tôi cũng sẵn lòng.