Đây là một loạt bài gồm 10 phần chia sẻ cách Apidog phát triển Apidog CLI, một công cụ dòng lệnh để 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 bất kỳ bài viết nào bạn quan tâm:
| 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 | Khám phá 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 dữ kiện, Model hành động dựa trên dữ kiện | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLI giao tiếp với Agent |
Đầu ra có cấu trúc |
| 5 | SKILL: Chuyển giao kinh nghiệm vận hành dưới dạng mã | Kinh nghiệm vận hành |
| 6 | Các con số không nói dối: Giảm 30% lượt gọi công cụ, giảm 25% số token | Kết quả định lượng |
| 7 | Từ PRD đến Vòng lặp kiểm thử: Quy trình làm việc Agent hoàn chỉnh 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à điều không thể thiếu đối với các công cụ Agent | Góc nhìn DevOps |
| 9 | Nhánh AI: Thay đổi dự án an toàn hơn với AI Agent | 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 |
Phát triển API đang thay đổi cùng với AI Agent. Skill-First đóng gói các đặc tả, kiểm thử và kịch bản thành các kỹ năng có thể thực thi, kiểm chứng được – bổ sung cho các phương pháp tiếp cận hiện có trong kỷ nguyên Agent.
Kỷ nguyên Spec-First
Trong nhiều năm, quy trình cộng tác của nhiều nhóm phát triển là Spec-First.
Đó là gì
| Nguyên tắc | Mô tả |
|---|---|
| Thiết kế API trước | Định nghĩa API trước khi triển khai |
| Cộng tác dựa trên tài liệu | Các nhóm tham khảo đặc tả chung |
| Giả lập sớm | Frontend có thể phát triển dựa trên bản giả lập |
| Gỡ lỗi cùng nhau | Các vấn đề hiển thị ở định dạng chung |
| Kiểm thử dựa trên đặc tả | Xác minh việc triển khai khớp với thiết kế |
| Phát hành khi sẵn sàng | Phát hành các API đã được tài liệu hóa và kiểm thử |
Giá trị
| Lợi ích | Tại sao nó quan trọng |
|---|---|
| Các hợp đồng rõ ràng | Frontend/backend biết điều gì sẽ xảy ra |
| Phát triển song song | Các nhóm làm việc độc lập |
| Giảm ma sát | Giao tiếp sai được phát hiện sớm |
| Kiểm thử ổn định | Các kiểm thử khớp với hành vi được tài liệu hóa |
| Tài liệu sống | Đặc tả phát triển cùng với sản phẩm |
Spec-First là phương pháp đúng đắn cho việc phát triển API do con người điều khiển.
Người tiêu dùng mới: AI Agent
Sau khi AI Coding xuất hiện, người tiêu dùng tài sản API đã thay đổi.
Agent cũng bắt đầu tiêu thụ các tài sản này.
Những gì Agent cần
| Hoạt động của Agent | Tài sản cần thiết |
|---|---|
| Đọc endpoint | Tài liệu API |
| Thêm kiểm thử | Định nghĩa endpoint, schemas |
| Chạy tự động hóa | Kịch bản kiểm thử, môi trường |
| Sửa mã dựa trên báo cáo | Chi tiết lỗi, dữ liệu phản hồi |
| Đánh giá liệu thay đổi có sử dụng được không | Kết quả kiểm thử, độ bao phủ |
Trong bối cảnh này, tài liệu API, các trường hợp kiểm thử và kịch bản kiểm thử trong Apidog không chỉ là tài liệu cộng tác cho con người.
Chúng là các tài sản có thể gọi được một cách xác định cho Agent.
Chuyển đổi tài sản
| Tài sản | Spec-First (Góc nhìn con người) | Skill-First (Góc nhìn Agent) |
|---|---|---|
| Tài liệu API | Tài liệu cộng tác | Nguồn dữ liệu có thể gọi |
| Các trường hợp kiểm thử | Hiện vật chất lượng | Xác minh có thể thực thi |
| Kịch bản kiểm thử | Quy trình kiểm thử | Mục tiêu tự động hóa |
| Môi trường | Cấu hình | Ngữ cảnh thời gian chạy |
| Báo cáo | Kết quả xem xét | Tín hiệu phản hồi |
Các tài sản chuyển đổi từ "có thể đọc" sang "có thể gọi".
Định nghĩa Skill-First
Xây dựng dựa trên Spec-First:
| Những gì còn lại | Tại sao |
|---|---|
| Đặc tả endpoint | Vẫn cần các hợp đồng rõ ràng |
| Các trường hợp kiểm thử | Vẫn cần các hiện vật chất lượng |
| Kịch bản kinh doanh | Vẫn cần độ bao phủ quy trình làm việc |
| Tài liệu | Vẫn cần tài liệu tham khảo cho con người |
Cộng thêm:
| Những gì được thêm vào | Mục đích |
|---|---|
| Kỹ năng có thể thực thi | Agent có thể gọi các quy trình làm việc |
| Các bước có thể kiểm chứng | Các cổng chất lượng ở mỗi giai đoạn |
| Chuỗi có thể theo dõi | Nhật ký kiểm toán hành động của Agent |
Skill-First = Spec-First + Lớp thực thi Agent.
Kiến trúc hệ thống
| Lớp | Trách nhiệm | Ví dụ |
|---|---|---|
| Apidog | Quản lý tài sản API và kiểm thử | Endpoint, schemas, trường hợp kiểm thử, kịch bản |
| CLI | Cung cấp khả năng thực thi xác định | Lệnh, xác thực, đầu ra |
| SKILL | Cung cấp khả năng đánh giá và đường dẫn tác vụ | Hướng dẫn quy trình làm việc, quy tắc trình tự |
| Agent | Hiểu mục tiêu, thực thi, điều chỉnh | Claude Code, Cursor, Trae, Codex |
Mỗi lớp có một vai trò cụ thể.
Cách chúng hoạt động cùng nhau
Người dùng: "Tạo kiểm thử cho API hoàn tiền và chạy xác minh"
↓
Agent: Hiểu loại tác vụ (SKILL hỗ trợ)
↓
Agent: Gọi CLI để đọc các endpoint (CLI thực thi)
↓
Agent: Tạo các trường hợp kiểm thử (Agent tạo)
↓
CLI: Xác thực cấu trúc (cli-schema xác thực)
↓
Agent: Ghi các trường hợp kiểm thử (CLI thực thi)
↓
CLI: Trả về agentHints (CLI hướng dẫn)
↓
Agent: Đọc lại, điều chỉnh (Agent làm theo gợi ý)
↓
Agent: Chạy kiểm thử (CLI thực thi)
↓
CLI: Trả về báo cáo (CLI cung cấp phản hồi)
↓
Agent: Tóm tắt cho người dùng (Agent hoàn tất)Chuyển đổi quy trình làm việc
Quy trình làm việc Spec-First (Do con người điều khiển)
Con người thiết kế đặc tả
↓
Con người tài liệu hóa
↓
Con người tạo bản giả lập
↓
Con người gỡ lỗi
↓
Con người viết kiểm thử
↓
Con người phát hànhĐặc điểm:
| Khía cạnh | Mô tả |
|---|---|
| Người điều khiển | Con người |
| Trọng tâm | Cộng tác |
| Phản hồi | Xem xét thủ công |
| Tốc độ | Tốc độ con người |
| Lỗi | Con người phát hiện |
Quy trình làm việc Skill-First (Có Agent hỗ trợ)
Con người chỉ định mục tiêu
↓
Agent đọc các tài sản hiện có
↓
Agent tạo ra các thay đổi
↓
CLI xác thực
↓
Agent ghi
↓
CLI hướng dẫn các bước tiếp theo
↓
Agent xác minh
↓
Con người xem xét kết quảĐặc điểm:
| Khía cạnh | Mô tả |
|---|---|
| Người điều khiển | Agent (được hướng dẫn bởi mục tiêu của con người) |
| Trọng tâm | Thực thi |
| Phản hồi | Xác thực tự động |
| Tốc độ | Tốc độ Agent |
| Lỗi | CLI phát hiện |
Các nhóm nên làm gì
Các bước tức thì
| Bước | Hành động |
|---|---|
| 1. Cài đặt | npm install -g apidog-cli@latest |
| 2. Cài đặt SKILL | apidog skill install |
| 3. Thử tác vụ nhỏ | Giao tác vụ rủi ro thấp cho Agent |
| 4. Học các mẫu | Quan sát quy trình làm việc của Agent |
| 5. Mở rộng phạm vi | Tăng dần độ phức tạp của tác vụ |
Ví dụ về tác vụ Agent đầu tiên
Sử dụng Apidog CLI để giúp tôi tạo endpoint API đầu tiên trong Apidog.
Đầu tiên, hãy kiểm tra thiết lập Apidog CLI của tôi và liệt kê các dự án mà tôi có thể truy cập.
Hỏi tôi nên sử dụng dự án nào. Sau khi tôi xác nhận, hãy tạo một endpoint GET /health đơn giản
có tên Health Check với ví dụ phản hồi 200. Xác thực bất kỳ đầu vào có cấu trúc nào
trước khi ghi, sau đó đọc lại endpoint và tóm tắt những gì đã được tạo.Điều này mang lại:
| Lợi ích | Mô tả |
|---|---|
| Kiểm tra thiết lập | Agent xác minh môi trường |
| Chọn dự án | Agent hỏi trước khi ghi |
| Tạo nhỏ | Tác vụ đầu tiên rủi ro thấp |
| Xác thực | cli-schema trước khi ghi |
| Đọc lại | Xác nhận những gì đã được tạo |
| Tóm tắt | Con người nhận được kết quả rõ ràng |
Lệnh bắt đầu
# Cài đặt Apidog CLI
npm install -g apidog-cli@latest
# Cài đặt SKILL bổ trợ
apidog skill install
# Kiểm tra phiên bản (cần 2.2.5+)
apidog -v
# Xác thực
apidog auth login
# Liệt kê dự án
apidog project listTương lai
| Xu hướng | Hướng đi |
|---|---|
| Sự tham gia của Agent | Nhiều tác vụ phát triển API hơn được Agent xử lý |
| Các mẫu CLI + SKILL | Quy trình làm việc trưởng thành, tiêu chuẩn hóa |
| Nhiều kỹ năng hơn | Các kỹ năng dành riêng cho từng lĩnh vực trong các ngữ cảnh khác nhau |
| Hội tụ tốt hơn | Kỹ thuật được cải thiện cho các nút quan trọng |
| Cộng tác giữa con người và Agent | Chuyển giao liền mạch giữa con người và Agent |
Tương lai là phát triển API có Agent hỗ trợ.
Tóm tắt toàn bộ loạt bài
Chúng tôi đã đề cập toàn bộ hành trình:
| Phần | Chủ đề | Thông tin chi tiết quan trọng |
|---|---|---|
| 1 | Vấn đề | 126 công cụ MCP → một bức tường các công cụ ngẫu nhiên |
| 2 | Bước ngoặt | Sự phức tạp chuyển từ ngữ cảnh sang kỹ thuật |
| 3 | Triết lý | CLI xác thực, Agent tạo |
| 4 | Thiết kế | agentHints hướng dẫn các bước tiếp theo |
| 5 | Kinh nghiệm | SKILL đóng gói kiến thức quy trình làm việc |
| 6 | Xác thực | Giảm 30% lượt gọi, giảm 25% token |
| 7 | Thực hành | PRD → OpenAPI → Kiểm thử → Xác minh |
| 8 | Nền tảng | CI/CD vẫn là nền tảng |
| 9 | Thành thật | Bốn thách thức vẫn còn |
| 10 | Tầm nhìn | Spec-First → Skill-First |
Nguyên tắc cuối cùng
Spec-First dành cho sự cộng tác của con người. Skill-First dành cho việc thực thi của Agent.
| Kỷ nguyên | Phương pháp tiếp cận | Người tiêu dùng |
|---|---|---|
| Truyền thống | Spec-First | Con người |
| Kỷ nguyên Agent | Skill-First | Con người + Agent |
Tài sản trở nên có thể gọi được. Quy trình làm việc trở nên có thể thực thi. Chất lượng trở nên có thể kiểm chứng được.
Chào mừng đến với Skill-First.
Những điểm chính cần nhớ
- Spec-First là phương pháp đúng đắn cho việc phát triển do con người điều khiển
- Agent hiện là người tiêu dùng tài sản API
- Tài sản chuyển đổi từ có thể đọc sang có thể gọi
- Skill-First = Spec-First + thực thi Agent
- Hệ thống: Apidog (tài sản) → CLI (thực thi) → SKILL (đánh giá) → Agent (hành động)
- Con người chỉ định mục tiêu, Agent thực thi, CLI xác thực
- Bắt đầu nhỏ, học các mẫu, mở rộng phạm vi
Tải xuống 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. 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.