OpenApi - Bài viết này là một phần của loạt bài.
Trong những dự án tôi từng làm, thứ làm trễ tiến độ đều đặn nhất không phải là những bài toán kỹ thuật khó, mà là cảnh frontend ngồi không chờ một endpoint “sắp xong rồi”. Cách chữa mà đội tôi ở công ty chốt lại vừa nhàm vừa hiệu quả: thống nhất hợp đồng API (API contract) bằng OpenAPI trước, rồi mới có ai bắt đầu viết mã.
Cái vòng chờ đợi#
Quy trình truyền thống thì chạy tuần tự. Backend thiết kế và xây API, và chỉ khi endpoint đã chạy được thật thì frontend mới bắt đầu tích hợp. Backend chậm ngày nào thì lịch của frontend lãnh đủ ngày đó, mà ngày phát hành thường lại phụ thuộc vào lịch của frontend.
Hợp đồng trước, mã nguồn sau#
Với quy trình đặc tả trước (schema-first), hai bên bắt đầu gần như cùng lúc. Trước khi có dòng mã nào, toàn bộ cấu trúc của API được đưa vào một bản đặc tả OpenAPI (OpenAPI schema): mọi endpoint, mô hình dữ liệu của yêu cầu và phản hồi, phương thức xác thực và mã lỗi. Tài liệu đó trở thành bản hợp đồng giữa frontend và backend.
Lợi ích thấy ngay. Trước khi tính năng được xây, ai cũng hiểu nó theo cùng một cách. Frontend có thể dựng giao diện trong lúc backend vẫn đang hiện thực các endpoint. Khi có thay đổi thì xử lý cũng nhanh hơn, vì chỉ có một nguồn thông tin chuẩn đã được thống nhất cần cập nhật. Và bạn có thể sinh máy chủ giả lập (mock server) thẳng từ bản đặc tả, nên frontend bắt đầu kiểm thử được ngay cả khi chưa có endpoint thật nào.
Áp dụng thực tế ra sao#
- Thu thập yêu cầu, như với bất kỳ việc gì khác.
- Thiết kế bản đặc tả: endpoint, mô hình yêu cầu/phản hồi, xác thực, mã lỗi.
- Cho cả frontend lẫn backend cùng rà soát. Đây là lúc bản hợp đồng thể hiện rõ giá trị của nó.
- Sinh máy chủ giả lập (Swagger và Postman đều làm được) và để frontend tích hợp với bản giả lập đó.
- Backend hiện thực các endpoint thật theo đúng bản đặc tả.
- Khi endpoint thật lần lượt xong thì thay dần bản giả lập bằng endpoint thật, đồng thời kiểm thử liên tục để chắc chắn hai bên vẫn làm đúng hợp đồng.
- Tiếp tục trao đổi với nhau. Bản đặc tả là tài liệu sống, chứ không phải thứ khắc lên bia đá.
Những điểm vướng#
Tất nhiên cách này cũng có cái giá của nó. Viết một bản đặc tả kỹ lưỡng ngay từ đầu tốn khá nhiều thời gian. Khi yêu cầu thay đổi thì bản đặc tả phải đổi trước, và ảnh hưởng sẽ lan sang cả hai đội. Ngoài ra, ai cũng cần biết dùng OpenAPI và các công cụ đi kèm ở mức cơ bản.
Dù vậy, tôi chưa từng thấy trường hợp nào mà công sức bỏ ra lúc đầu lại tốn hơn mớ hỗn loạn lúc tích hợp mà nó giúp tránh được. Frontend bắt tay vào làm từ ngày đầu tiên, còn các cuộc tranh cãi thì diễn ra trên một bản tài liệu, chứ không phải trên những bản dựng hỏng.