Nền tảng API quy trình thiết kế API trước

Tóm tắt

Cách tiếp cận thiết kế trước (design-first) có nghĩa là đặc tả API của bạn được viết trước mã triển khai – và đặc tả này định hướng mọi thứ sau đó: mock, tài liệu, kiểm thử và client stubs. Việc lựa chọn một nền tảng hỗ trợ quy trình làm việc này từ đầu đến cuối sẽ loại bỏ sự cọ xát liên tục trong việc giữ mã và tài liệu đồng bộ. Bài viết này giải thích cách tiếp cận thiết kế trước và đánh giá những công cụ tốt cần có, với Apidog là một nền tảng thiết kế trước hoàn chỉnh.

ApidogDùng thử Apidog miễn phí

Giới thiệu

Hầu hết các nhà phát triển học cách xây dựng API theo cách code-first (viết mã trước). Bạn viết một route, thêm một số annotation, chạy một bộ tạo và nhận được tài liệu. Nó hoạt động. Cho đến khi nó không còn hoạt động.

Tài liệu bị lệch. Các annotation trở nên lỗi thời. Một kỹ sư mới thay đổi định dạng phản hồi nhưng quên cập nhật decorator. Sáu tháng sau, tài liệu nói rằng API trả về một mảng chuỗi, và phản hồi thực tế trả về một mảng đối tượng với một trường value.

Thiết kế trước đảo ngược điều này. Đặc tả là nguồn chân lý duy nhất. Mã, tài liệu và mock đều được tạo ra từ nó. Khi đặc tả thay đổi, mọi thứ thay đổi cùng nhau – vì mọi thứ đều được tạo ra từ nó.

Đây không phải là một sự khác biệt mang tính lý thuyết. Các nhóm áp dụng thiết kế trước báo cáo ít bất ngờ về tích hợp hơn, phát triển frontend nhanh hơn (vì mock có sẵn ngay từ ngày đầu), và tài liệu chính xác vì nó không bao giờ là một sản phẩm phụ.

Nhưng thiết kế trước yêu cầu các công cụ giúp viết đặc tả đủ nhanh để trở nên thực tế. Nếu việc định nghĩa một endpoint trong công cụ đặc tả của bạn mất 20 phút và viết bộ xử lý route mất 5 phút, sẽ không ai sử dụng công cụ đặc tả. Nền tảng phải làm cho thiết kế trước nhanh hơn code-first, chứ không phải chậm hơn.

Thiết kế trước có nghĩa là gì trong thực tế

Thiết kế trước là một quy trình làm việc, không phải một công nghệ. Dưới đây là cách nó trông ở mỗi giai đoạn phát triển API:

Trước khi viết bất kỳ mã nào

Thiết kế API được định nghĩa dưới dạng đặc tả OpenAPI. Điều này bao gồm:

• Tất cả các đường dẫn endpoint và phương thức HTTP
• Định nghĩa tham số yêu cầu (path, query, header)
• Schema của request body cho các endpoint POST/PUT/PATCH
• Schema phản hồi cho tất cả các mã trạng thái (200, 400, 401, 422, 500)
• Yêu cầu xác thực
• Mô tả trường và ví dụ

Đánh giá thiết kế này là nơi đưa ra hầu hết các quyết định quan trọng: đặt tên, cấu trúc dữ liệu, các mẫu xử lý lỗi.

Trong quá trình phát triển

Đặc tả được xuất bản lên một máy chủ mock. Kỹ sư frontend xây dựng dựa trên mock. Kỹ sư backend triển khai dựa trên đặc tả, coi nó như tài liệu yêu cầu của họ. Cả hai nhóm làm việc song song mà không cản trở lẫn nhau.

Sau khi triển khai

Các bài kiểm thử tự động xác thực rằng triển khai thực tế khớp với đặc tả. Mọi sai lệch so với hợp đồng sẽ khiến bài kiểm thử thất bại.

Khi yêu cầu thay đổi

Đặc tả được cập nhật trước. Cả hai nhóm xem xét sự thay đổi. Mock tự động cập nhật. Các bài kiểm thử gắn cờ bất kỳ triển khai nào không tuân theo đặc tả đã cập nhật.

Những gì một nền tảng thiết kế trước cần

Không phải mọi công cụ API đều hỗ trợ quy trình làm việc thiết kế trước. Dưới đây là những gì phân biệt các công cụ hỗ trợ và không hỗ trợ.

Trình chỉnh sửa API trực quan

YAML thô là một phương tiện thiết kế kém. Một trình chỉnh sửa trực quan cho phép bạn tập trung vào cấu trúc và ngữ nghĩa API mà không phải vật lộn với thụt lề YAML. Trình chỉnh sửa phải tạo ra OpenAPI hợp lệ, hỗ trợ tái sử dụng schema (các thành phần) và xác thực theo thời gian thực.

Xác thực OpenAPI

Đặc tả phải là OpenAPI hợp lệ trước khi nó được sử dụng cho bất kỳ mục đích nào. Xác thực nội tuyến bắt lỗi trong quá trình chỉnh sửa thay vì lúc tạo mã hoặc tạo mock.

Tạo mock tự động từ đặc tả

Viết đặc tả, nhận mock. Không cần thêm bước nào. Mock phải trả về dữ liệu tuân thủ các loại trường, định dạng và ràng buộc từ schema. Đây là điều làm cho việc phát triển song song trở nên thực tế.

Xem trước tài liệu với các ví dụ thực tế

Đặc tả phải được hiển thị thành tài liệu dễ đọc mà bạn có thể chia sẻ với các bên liên quan trong giai đoạn thiết kế. Các thành viên nhóm không chuyên về kỹ thuật cũng có thể đọc và đưa ra phản hồi.

Quy trình đánh giá nhóm

Thiết kế trước xử lý các thay đổi đặc tả giống như các thay đổi mã: ai đó đề xuất một thay đổi, những người khác xem xét, nó được phê duyệt hoặc sửa đổi. Nền tảng cần khả năng bình luận không đồng bộ và theo dõi thay đổi.

Xuất sang OpenAPI tiêu chuẩn

Đặc tả phải có thể di chuyển được. Bạn có thể xuất nó sang OpenAPI tiêu chuẩn và sử dụng nó với bất kỳ công cụ hạ nguồn nào: bộ tạo mã, API gateway, framework kiểm thử.

Apidog như một nền tảng thiết kế trước

Kiến trúc của Apidog được xây dựng xung quanh đặc tả như một thành phần chính. Tab thiết kế, máy chủ mock, bộ chạy kiểm thử và tài liệu đều được kết nối với cùng một định nghĩa API cơ bản.

Trình chỉnh sửa OpenAPI trực quan

Giao diện thiết kế của Apidog sử dụng chỉnh sửa dựa trên biểu mẫu. Mỗi endpoint là một biểu mẫu có cấu trúc: đường dẫn, phương thức, tham số, request body, phản hồi. Các trường schema được định nghĩa bằng bộ chọn loại, trình chỉnh sửa mô tả, quy tắc xác thực và annotation mock.

Bạn không cần phải viết YAML trừ khi bạn muốn. Apidog cung cấp chế độ xem thô hiển thị biểu diễn YAML hoặc JSON của đặc tả và cho phép bạn chỉnh sửa trực tiếp nếu bạn thích. Các thay đổi trong chế độ xem trực quan đồng bộ hóa với chế độ xem thô và ngược lại.

Các thành phần Schema là hạng nhất. Định nghĩa một schema UserProfile trong phần components. Tham chiếu nó bằng $ref trong bất kỳ endpoint nào. Thay đổi schema một lần, và mọi endpoint tham chiếu nó đều phản ánh sự thay đổi.

Xem trước tài liệu theo thời gian thực

Khi bạn thiết kế một endpoint, chế độ xem tài liệu cập nhật theo thời gian thực. Bạn có thể xem trước cách endpoint sẽ xuất hiện trong tài liệu đã xuất bản mà không cần rời khỏi giao diện thiết kế. Bản xem trước hiển thị các mô tả đã render, bảng schema với các loại trường và ràng buộc, cùng các ví dụ phản hồi.

Chia sẻ liên kết tài liệu với các quản lý sản phẩm hoặc trưởng nhóm frontend trong giai đoạn thiết kế để đánh giá. Họ không cần cài đặt bất cứ thứ gì.

Smart Mock: từ đặc tả đến mock hoạt động

Khi bạn lưu một endpoint mới trong trình thiết kế của Apidog, máy chủ mock sẵn sàng ngay lập tức. URL mock xuất hiện trong giao diện. Mock tạo dữ liệu phản hồi dựa trên schema của bạn:

• Các trường chuỗi với format: email trả về địa chỉ email hợp lệ
• Các trường số nguyên với minimum và maximum trả về giá trị trong phạm vi
• Các trường Enum trả về các giá trị enum được chọn ngẫu nhiên
• Các đối tượng và mảng lồng nhau tuân theo cấu trúc schema lồng nhau
• Các thành phần $ref được giải quyết và mock đúng cách

Bạn cũng có thể đặt các quy tắc mock tùy chỉnh cho các kịch bản cụ thể: trả về 404 khi tham số đường dẫn là 0, hoặc trả về một payload cụ thể cho một giá trị tham số truy vấn cụ thể.

Đánh giá nhóm và theo dõi thay đổi

Các thay đổi đặc tả API trong Apidog hiển thị cho tất cả các thành viên không gian làm việc. Bình luận có thể được thêm vào các endpoint hoặc trường cụ thể. Lịch sử thay đổi theo dõi ai đã thay đổi gì và khi nào.

Đối với quy trình làm việc thiết kế trước, điều này có nghĩa là các thay đổi đặc tả trải qua cùng một văn hóa đánh giá như các thay đổi mã, mà không yêu cầu một công cụ hoặc quy trình riêng biệt.

Thiết kế trước so với Mã trước: Những đánh đổi thực tế

Thiết kế trước không phải là vượt trội hoàn toàn. Dưới đây là một so sánh trung thực.

Ưu điểm của thiết kế trước:

• Frontend và backend có thể làm việc song song (lợi ích lớn về tốc độ)
• Tài liệu chính xác vì nó là nguồn gốc, không phải sản phẩm phụ
• Các vấn đề tích hợp xuất hiện sớm, trong quá trình đánh giá thiết kế, chứ không phải muộn, trong quá trình tích hợp
• Các hợp đồng API rõ ràng và có thể kiểm chứng
• Các thay đổi đối với API trải qua quy trình đánh giá theo mặc định

Nhược điểm của thiết kế trước:

• Tốn thời gian ban đầu để định nghĩa đặc tả trước khi viết mã
• Các công cụ đặc tả có đường cong học tập
• Yêu cầu kỷ luật để giữ cho việc triển khai đồng bộ với đặc tả
• Đặc tả quá chi tiết sớm có thể khóa bạn vào các quyết định trước khi bạn hiểu rõ miền

Ưu điểm của mã trước:

• Phát triển ban đầu nhanh hơn cho các dự án nhỏ, thử nghiệm
• Ít quy trình hơn cho các nhà phát triển độc lập lặp lại nhanh chóng
• Không cần học công cụ đặc tả

Nhược điểm của mã trước:

• Tài liệu luôn là một sản phẩm phụ và có xu hướng bị lệch
• Frontend phải đợi backend trước khi công việc tích hợp có thể bắt đầu
• Hợp đồng ngầm định, khiến việc phát hiện các thay đổi phá vỡ trở nên khó khăn hơn
• Refactoring API yêu cầu cập nhật tài liệu thủ công

Đối với các nhóm có nhiều hơn một kỹ sư làm việc trên một API, thiết kế trước thường mang lại kết quả tốt hơn. Kỷ luật đặc tả trước phát huy tác dụng nhất trong các tính năng đòi hỏi sự phối hợp đáng kể giữa frontend và backend.

Các công cụ hỗ trợ quy trình làm việc thiết kế trước

Apidog

Nền tảng thiết kế trước hoàn chỉnh: trình chỉnh sửa trực quan, tạo mock tức thì, tài liệu, kiểm thử và đánh giá nhóm trong một công cụ. Gói miễn phí bao gồm đầy đủ các tính năng. Khả năng tạo mock mạnh mẽ là một yếu tố khác biệt thực sự.

Stoplight Studio

Trình chỉnh sửa OpenAPI tốt nhất trong phân khúc với tính năng linting Spectral để thực thi kiểu. Không có máy chủ mock hoặc bộ chạy kiểm thử tích hợp. Tốt nhất cho các tổ chức cần công cụ quản trị. Đắt đối với các nhóm nhỏ.

SwaggerHub

Nền tảng chỉnh sửa và cộng tác OpenAPI đã trưởng thành. Được sử dụng rộng rãi trong doanh nghiệp. Khả năng mock hạn chế. Không có kiểm thử. Tốt cho các tổ chức tập trung vào đặc tả đã có trong hệ sinh thái Swagger.

Postman (với API Builder)

Postman có một tab thiết kế API tạo ra các đặc tả OpenAPI, nhưng quy trình làm việc thiết kế và collection có vẻ không liên kết. Máy chủ mock yêu cầu thiết lập thủ công từ các collection chứ không tự động tạo từ đặc tả. Hoạt động cho các nhóm code-first muốn có một số công cụ tài liệu.

Insomnia (với chế độ tài liệu)

Insomnia hỗ trợ chỉnh sửa đặc tả OpenAPI và cung cấp một mock cơ bản. Ít bóng bẩy hơn so với các công cụ thiết kế trước chuyên dụng. Tốt cho các nhà phát triển độc lập muốn có một tùy chọn nhẹ.

Thiết lập quy trình làm việc thiết kế trước trong Apidog

Bước 1: Bắt đầu với đặc tả, không phải collectionTạo một dự án mới và mở tab thiết kế. Hạn chế việc bắt đầu trong trình tạo yêu cầu. Định nghĩa ít nhất đường dẫn endpoint, phương thức và schema phản hồi trước khi bạn gửi một yêu cầu nào.

Bước 2: Định nghĩa các thành phần dùng chung trướcTrước khi thêm các endpoint, hãy định nghĩa các schema sẽ được sử dụng lại: định dạng phản hồi lỗi, trình bao phân trang, các trường thực thể chung. Điều này ngăn ngừa sự không nhất quán sau này.

Bước 3: Lấy URL mock sớmSao chép URL mock ngay khi endpoint được lưu. Chia sẻ nó với kỹ sư frontend. Họ có thể bắt đầu xây dựng dựa trên nó ngay lập tức.

Bước 4: Đánh giá tài liệu trước khi viết mãXem trước tài liệu được tạo. Nếu mô tả trường không rõ ràng trong tài liệu, nó sẽ không rõ ràng với tất cả những ai đọc mã. Sửa nó trong đặc tả.

Bước 5: Khóa đặc tả trước khi bắt đầu triển khaiSau khi đánh giá thiết kế hoàn tất và các bình luận được giải quyết, hãy coi đặc tả là đã khóa cho sprint đó. Các thay đổi triển khai yêu cầu cập nhật đặc tả phải trải qua quy trình đánh giá, chứ không được thực hiện một cách lặng lẽ.

Bước 6: Chạy kiểm thử xác thực schema trong CIThiết lập bộ kiểm thử của Apidog để xác thực schema phản hồi trên mỗi lần chạy CI. Đây là hàng rào bảo vệ tự động giúp giữ cho việc triển khai và đặc tả đồng bộ.

Câu hỏi thường gặp

Thiết kế trước chỉ dành cho REST API?Không. Nguyên tắc thiết kế trước áp dụng cho bất kỳ giao thức nào mà bạn có thể định nghĩa một hợp đồng: GraphQL schema-first, gRPC với protobuf, AsyncAPI cho các hệ thống hướng sự kiện. Apidog hỗ trợ thiết kế REST và GraphQL. Đối với gRPC, các tệp proto phục vụ cùng mục đích hợp đồng trước.

Chúng ta có cần định nghĩa mọi endpoint trước khi bắt đầu phát triển không?Không. Bạn có thể áp dụng thiết kế trước ở cấp độ tính năng: định nghĩa đặc tả cho tính năng bạn sắp xây dựng trước khi viết mã, ngay cả khi các phần khác của codebase là code-first. Việc áp dụng tăng dần vẫn hoạt động.

Thiết kế trước hoạt động như thế nào với các sprint linh hoạt?Các buổi thiết kế vào đầu sprint định nghĩa hợp đồng API cho các tính năng của sprint đó. Frontend và backend làm việc song song trong sprint. Đánh giá đặc tả trở thành một phần của lập kế hoạch sprint.

Nếu việc triển khai cần phải khác với đặc tả ban đầu thì sao?Điều đó có thể xảy ra. Quy trình đúng là cập nhật đặc tả trước, đạt được sự đồng thuận từ các bên liên quan (đặc biệt là frontend), sau đó cập nhật việc triển khai. Điều này giữ cho đặc tả là nguồn chân lý duy nhất thay vì việc triển khai.

Chúng ta có thể tạo server stubs từ xuất OpenAPI của Apidog không?Có. Xuất đặc tả từ Apidog dưới dạng OpenAPI 3.x, sau đó sử dụng bất kỳ trình tạo mã tiêu chuẩn nào để tạo server stubs. openapi-generator hỗ trợ hơn 50 ngôn ngữ và framework server.

Chúng ta xử lý việc lập phiên bản đặc tả như thế nào?Apidog duy trì lịch sử thay đổi trong một dự án. Đối với các thay đổi phiên bản lớn được duy trì song song (v1 và v2 đều hoạt động), các dự án hoặc nhánh riêng biệt hoạt động tốt.

Thiết kế trước đòi hỏi một khoản đầu tư nhỏ vào kỷ luật ban đầu và mang lại lợi ích đáng kể trong việc giảm chi phí tích hợp. Nền tảng bạn chọn phải làm cho khoản đầu tư ban đầu đó càng thấp càng tốt. Nếu việc viết đặc tả gây khó khăn, các nhóm sẽ bỏ qua nó. Trình chỉnh sửa trực quan của Apidog, tạo mock tức thì và xem trước tài liệu làm cho thiết kế trước trở thành con đường dễ dàng nhất chứ không phải con đường đòi hỏi nhiều nỗ lực nhất.