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à nhóm tôi ở công ty chốt lại vừa nhàm vừa hiệu quả: thống nhất 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.
Contract trước, mã nguồn sau#
Với quy trình 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 OpenAPI schema: mọi endpoint, model của request và response, 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 implement. 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 mock server thẳng từ schema, 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ế schema: endpoint, model request/response, xác thực, mã lỗi.
- Cho cả frontend lẫn backend cùng review. Đây là lúc bản hợp đồng thể hiện rõ giá trị của nó.
- Sinh mock server (Swagger và Postman đều làm được) và để frontend tích hợp với mock đó.
- Backend implement các endpoint thật theo đúng schema.
- Khi endpoint thật lần lượt xong thì thay dần mock 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. Schema 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 schema kỹ lưỡng ngay từ đầu tốn khá nhiều thời gian. Khi yêu cầu thay đổi thì schema phải đổi trước, và ảnh hưởng sẽ lan sang cả hai nhóm. 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 build hỏng.