Bruno ưu tiên request trước ư? Đúng vậy. Bruno được xây dựng xoay quanh việc tổng hợp, tổ chức và gửi các HTTP request. Bạn tạo một bộ sưu tập, thêm request, viết chúng trong các tệp .bru của nó, chạy chúng và quản lý phiên bản toàn bộ mọi thứ trong Git. Mô hình đó nhanh, thân thiện với Git và mang lại trải nghiệm thực sự thú vị khi bạn khám phá một API đã tồn tại.
Nhưng "ưu tiên request" và "ưu tiên thiết kế" trả lời các câu hỏi khác nhau. Ưu tiên request hỏi: làm thế nào để tôi gọi endpoint này? Ưu tiên thiết kế hỏi: endpoint này nên trông như thế nào, trước khi bất kỳ ai viết mã để phục vụ nó? Khoảng cách giữa hai câu hỏi đó chính là nơi các nhóm xây dựng API mới hoặc API chia sẻ bắt đầu cảm thấy khó khăn. Bài viết này sẽ phân tích thẳng thắn sự đánh đổi giữa cách tiếp cận ưu tiên request của Bruno và cách tiếp cận ưu tiên thiết kế, sau đó chỉ ra nơi quy trình làm việc ưu tiên thiết kế, chuẩn OpenAPI phát huy tác dụng.
Ưu tiên request so với ưu tiên thiết kế, tóm tắt nhanh
Hai phương pháp này không hẳn là đối thủ cạnh tranh mà là những điểm xuất phát khác nhau. Dưới đây là phiên bản ngắn gọn.
| Khía cạnh | Ưu tiên request (Bruno) | Ưu tiên thiết kế (chuẩn OpenAPI) |
|---|---|---|
| Thành phần khởi đầu | Một request bạn có thể gửi | Một hợp đồng (OpenAPI spec) |
| Tốt nhất cho | Khám phá và kiểm thử các API hiện có | Thiết kế các API mới/chia sẻ trước khi viết code |
| Nguồn đáng tin cậy | Tập hợp các request | Spec |
| Đánh giá chéo nhóm | Sau khi các endpoint tồn tại | Trước khi viết một dòng code server |
| Giao diện thiết kế trực quan | Không có theo mặc định | Trình thiết kế trực quan + trình chỉnh sửa schema |
| Rủi ro sai lệch | Tập hợp có thể lạc hậu so với API thực tế | Spec vẫn là hợp đồng duy nhất |
| Câu chuyện về Git | Mạnh (plain-text .bru) |
Mạnh khi công cụ đồng bộ spec với Git |
Cả hai cột đều không "sai". Lựa chọn đúng đắn phụ thuộc vào việc API của bạn đã tồn tại hay bạn đang định nghĩa nó ngay bây giờ.
Mô hình ưu tiên request của Bruno
Bruno thực hiện tốt công việc của mình, và điều quan trọng là phải chính xác về công việc đó là gì. Nó lưu trữ các request dưới dạng tệp .bru văn bản thuần túy trong một thư mục mà bạn sở hữu. Không có tài khoản đám mây bắt buộc, không có đồng bộ độc quyền, không có dữ liệu đo từ xa chạy ngầm mà bạn phải từ chối. Đối với các nhà phát triển muốn client API của họ hoạt động giống như phần còn lại của codebase, đây là một lợi thế thực sự, và nó là cốt lõi của quy trình làm việc API Git-native mà nhiều nhóm đã áp dụng.
Bruno nổi bật ở đâu:
- Khám phá một API hiện có. Trỏ nó vào một dịch vụ đang chạy, gửi request, kiểm tra phản hồi, lặp lại. Vòng lặp phản hồi rất chặt chẽ.
- Ưu tiên cục bộ và thân thiện với Git. Các khác biệt dễ đọc, việc hợp nhất hợp lý và lịch sử request của bạn nằm trong cùng một PR với code của bạn.
- Viết script và kiểm thử. Các script trước và sau request, xác nhận và biến môi trường bao gồm các kiểm thử hàng ngày mà hầu hết các kỹ sư cần.
- Không bị khóa hệ thống. Định dạng mở và các tệp là của bạn.
Nếu công việc của bạn là sử dụng và xác minh các API đã tồn tại, thì ưu tiên request thường là con đường trực tiếp nhất. Chúng tôi đã từng nói điều này khi so sánh nó với các nền tảng rộng hơn trong phân tích các lựa chọn thay thế Bruno này.
Chi phí của việc không có lớp thiết kế hoặc hợp đồng
Sự đánh đổi xuất hiện ngay khi API chưa tồn tại, hoặc khi có nhiều hơn một nhóm phải thống nhất về việc nó nên trông như thế nào.
Không có trình thiết kế trực quan. Các công cụ ưu tiên request thể hiện các endpoint dưới dạng request, không phải dưới dạng mô hình tài nguyên, schema và phản hồi. Không có một canvas nào mà một kỹ sư sản phẩm, một trưởng nhóm backend và một nhà phát triển frontend có thể nhìn vào cùng một hình dạng tài nguyên và thống nhất về nó trước khi bất kỳ ai viết bộ xử lý. Thiết kế bằng request có nghĩa là thiết kế bằng các ví dụ, và các ví dụ không bắt buộc cấu trúc.
Sai lệch hợp đồng. Khi tập hợp là nguồn đáng tin cậy, nó chỉ phản ánh những gì ai đó đã gọi. API thực tế có thể thay đổi, thêm trường, loại bỏ tham số, thắt chặt xác thực, và tập hợp lặng lẽ tụt hậu cho đến khi một bài kiểm thử thất bại. Một quy trình làm việc tập trung vào spec đảo ngược điều này: hợp đồng là tài liệu tham khảo, và việc triển khai được kiểm tra dựa trên nó.
Đánh giá chéo nhóm khó hơn trước khi viết code. Việc xem xét một thư mục các request cho bạn biết cách các endpoint đang được gọi ngày nay. Nó không cung cấp cho người đánh giá một tài liệu khai báo rõ ràng để phê duyệt trước khi triển khai. Đối với các nhóm quản lý thay đổi API thông qua đánh giá thiết kế, việc thiếu một hợp đồng hạng nhất khiến việc đánh giá đó chậm hơn và tùy tiện hơn.
Không điều nào trong số này làm cho Bruno trở thành một công cụ kém. Nó chỉ biến Bruno thành một công cụ ưu tiên request được sử dụng ngoài công việc mà nó được thiết kế cho mục đích ưu tiên request.
Khi ưu tiên thiết kế giành chiến thắng
Ưu tiên thiết kế mang lại lợi ích đặc biệt trong ba tình huống:
- API mới hoàn toàn. Khi chưa có gì tồn tại, spec là thiết kế. Bạn định nghĩa tài nguyên, schema và các hình dạng lỗi một lần, sau đó tạo stub server, mock và tài liệu từ hợp đồng duy nhất đó thay vì phải tái thiết kế chúng từ các request sau này.
- Hợp đồng đa nhóm. Khi một nhóm backend và một hoặc nhiều nhóm client phải thống nhất, OpenAPI spec là thỏa thuận. Frontend có thể xây dựng dựa trên mock ngay khi hợp đồng được phê duyệt, song song với việc triển khai backend, thay vì chờ đợi các endpoint thực tế.
- API công cộng. Khi các nhà phát triển bên ngoài phụ thuộc vào bạn, sự ổn định và tài liệu rõ ràng là sản phẩm. Một hợp đồng được duy trì cung cấp cho bạn các tài liệu tham khảo được tạo tự động, kỷ luật quản lý phiên bản và một cách để truyền đạt các thay đổi gây phá vỡ một cách có chủ ý.
Điểm chung: ưu tiên thiết kế thắng thế khi API là một giao diện chia sẻ cần sự thống nhất trước khi viết code, chứ không chỉ là một dịch vụ bạn đang kiểm tra sau khi nó được triển khai.
Apidog ưu tiên thiết kế cộng với Chế độ Spec-First
Apidog được xây dựng theo hướng ưu tiên thiết kế, và điểm liên quan ở đây là bạn không cần phải từ bỏ trải nghiệm chuẩn OpenAPI, thân thiện với Git để đạt được điều đó.
Bạn có thể làm việc theo hai cách trên cùng một dự án. Trình thiết kế trực quan để định nghĩa các endpoint, schema request và response, và các thành phần có thể tái sử dụng mà không cần viết tay YAML, đây là điều mà hầu hết mọi người hình dung khi nghe "ưu tiên thiết kế". Và có Chế độ Spec-First, một trình chỉnh sửa code nơi bạn tạo tài liệu OpenAPI trực tiếp, với spec là nguồn đáng tin cậy. Hai chế độ này được giữ đồng bộ, vì vậy một kỹ sư backend có thể làm việc với OpenAPI thô trong khi một kỹ sư sản phẩm làm việc trên canvas, và họ đang chỉnh sửa cùng một hợp đồng.
Chế độ Spec-First cũng hỗ trợ đồng bộ Git hai chiều: spec nằm trong kho lưu trữ của bạn dưới dạng một tệp thực, các thay đổi luân chuyển theo cả hai hướng, và thiết kế API của bạn di chuyển qua cùng các pull request và đánh giá như code của bạn. Đó là thuộc tính Git-native mà người dùng Bruno đánh giá cao, áp dụng cho hợp đồng chứ không phải cho một tập hợp các request. Các cơ chế đầy đủ có trong tài liệu Chế độ Spec-First.
Kết quả là một quy trình làm việc bao gồm cả hai câu hỏi: thiết kế hợp đồng trước khi bạn cần, và vẫn kiểm thử dựa trên nó như một client ưu tiên request khi các endpoint đã hoạt động. Để hiểu sâu hơn về nơi các mô hình này gặp nhau, hãy xem spec-first vs design-first trong Apidog.
Lựa chọn theo mức độ trưởng thành của nhóm
Một cách đơn giản để quyết định: khớp công cụ với vị trí của API trong vòng đời của nó, không phải theo sở thích.
- Đội ngũ solo hoặc nhỏ, chủ yếu sử dụng API. Ưu tiên request là đủ. Mô hình ưu tiên cục bộ của Bruno không cản trở bạn, và bạn không phải chịu gánh nặng duy trì một hợp đồng chính thức mà bạn không cần.
- Đội ngũ đang phát triển, triển khai API của riêng mình. Đây là điểm uốn. Khi một nhóm thứ hai phụ thuộc vào các endpoint của bạn, một tập hợp không chính thức sẽ ngừng mở rộng và một hợp đồng rõ ràng bắt đầu giúp bạn tiết kiệm chu kỳ đánh giá và lỗi tích hợp.
- Tổ chức trưởng thành với API công cộng hoặc nhiều API nội bộ. Ưu tiên thiết kế thực sự cần thiết. Spec trở thành quản trị, tài liệu và quy trình giới thiệu tất cả cùng một lúc, và một công cụ chuẩn OpenAPI với đồng bộ Git giữ cho nó trung thực.
Đánh giá thẳng thắn về ưu tiên request của Bruno so với ưu tiên thiết kế là sự trưởng thành, chứ không phải sở thích, thường quyết định. Các nhóm có xu hướng bắt đầu với ưu tiên request và phát triển thành ưu tiên thiết kế khi API của họ trở thành những hợp đồng mà người khác dựa vào.
Câu hỏi thường gặp
Bruno là ưu tiên request hay ưu tiên thiết kế?
Bruno là ưu tiên request. Mô hình cốt lõi của nó là tổng hợp, tổ chức và gửi các request được lưu trữ dưới dạng tệp văn bản thuần túy, lý tưởng cho việc khám phá và kiểm thử các API đã tồn tại. Nó không tập trung vào việc tạo ra một hợp đồng OpenAPI trước khi API được xây dựng.
Tôi có thể thực hiện công việc ưu tiên thiết kế trong Bruno không?
Không tự nhiên theo cách mà một công cụ tập trung vào spec thực hiện. Bruno tập trung vào các request chứ không phải vào trình thiết kế trực quan hoặc tài liệu OpenAPI như nguồn đáng tin cậy. Nếu bạn cần định nghĩa và đánh giá một hợp đồng trước khi viết code, một công cụ ưu tiên thiết kế, chuẩn OpenAPI phù hợp hơn với công việc đó.
Tôi có phải từ bỏ tính thân thiện với Git để chuyển sang ưu tiên thiết kế không?
Không. Thuộc tính Git-native, các tệp văn bản thuần túy trong kho lưu trữ của bạn, các khác biệt dễ đọc, đánh giá thông qua PR, có thể áp dụng cho chính spec đó. Chế độ Spec-First của Apidog giữ tài liệu OpenAPI trong kho lưu trữ của bạn với đồng bộ hai chiều, vì vậy ưu tiên thiết kế không có nghĩa là bỏ qua Git.