Xây Dựng REST API
Deliverable phổ biến nhất trong outsourcing là một API: một mobile team cần backend, một khách hàng muốn tách rời frontend của họ, hoặc một đối tác integration cần một giao diện chuẩn hóa. Xây dựng API đúng cách — error response nhất quán, status code phù hợp, input validation, authentication, và documentation — thường mất cả một ngày. Sun Agent Kit nén thời gian đó thành một buổi chiều tập trung, tạo ra code sẵn sàng cho production review, không chỉ là proof of concept.
Tổng Quan
Mục tiêu: Thiết kế và triển khai một REST API đầy đủ chức năng, có tài liệu với authentication và các thao tác CRUD
Thời gian: 30–60 phút (so với 6–12 giờ thủ công)
Agents sử dụng: planner, implementer, tester, doc-writer
Commands: /sk:plan, /sk:cook, /sk:test, /sk:docs
Yêu Cầu Trước Khi Bắt Đầu
- Sun Agent Kit đã cài đặt với scaffold dự án sẵn sàng (chạy
/sk:bootstrapnếu bắt đầu từ đầu) - Database đang chạy và migrations tooling đã thiết lập
- Mô tả rõ ràng về các resource, relationship, và operation cần thiết
- Chiến lược authentication đã quyết định (JWT, API key, OAuth — nói cho agent biết cái nào)
- Framework và ORM ưu tiên đã có trong scaffold (Express + Prisma, Fastify + Drizzle, v.v.)
Quy Trình Từng Bước
Bước 1: Thiết Kế Các API Endpoint
/sk:plan "design a REST API for a task management system: users, projects, tasks. Users own projects, projects contain tasks. Tasks have status (todo/in-progress/done), priority (low/medium/high), due dates, and assignees. CRUD for all resources. JWT auth. Role-based access: project owners can invite members."Điều gì xảy ra: Agent thực hiện:
- Phân tích cấu trúc dự án để tìm framework, ORM, và route pattern hiện có
- Thiết kế endpoint map đầy đủ bao gồm auth, project, member, và task operation
- Viết kế hoạch triển khai với các bước đánh số và task checklist được lưu vào
plans/
Bước 2: Tạo Database Schema
/sk:cook "implement the Prisma schema for users, projects, project_members, and tasks per the API design in plans/phase-task-api.md — then generate and run the migration"Điều gì xảy ra: Agent thực hiện:
- Viết Prisma schema với tất cả model và relationship cần thiết
- Thêm index cho các query mà API sẽ chạy thường xuyên nhất
- Tạo và áp dụng migration vào database
Bước 3: Triển Khai Các CRUD Endpoint
/sk:cook "implement all endpoints from plans/phase-task-api.md — controllers, services, route handlers, input validation with zod, and proper HTTP status codes for all success and error cases"Điều gì xảy ra: Agent thực hiện:
- Triển khai auth endpoint (register, login) với xử lý credential phù hợp
- Triển khai project endpoint với ownership và membership access control
- Triển khai task endpoint với filtering và permission check
- Áp dụng Zod validation schema cho tất cả mutating endpoint
- Chạy typecheck và resolve các TypeScript error
Bước 4: Chạy Test
/sk:test "write and run integration tests for all endpoints — cover the happy path, auth failures, permission checks (non-owner trying to delete), and validation errors"Điều gì xảy ra: Agent thực hiện:
- Viết test file cho auth, project, và task bao gồm happy path và error case
- Chạy full test suite trên test database
- Báo cáo coverage cho controller, service, và schema
Bước 5: Tạo Tài Liệu API
/sk:docs "generate API reference documentation for all endpoints — include request/response examples, error codes, and authentication notes"Điều gì xảy ra: Agent thực hiện:
- Đọc tất cả route handler và Zod schema
- Tạo OpenAPI 3.1 spec có thể import vào Postman hoặc Insomnia
- Viết API reference dễ đọc với ví dụ curl cho mỗi endpoint
Ví Dụ Thực Tế: Xây Dựng Task Management API với Users, Projects, và Tasks
Tình huống: Mobile team của khách hàng (iOS/Android) cần backend cho ứng dụng quản lý dự án của họ. Họ gửi một Notion doc với ghi chú data model và danh sách các màn hình. Deliverable của bạn là một API hoạt động với docs họ có thể import vào Postman. Timeline: từ sáng thứ Tư đến hết ngày thứ Sáu.
Bắt đầu sáng thứ Tư:
# 1. Bootstrap nếu bắt đầu từ đầu
/sk:bootstrap "Express TypeScript REST API — PostgreSQL with Prisma, JWT auth, Zod validation, Vitest for tests, no frontend"
# 2. Lên kế hoạch toàn bộ API từ Notion doc của khách hàng
/sk:plan "task management API: users register/login, projects (CRUD, invite members), tasks (CRUD, status workflow, assignees, due dates, filters). Client mobile app will consume this. JWT auth throughout."
# 3. Build database schema trước
/sk:cook "implement Prisma schema per the plan — focus on data integrity: FK constraints, indexes for the queries the mobile app will run (tasks by project, tasks by assignee)"
# 4. Triển khai tất cả endpoint
/sk:cook "implement all endpoints per plans/phase-task-api.md — don't add anything not in the plan. Make sure every error response is JSON with { error: string } shape so the mobile team can handle errors consistently."
# 5. Viết test toàn diện — khách hàng sẽ chạy những test này trong CI
/sk:test "integration tests for all endpoints — use a real test database, not mocks. Cover: auth flows, permission boundaries, filter combinations, edge cases like deleting a project with tasks"
# 6. Tạo OpenAPI spec — đây là thứ mobile team đã yêu cầu
/sk:docs "generate API reference documentation — OpenAPI 3.1 spec importable into Postman, plus a curl-heavy API.md for quick reference"
# 7. Commit
/sk:git cm "feat: task management REST API — users, projects, tasks, JWT auth"Kết quả: Đến trưa thứ Năm, mobile team của khách hàng đã có OpenAPI spec trong Postman workspace của họ và một API đang chạy trên staging. Họ xác nhận nó khớp với các màn hình vào cuối ngày. Thứ Sáu là buffer cho bất kỳ feedback integration nào.
So Sánh Thời Gian
| Giai đoạn | Thủ công | Với Sun Agent Kit |
|---|---|---|
| Thiết kế endpoint + lập kế hoạch | 1–2 giờ | 5–10 phút |
| Database schema + migration | 30–60 phút | 5–10 phút |
| Triển khai controller/service/route | 3–5 giờ | 15–25 phút |
| Input validation và error handling | 1–2 giờ | đã có trong cook |
| Viết test | 2–3 giờ | 5–15 phút |
| Tài liệu API (OpenAPI) | 1–2 giờ | 5–10 phút |
| Tổng | 6–12 giờ | 30–60 phút |
Các Thực Hành Tốt Nhất
1. Chỉ định hình dạng error response trong prompt cook ✅
Mobile team cần error response nhất quán để xử lý chúng một cách generic. Hãy nói với agent: “all errors must return { error: string, code?: string } with the appropriate HTTP status.” Điều này ngăn mỗi endpoint format lỗi theo cách khác nhau.
2. Mô tả quy tắc access control rõ ràng ✅
“Role-based” là mơ hồ. Hãy chính xác: “only project owners can invite members; both owners and members can create tasks; only the task creator or assignee can delete a task.” Quy tắc authorization mơ hồ tạo ra các triển khai không an toàn hoặc không nhất quán.
3. Review Prisma schema trước khi chạy /sk:cook trên endpoint ✅
Nếu schema sai, mọi endpoint xây dựng trên nó đều kế thừa vấn đề. Dành 5 phút đọc schema được tạo ra trước khi tiếp tục.
4. Nhờ /sk:cook build tất cả trong một lệnh mà không có kế hoạch ❌
/sk:cook "build me a task management API" không có kế hoạch tạo ra một cấu trúc generic có thể không khớp với data model của khách hàng. Luôn lên kế hoạch trước, sau đó cook theo kế hoạch.
5. Bỏ qua OpenAPI spec vì “sẽ thêm sau” ❌
“Sau” không bao giờ đến. Tạo spec như một phần của build ban đầu. Mất vài phút với /sk:docs và tiết kiệm hàng giờ trao đổi qua lại với mobile team của khách hàng.
Xử Lý Sự Cố
Vấn đề: Prisma migration fail với constraint error
Giải pháp: Chạy /sk:fix --quick "Prisma migration failed: [paste error]". Thường là vấn đề thứ tự foreign key hoặc nullable constraint — agent giải quyết nhanh chóng.
Vấn đề: Test fail với “connection refused” đến test database
Giải pháp: Kiểm tra file .env.test của bạn có DATABASE_URL trỏ đến test database, không phải production. Chạy /sk:ask "how should the test database be configured in this project?" để xác minh.
Vấn đề: OpenAPI spec không khớp với hành vi endpoint thực tế
Giải pháp: Docs agent đọc route handler và schema. Nếu handler có behavior không được document (manual response override, middleware side effect), chạy lại /sk:docs với ghi chú rõ ràng về middleware liên quan.
Vấn đề: /sk:cook tạo service layer nhưng dự án không dùng
Giải pháp: Hướng dẫn pattern trong prompt: /sk:cook "put all business logic in route handlers, no service layer". Agent mặc định theo convention có sẵn trong codebase của bạn nhưng có thể được override.
Bước Tiếp Theo
- Triển Khai Xác Thực — thêm full auth flow lên trên API mới của bạn
- Thêm Tính Năng Mới — mở rộng API với các endpoint bổ sung và business logic
- Sửa Bug Có Hệ Thống — cho khi QA hoặc mobile team báo cáo vấn đề với API của bạn
Điểm mấu chốt: Mobile team của khách hàng không nên chờ hai ngày cho một API endpoint hoạt động được — /sk:cook theo một kế hoạch vững chắc giao endpoint, test, và một OpenAPI spec trong một buổi sáng.