Đây là chuỗi 10 phần chia sẻ cách Apidog phát triển Apidog CLI, công cụ dòng lệnh dùng để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc chuyển đến phần phù hợp với nhu cầu triển khai của mình:
| Tiêu đề | Trọng tâm | |
|---|---|---|
| 1 | Chúng tôi đã xây dựng 126 công cụ MCP. Nhưng đó không phải là giải pháp tốt nhất cho Agent | Phát hiện vấn đề |
| 2 | Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới | Phát triển kiến trúc |
| 3 | Quy tắc vàng: CLI tạo ra sự thật, Mô hình hành động dựa trên sự thật | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLIs giao tiếp với Agent |
Đầu ra có cấu trúc |
| 5 | SKILL: Chuyển đổi kinh nghiệm vận hành thành mã | Kinh nghiệm vận hành |
| 6 | Các con số không nói dối: Giảm 30% số lượt gọi công cụ, giảm 25% số lượng token | Kết quả định lượng |
| 7 | Từ PRD đến chu trình kiểm thử: Quy trình làm việc hoàn chỉnh của Agent với Apidog CLI | Hướng dẫn thực hành |
| 8 | Tại sao khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent | Góc nhìn DevOps |
| 9 | AI Branch: Thay đổi dự án an toàn hơn với AI Agents | Lớp bảo mật |
| 10 | Spec-First đã là quá khứ. Chào mừng đến với Skill-First. | Tầm nhìn & Tương lai |
Bài viết này đi qua một ví dụ triển khai thực tế: nhóm đã có PRD “Hoàn tiền đơn hàng” và cơ sở mã tương ứng. Mục tiêu là để Agent dùng Apidog CLI + SKILL tạo OpenAPI, nhập vào Apidog, tạo test case, xác thực schema và chạy kiểm thử end-to-end.
Kịch bản
Bối cảnh
Nhóm vừa hoàn thành PRD cho chức năng Hoàn tiền đơn hàng. Trong codebase đã có route và controller tương ứng.
Yêu cầu gửi cho Agent
Tạo kiểm thử API cho chức năng hoàn tiền dựa trên PRD và cơ sở mã, sau đó chạy xác minh.
Nhiệm vụ này gồm nhiều bước kỹ thuật:
- Đọc PRD.
- Đối chiếu với route/controller trong codebase.
- Sinh OpenAPI.
- Nhập OpenAPI vào Apidog.
- Tạo test case cho từng endpoint.
- Gom test case thành kịch bản nghiệp vụ.
- Chạy kiểm thử và xuất báo cáo.
Vấn đề của cách tiếp cận cũ
Với cách tiếp cận dựa trên nhiều công cụ MCP rời rạc, Agent phải tự quyết định thứ tự thao tác và công cụ cần dùng.
| Điểm quyết định | Sự không chắc chắn |
|---|---|
| Truy vấn dự án trước? | Hay tạo endpoint trước? |
| Viết test case trước? | Hay tạo schema trước? |
| Chạy kiểm thử trực tiếp? | Hay đọc lại tài nguyên trước? |
| Công cụ nào cho mỗi bước? | Phải tìm trong 126 công cụ |
Vấn đề không nằm ở việc Agent không thể làm. Vấn đề là Agent phải dành quá nhiều lượt gọi công cụ để tìm đường đi đúng, thay vì thực thi tác vụ chính.
Quy trình CLI + SKILL
Với CLI + SKILL, luồng triển khai được chuẩn hóa thành chuỗi thao tác rõ ràng:
Tạo OpenAPI từ PRD & cơ sở mã
↓
Nhập vào Apidog
↓
Thêm test case cho endpoint
↓
Xác thực trước khi ghi
↓
Tạo test scenario cho luồng nghiệp vụ
↓
Xác thực trước khi ghi
↓
Chạy kiểm thử tự động
Điểm quan trọng: mỗi bước đều có lệnh CLI, đầu ra có cấu trúc và agentHints để Agent biết bước tiếp theo.
Bước 1: Tạo OpenAPI và nhập vào Apidog
Agent bắt đầu bằng cách đọc PRD và codebase để tạo đặc tả OpenAPI.
Trích đoạn PRD
API Hoàn tiền Đơn hàng
POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number }
- Response: { "refundId": string, "status": string, "processedAt": datetime }
GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number }
OpenAPI do Agent tạo
{
"openapi": "3.0.0",
"paths": {
"/api/orders/{orderId}/refund": {
"post": {
"summary": "Tạo yêu cầu hoàn tiền",
"parameters": [...],
"requestBody": {...},
"responses": {...}
}
},
"/api/orders/{orderId}/refund/{refundId}": {
"get": {
"summary": "Lấy trạng thái hoàn tiền"
}
}
}
}
Lưu file này thành openapi.json, sau đó nhập vào Apidog:
apidog import --project <projectId> --format openapi --file ./openapi.json
Đầu ra CLI
{
"success": true,
"data": {
"importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
"endpointIds": ["ep-001", "ep-002"]
},
"agentHints": {
"summary": "OpenAPI đã được nhập thành công. 2 endpoint đã được tạo.",
"nextSteps": [
"Liệt kê các endpoint đã nhập để xác nhận cấu trúc.",
"Thêm trường hợp kiểm thử cho từng endpoint.",
"Tạo một kịch bản kiểm thử cho toàn bộ luồng hoàn tiền."
]
}
}
Ở bước này, Agent không cần đoán tiếp theo phải làm gì. agentHints.nextSteps đã chỉ ra hướng đi tiếp theo: xác nhận endpoint, thêm test case, sau đó tạo scenario.
Bước 2: Tạo test case cho một endpoint
Agent bắt đầu với endpoint tạo yêu cầu hoàn tiền.
Đọc lại endpoint trước khi sinh test case:
apidog endpoint get ep-001 --project <projectId>
CLI trả về cấu trúc endpoint
{
"id": "ep-001",
"method": "POST",
"path": "/api/orders/{orderId}/refund",
"requestBody": {
"schema": {
"type": "object",
"properties": {
"reason": { "type": "string" },
"amount": { "type": "number" }
},
"required": ["reason", "amount"]
}
},
"responses": {
"200": {}
}
}
Dựa trên schema thực tế, Agent tạo payload test case:
{
"name": "Tạo hoàn tiền - thành công",
"endpointId": "ep-001",
"request": {
"path": "/api/orders/order-123/refund",
"body": {
"reason": "Yêu cầu của khách hàng",
"amount": 99.99
}
},
"assertions": [
{
"subject": "responseJson.status",
"comparator": "equal",
"target": "processed"
}
]
}
Trước khi ghi vào Apidog, xác thực schema cục bộ:
apidog cli-schema validate test-case-create --file ./test-case-create.json
Kết quả xác thực
{
"success": true,
"agentHints": {
"summary": "Cấu trúc trường hợp kiểm thử hợp lệ.",
"nextSteps": [
"Tạo trường hợp kiểm thử trong Apidog.",
"Đọc lại trường hợp kiểm thử đã tạo để xác nhận.",
"Thêm các khẳng định nếu cần."
]
}
}
Sau khi hợp lệ, tạo test case:
apidog test-case create --project <projectId> --file ./test-case-create.json
Đầu ra CLI
{
"success": true,
"data": {
"id": "tc-001",
"name": "Tạo hoàn tiền - thành công"
},
"agentHints": {
"summary": "Trường hợp kiểm thử đã được tạo thành công.",
"nextSteps": [
"Đọc lại trường hợp kiểm thử tc-001 để xác nhận các khẳng định.",
"Tạo trường hợp kiểm thử cho GET /refund/{refundId}.",
"Xây dựng kịch bản kiểm thử cho luồng hoàn tiền hoàn chỉnh."
]
}
}
Cách làm này giảm lỗi ghi dữ liệu vì Agent xác thực cấu trúc trước khi gọi lệnh tạo tài nguyên.
Bước 3: Tạo test scenario cho luồng hoàn chỉnh
Theo PRD, luồng nghiệp vụ hoàn chỉnh là:
Tạo đơn hàng → Thanh toán → Hoàn tiền → Truy vấn trạng thái hoàn tiền
Agent gom các test case thành một scenario:
{
"name": "Luồng hoàn tiền đơn hàng hoàn chỉnh",
"steps": [
{ "type": "case", "caseId": "tc-create-order" },
{ "type": "case", "caseId": "tc-pay" },
{ "type": "case", "caseId": "tc-001" },
{ "type": "case", "caseId": "tc-get-refund" }
]
}
Trước khi tạo scenario, tiếp tục xác thực payload:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Nếu hợp lệ, tạo scenario:
apidog test-scenario create --project <projectId> --file ./scenario-update.json
Nguyên tắc triển khai ở đây là: đọc cấu trúc thật → tạo payload → xác thực → ghi. Agent không tự viết vào hệ thống khi chưa kiểm tra schema.
Bước 4: Chạy xác minh
Sau khi test case và scenario đã sẵn sàng, chạy kiểm thử tự động:
apidog run --project <projectId> \
--test-scenario scenario-001 \
--environment env-production \
-r "cli,html,junit" \
--out-dir ./apidog-reports
Lệnh trên tạo nhiều loại báo cáo:
-
cli: kết quả hiển thị trong terminal. -
html: báo cáo để đọc thủ công. -
junit: file phù hợp cho CI/CD.
Đầu ra CLI
{
"success": true,
"stats": {
"total": 4,
"passed": 4,
"failed": 0
},
"reportFiles": {
"cli": "./apidog-reports/cli-report.txt",
"html": "./apidog-reports/report.html",
"junit": "./apidog-reports/junit.xml"
},
"agentHints": {
"summary": "Tất cả các kiểm thử đã vượt qua. 4 bước đã được thực hiện thành công.",
"nextSteps": [
"Xem lại báo cáo HTML để biết kết quả chi tiết.",
"Nếu xảy ra lỗi, hãy gỡ lỗi bằng cách sử dụng chi tiết lỗi CLI.",
"Tích hợp kiểm thử này vào đường ống CI."
]
}
}
Đây là điểm kết nối giữa workflow của Agent và workflow CI/CD: cùng một lệnh apidog run có thể dùng cho cả kiểm thử tự động trong pipeline và kiểm thử do Agent điều phối.
Chuỗi hoàn chỉnh
Sau khi hoàn tất, toàn bộ tài sản kiểm thử đã được tạo và xác minh:
| Yếu tố | Trạng thái |
|---|---|
| PRD | Đã đọc và xử lý |
| Cơ sở mã | Đã phân tích các route |
| OpenAPI | Đã tạo và nhập |
| Tài sản endpoint | Đã tạo trong Apidog |
| Kiểm thử một endpoint | Đã tạo và xác thực |
| Kịch bản nghiệp vụ | Đã xây dựng và xác minh |
Kết quả: mọi bước đều có đầu vào, đầu ra, lệnh CLI và báo cáo tương ứng. Điều này giúp quy trình có thể truy vết và lặp lại.
agentHints trong toàn bộ luồng
agentHints đóng vai trò như lớp hướng dẫn thao tác cho Agent.
| Sau bước | Gợi ý từ agentHints
|
|---|---|
| Nhập endpoint | Liệt kê endpoint, thêm test case |
| Tạo test case | Đọc lại, tạo thêm test case, xây dựng scenario |
| Tạo scenario | Thêm assertion, xác thực, chạy kiểm thử |
| Chạy kiểm thử | Xem báo cáo, gỡ lỗi nếu cần, tích hợp vào CI |
Thay vì phải suy luận từ danh sách công cụ lớn, Agent nhận được chỉ dẫn trực tiếp từ kết quả của từng lệnh.
So sánh MCP và CLI + SKILL cho tác vụ này
| Khía cạnh | Cách tiếp cận MCP | Cách tiếp cận CLI + SKILL |
|---|---|---|
| Điểm khởi đầu | Agent tìm kiếm các công cụ dự án | SKILL xác định loại tác vụ |
| Tạo endpoint | Agent đoán công cụ và trường dữ liệu | CLI nhập từ OpenAPI |
| Tạo test case | Dễ phải thử lại do lỗi field | Xác thực cục bộ trước khi ghi |
| Xây dựng scenario | Agent tự viết cấu trúc | Nhập step, đọc lại, cập nhật |
| Xác minh | Agent tìm công cụ chạy |
agentHints gợi ý sau scenario |
| Tổng số bước | Khoảng 20-25 lượt gọi với các lần thử lại | Khoảng 10-12 lượt gọi đã xác thực |
Với các tác vụ nhiều bước, khác biệt lớn nhất là khả năng giảm suy đoán. CLI + SKILL biến workflow thành chuỗi thao tác có kiểm chứng.
Tiếp theo là gì
Ví dụ này cho thấy cách CLI + SKILL hoạt động trong một quy trình R&D thực tế: từ PRD đến test scenario có thể chạy được.
Nền tảng bên dưới workflow này là khả năng tương thích CI/CD.
Trong Phần 8, Tại sao khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent, chúng ta sẽ xem vì sao apidog run có thể phục vụ cả pipeline CI và AI Agent, cũng như lý do thiết kế công cụ theo hướng này bền vững hơn.
Những điểm chính
- Workflow hoàn chỉnh: PRD → OpenAPI → Import → Test case → Scenario → Verification.
- Mỗi bước nên có lệnh CLI, xác thực schema và
agentHints. - Nên đọc cấu trúc thực tế trước khi tạo hoặc cập nhật tài nguyên.
- Xác thực cục bộ giúp giảm lỗi ghi dữ liệu.
-
agentHintsgiúp Agent biết bước tiếp theo mà không cần đoán. - Báo cáo
htmlvàjunitgiúp kết quả kiểm thử dùng được cho cả review thủ công và CI/CD. - Toàn bộ quy trình có thể truy vết, chạy lại và tự động hóa.
Tải Apidog để thiết kế, giả lập, kiểm thử và tài liệu hóa API trong một không gian làm việc duy nhất. Tìm hiểu thêm về Apidog CLI để kiểm thử API dòng lệnh, tự động hóa CI và quy trình làm việc của AI Agent.
Top comments (0)