Hợp đồng API của bạn có lẽ đang nằm ở ba nơi cùng một lúc. Một sơ đồ trong wiki. Một bộ sưu tập Postman mà ai đó đã xuất khẩu quý trước. Một tài liệu Markdown viết tay đã bị lệch so với dịch vụ đang chạy từ hai bản phát hành trước. Khi ba thứ này không thống nhất, nhóm của bạn sẽ phải đoán mò. Đoán mò làm hỏng các tích hợp.
Coi đặc tả API của bạn như code sẽ khắc phục điều này. Bạn viết một tệp OpenAPI, commit nó vào Git và đánh giá nó giống như bất kỳ tệp nguồn nào khác. Từ một tệp duy nhất đó, bạn tạo ra các mock, kiểm thử, tài liệu và SDK. Đặc tả không còn là một việc làm thêm mà trở thành hợp đồng mà mọi người xây dựng dựa trên đó.
Hướng dẫn này giải thích ý nghĩa của "spec-as-code", tại sao tệp OpenAPI xứng đáng được kiểm soát chặt chẽ như code ứng dụng của bạn, và cách vận hành quy trình làm việc mà không gặp khó khăn với các công cụ của bạn.
Spec-as-code nghĩa là gì
Spec-as-code có nghĩa là định nghĩa API của bạn là một tệp văn bản thuần túy nằm trong hệ thống kiểm soát phiên bản. Không phải là một bản ghi cơ sở dữ liệu. Không phải là một tài liệu được lưu trữ trực tuyến với liên kết chia sẻ. Đó là một tệp mà bạn có thể `git diff`, phân nhánh (branch) và hợp nhất (merge).
Ý tưởng này vay mượn trực tiếp từ docs-as-code, nơi tài liệu nằm trong cùng kho lưu trữ với mã mà nó mô tả và được phân phối qua cùng một quy trình. Spec-as-code áp dụng nguyên tắc tương tự cho chính hợp đồng API. Tài liệu OpenAPI (YAML hoặc JSON) là sản phẩm chính. Mọi thứ khác ở hạ nguồn đều được tạo ra từ nó.
Sự thay đổi đó có một hệ quả lớn. Đặc tả trở thành nguồn đáng tin cậy duy nhất. Khi một nhà phát triển muốn biết `/users/{id}` trả về gì, họ đọc đặc tả, chứ không phải một trang wiki lỗi thời. Khi QA viết một kiểm thử, họ khẳng định dựa trên đặc tả. Khi một đối tác tích hợp, họ lấy một SDK được tạo ra từ đặc tả. Một tệp, nhiều đầu ra.
Tại sao phải coi đặc tả như mã nguồn
Một khi đặc tả là một tệp trong Git, bạn sẽ kế thừa mọi quy trình làm việc mà bạn đã tin tưởng đối với mã nguồn.
Đánh giá trong yêu cầu kéo (pull request). Một thay đổi đối với một endpoint sẽ xuất hiện dưới dạng khác biệt (diff) trong một PR. Người đánh giá sẽ thấy chính xác những trường nào đã thay đổi, mã trạng thái nào đã được thêm vào, và liệu hình dạng phản hồi có làm hỏng khả năng tương thích ngược hay không. Một thay đổi gây lỗi không còn là một bất ngờ trong môi trường sản xuất. Đó là một chuỗi bình luận trước khi hợp nhất. Đây là cốt lõi của quy trình làm việc API Git-native.
Định dạng thân thiện với diff. Các file YAML thuần túy hiển thị sự khác biệt một cách rõ ràng. Bạn có thể đọc một thay đổi gồm năm dòng và hiểu nó trong vài giây. Hãy so sánh điều đó với một bản xuất nhị phân hoặc một công cụ lưu trữ nơi "những gì đã thay đổi" là vô hình. Với đặc tả trong Git, tính năng "blame", lịch sử và sự khác biệt đều hoạt động hiệu quả.
Phiên bản hóa thực sự. Mọi thay đổi đều có một commit, một tác giả và một dấu thời gian. Bạn có thể gắn thẻ phát hành, phân nhánh cho việc thiết kế lại `v2`, và khôi phục một thay đổi tồi bằng một lệnh duy nhất. Lịch sử API của bạn trở nên có thể kiểm tra được. Để tìm hiểu sâu hơn về các chiến lược gắn thẻ và phân nhánh, hãy xem kiểm soát phiên bản OpenAPI bằng Git.
Nguồn đáng tin cậy duy nhất. Bởi vì các mock, kiểm thử và tài liệu đều được tạo ra từ cùng một tệp, chúng không thể tự tách rời. Cập nhật đặc tả, tạo lại, và mọi đầu ra sẽ luôn nhất quán.
Dưới đây là cách so sánh hai phương pháp trong thực tế.
| Mối quan tâm | Đặc tả trong công cụ lưu trữ | Đặc tả API dưới dạng mã |
|---|---|---|
| Đánh giá thay đổi | Thủ công, dễ bỏ sót | Diff PR, đánh giá chặn |
| Lịch sử | Hạn chế hoặc bị khóa bởi nhà cung cấp | Nhật ký Git đầy đủ |
| Khôi phục | Thường thủ công | git revert |
| Nguồn đáng tin cậy duy nhất | Mơ hồ | Tệp đã được commit |
| Tích hợp CI | Gắn thêm | Bản địa |
OpenAPI như một sản phẩm chính
OpenAPI là định dạng hiển nhiên cho đặc tả vì nó được hỗ trợ rộng rãi và có thể đọc được bằng máy. Đây là một phần nhỏ nhưng hoàn chỉnh của một tệp OpenAPI 3.1 mà bạn sẽ giữ trong kho lưu trữ của mình.
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: The requested order
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
required: [id, status, total]
properties:
id:
type: string
format: uuid
status:
type: string
enum: [pending, shipped, delivered]
total:
type: number
format: float
Tệp này là hợp đồng. Thêm một trường vào `Order`, và sự khác biệt chỉ là một dòng. Thay đổi enum `status`, và người đánh giá sẽ thấy ngay lập tức. Giữ nó trong thư mục `api/openapi.yaml` bên cạnh mã dịch vụ của bạn, và đặc tả sẽ đi kèm với việc triển khai mà nó mô tả.
Đặc tả và tài liệu
Lợi ích của một tệp nguồn duy nhất là mọi thứ bạn tạo ra từ nó.
Mocks (Mô phỏng). Trỏ một máy chủ mock vào đặc tả và bạn sẽ có một API có thể chạy trước khi bất kỳ endpoint nào được xây dựng. Các nhóm frontend và di động bắt đầu tích hợp dựa trên hợp đồng ngay từ ngày đầu tiên. Khi đặc tả thay đổi, mock cũng thay đổi theo.
Kiểm thử. Tạo các kiểm thử hợp đồng để khẳng định dịch vụ trực tiếp khớp với đặc tả. Nếu một endpoint đã triển khai trả về một trường mà đặc tả chưa từng khai báo, kiểm thử sẽ thất bại. Điều này giúp phát hiện sự sai lệch giữa hợp đồng và mã đang chạy trước khi khách hàng phát hiện ra.
Tài liệu. Tự động chuyển đổi đặc tả thành tài liệu tham khảo. Không ai còn viết tay các bảng endpoint nữa. Tài liệu khớp với đặc tả vì chúng chính là đặc tả, được hiển thị.
SDK. Tạo các thư viện client bằng nhiều ngôn ngữ từ cùng một tệp. Các đối tác nhận được một SDK có kiểu (typed) luôn phản ánh hợp đồng hiện tại.
Mỗi đầu ra là một hàm của đặc tả. Thay đổi đầu vào, tạo lại đầu ra, và sự nhất quán sẽ tự động có được.
Cách Apidog biến đặc tả thành nguồn đáng tin cậy duy nhất
Chạy spec-as-code bằng tay có nghĩa là phải kết nối một CLI, một máy chủ mock, một trình tạo tài liệu và một Git hook. Apidog gộp tất cả những điều đó vào một quy trình làm việc duy nhất.
Chế độ Spec-First của Apidog coi tệp OpenAPI của bạn là định nghĩa có thẩm quyền. Bạn thiết kế các endpoint dựa trên đặc tả, và Apidog giữ các mock, kiểm thử và tài liệu của bạn đồng bộ chặt chẽ với nó.
Phần làm cho điều này trở nên thực tế là đồng bộ Git hai chiều. Apidog có thể đọc tệp OpenAPI của bạn từ một kho lưu trữ và ghi các thay đổi trở lại kho đó, vì vậy tệp trong Git và dự án trong Apidog luôn đồng bộ. Thiết kế trực quan khi nhanh hơn, chỉnh sửa trực tiếp YAML khi nhanh hơn, và cả hai đường dẫn đều đưa đến cùng một tệp đã được commit. Điều đó giữ cho quy trình đánh giá PR của bạn không bị gián đoạn trong khi cung cấp cho nhóm của bạn một trình chỉnh sửa phong phú hơn. Để tìm hiểu cơ chế đẩy các thay đổi đặc tả lên upstream, hãy xem cách đồng bộ hóa đặc tả OpenAPI của bạn với GitHub.
Kết quả: tệp OpenAPI vẫn là nguồn đáng tin cậy duy nhất, và các công cụ trực quan nằm trên đó thay vì thay thế nó.
Những cạm bẫy thường gặp
Spec-as-code khá đơn giản, nhưng một vài cạm bẫy thường khiến các nhóm gặp khó khăn ngay từ đầu.
Sự sai lệch giữa đặc tả và triển khai. Viết đặc tả thôi chưa đủ. Nếu không có gì kiểm tra rằng dịch vụ đang chạy khớp với nó, hai bên sẽ dần dần khác biệt một cách âm thầm. Hãy thêm các kiểm thử hợp đồng vào CI để một sự không khớp sẽ làm thất bại bản dựng, chứ không phải khách hàng.
Nhầm lẫn giữa mã được tạo tự động và mã viết tay. Quyết định xem đặc tả được tạo từ các chú thích mã hay được viết tay làm nguồn. Việc trộn lẫn cả hai dẫn đến một tệp mà không ai biết phần nào là có thẩm quyền. Chọn một hướng. Nếu đặc tả là nguồn đáng tin cậy duy nhất của bạn, hãy coi các chú thích mã là thứ bạn kiểm tra đối chiếu với nó, chứ không phải một bản sao chính thứ hai.
Coi đặc tả là tài liệu, không phải hợp đồng. Một đặc tả mà bạn chỉ đọc là một tài liệu. Một đặc tả mà bạn tạo ra các mock, kiểm thử và SDK từ đó là một hợp đồng. Giá trị đến từ việc kết nối các đầu ra, chứ không phải từ sự tồn tại của tệp.
Bỏ qua đánh giá. Một đặc tả trong Git được hợp nhất mà không qua đánh giá thì chỉ là một tệp trong Git. Vấn đề cốt lõi là yêu cầu kéo (pull request). Yêu cầu đánh giá đối với các thay đổi đặc tả giống như cách bạn làm đối với mã nguồn.
Bắt đầu
Bạn có thể áp dụng spec-as-code một cách tăng dần.
- Commit đặc tả của bạn. Di chuyển tệp OpenAPI của bạn vào kho lưu trữ tại một đường dẫn đã biết, như `api/openapi.yaml`.
- Yêu cầu đánh giá PR. Đảm bảo các thay đổi đặc tả phải trải qua cùng một cổng đánh giá như mã. Các khác biệt (diffs) trở thành cuộc thảo luận.
- Tạo một đầu ra. Bắt đầu với các mock hoặc tài liệu. Kết nối đặc tả với một trình tạo để đầu ra được cập nhật khi tệp thay đổi.
- Thêm kiểm tra CI. Lint đặc tả trên mỗi PR. Phát hiện OpenAPI không hợp lệ trước khi hợp nhất.
- Hoàn thiện vòng lặp với các kiểm thử hợp đồng. Sau khi các mock và tài liệu đã hoạt động, hãy thêm các kiểm thử khẳng định dịch vụ trực tiếp khớp với đặc tả.
Mỗi bước đều có giá trị riêng. Bạn nhận được giá trị ngay từ bước đầu tiên và tăng thêm giá trị với mỗi bổ sung.
Sự thay đổi này nhỏ để mô tả nhưng có tác động lớn. Một tệp duy nhất, trong Git, được đánh giá như mã, tạo ra mọi thứ ở hạ nguồn. Nếu bạn muốn chỉnh sửa trực quan và đồng bộ Git được tích hợp sẵn, hãy thử Chế độ Spec-First của Apidog và để tệp OpenAPI của bạn là nguồn đáng tin cậy duy nhất.
Câu hỏi thường gặp
“Đặc tả API dưới dạng mã” có giống với “Tài liệu dưới dạng mã” không?
Chúng chia sẻ cùng một triết lý: giữ sản phẩm chính trong hệ thống kiểm soát phiên bản và phân phối nó thông qua quy trình bình thường của bạn. Docs-as-code áp dụng cho tài liệu. Spec-as-code áp dụng cho chính hợp đồng API. Trong thực tế, chúng bổ trợ cho nhau, vì tài liệu được tạo từ một đặc tả đã commit theo định nghĩa là docs-as-code.
Tệp đặc tả nên sử dụng định dạng nào?
OpenAPI dưới dạng YAML là lựa chọn phổ biến. YAML hiển thị sự khác biệt một cách rõ ràng trong các pull request và dễ đọc đối với con người, đồng thời vẫn có thể được máy phân tích để tạo ra các mock, kiểm thử và SDK. JSON cũng hoạt động, nhưng YAML có xu hướng tạo ra các khác biệt gọn gàng hơn.
Làm cách nào để ngăn đặc tả bị lệch khỏi API thực tế?
Thêm các kiểm thử hợp đồng vào CI để khẳng định dịch vụ đang chạy khớp với đặc tả đã commit. Nếu một endpoint trả về một trường không được khai báo hoặc bỏ đi một trường đã được ghi lại, bản dựng sẽ thất bại. Vòng lặp phản hồi đó chính là điều biến đặc tả từ một tài liệu mang tính hy vọng thành một hợp đồng được thực thi.