How the Miro Developer Platform leverages contract testing

Miro · 2023 · 3. Quy mô lớn · Độ khó: Trung bình — bài gốc

Bối cảnh

• Miro Developer Platform 2.0 (REST API công khai) ra mắt năm trước đó; đội muốn nâng chất lượng và tính nhất quán của API bằng cách làm design-first: thiết kế API (file OpenAPI, OAS) trước khi cài đặt.
• Trước đây OAS sinh từ code bằng annotation trên controller/model. Cách đó từng giúp bỏ việc viết tài liệu tay, nhưng theo Miro rất chắp vá, và bản API đầu không theo chuẩn OpenAPI (endpoint xung đột, model quá phức tạp).
• Đổi nguồn sự thật sang file OAS viết tay thì mất bảo đảm cũ: khi OAS sinh từ code, ít nhất endpoint được mô tả là có thật; giờ không gì cho biết OAS khớp với API đang chạy.

Thay đổi chính

• Bỏ ý tưởng tái dùng test end-to-end: thêm kiểm schema vào e2e vẫn dựa vào con người (endpoint mới không có test, tham số mới ngoài đường quan trọng không được cập nhật, API thử nghiệm chưa có test). Viết bộ test riêng cho việc khớp OAS thì cùng lỗi và làm lại việc.
• Sinh test từ chính OAS: OAS đủ dữ liệu để dựng request (từ schema và giá trị example/default) và kiểm schema của response. Với một tài nguyên: tìm endpoint tạo, lưu id, dùng cho các endpoint đọc/sửa, xoá cuối cùng.
• Thứ tự gọi: bản đầu sắp theo "mức tài nguyên + method" (POST trước, DELETE sau; board trước widget) chạy được cho proof of concept nhưng vỡ khi có 3 mức trở lên, khi POST không tạo tài nguyên (gắn tag vào item), khi có ràng buộc thêm (parent_item_id). Chuyển sang đồ thị phụ thuộc dựng quanh từng endpoint: mỗi tham số bắt buộc trong path trỏ tới node "tạo" tài nguyên đó (tạo node rỗng nếu chưa gặp); endpoint xoá để riêng vào "cleanup queue" sắp theo mức. Sắp xếp rút về BFS rồi xả cleanup queue; node có nhiều cha thì chỉ cha xuất hiện sau cùng giữ nó, tránh tạo trùng (tag trùng bị trả 400).
• Giới hạn còn lại: tài nguyên không tạo được qua API (tổ chức của Enterprise API) phải tạo trước; tham số như tag_id, parent_id hay tài nguyên nhắc trong body phải được map tay.
• Kiến trúc: file OAS, thư viện sinh test (chỉ đổi khi cần tính năng cho mọi bộ test, ví dụ test thiếu tham số bắt buộc), phần tạo thành phần tự động, và test. Mọi tuỳ biến (map tham số, retry cho endpoint) qua plugin do chủ API viết.
• Bộ test chạy theo lịch và báo kết quả cho team; nhờ đó tài liệu được xuất bản tự động ngay sau thay đổi, kể cả gỡ endpoint đánh dấu draft khỏi OAS công khai.

Vì sao

• Khi tài liệu là hợp đồng với khách bên ngoài, độ lệch giữa tài liệu và API là lỗi sản phẩm; kiểm bằng test sinh tự động không phụ thuộc việc ai đó nhớ viết test.

Bài học cho SWE

• Đổi nguồn sự thật (code → đặc tả) thì phải dựng lại cơ chế kiểm tra mà nguồn cũ cho miễn phí.
• Test sinh từ đặc tả phủ mọi endpoint theo định nghĩa; phần khó là thứ tự và dữ liệu, giải bằng đồ thị phụ thuộc thay vì luật sắp xếp cố định.
• Cùng hướng "đặc tả làm bộ test": Cloudflare dùng test suite của Next.js làm đặc tả cho bản viết lại (Cloudflare 2026); Stripe dùng đầu vào lịch sử (Stripe 2026).

Liên quan

• Miro 2020 · Coinbase 2026 (sinh mọi bề mặt API từ một contract) · Yelp 2026
• Kiểm thử độ tin cậy (chaos, fault injection, mô phỏng tất định)