浏览器与自动化
create-handler
Create a new API handler following the handler pattern. Use when the user asks to create an endpoint, handler, or route.
girijashankarj · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add girijashankarj/cursor-handbook --skill create-handler技能说明
name: create-handler description: Create a new API handler following the handler pattern. Use when the user asks to create an endpoint, handler, or route.
Skill: Create API Handler
Step-by-step workflow for creating a new API handler following the {{CONFIG.patterns.handlerFlowSteps}}-step handler pattern.
Scripts (Cursor skills scripts/ support)
This skill includes a scripts/ folder. The agent can run these scripts as part of the workflow:
- scripts/scaffold-handler-dirs.sh — Creates the handler directory structure. Usage:
./scripts/scaffold-handler-dirs.sh <entity> <operation>(e.g.order create).
Trigger
When the user asks to create a new API endpoint, handler, or route.
Prerequisites
- Project configuration loaded (
{{CONFIG.paths.handlerBasePath}}exists) - Understanding of the entity and operation
Steps
Step 1: Gather Requirements
- Identify the entity (e.g., Order, Product, User)
- Identify the operation (e.g., create, read, update, list, delete)
- Determine HTTP method and URL path
- Identify request parameters and body schema
- Identify response format
Step 2: Create Directory Structure
mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/logic
mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/schemas
Expected structure:
{{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/
├── {{CONFIG.fileNames.handlerEntry}}
├── logic/
│ ├── validate-request.ts
│ ├── validate-business.ts
│ ├── pre-processing.ts
│ ├── operation.ts
│ ├── post-operation.ts
│ └── response.ts
└── schemas/
├── {{CONFIG.fileNames.requestSchema}}
└── {{CONFIG.fileNames.responseSchema}}
Step 3: Create Request Schema
- Define JSON Schema in
schemas/{{CONFIG.fileNames.requestSchema}} - Include all required and optional fields
- Add type validation and constraints
- Add description for each field
Step 4: Create Response Schema
- Define JSON Schema in
schemas/{{CONFIG.fileNames.responseSchema}} - Follow response envelope pattern:
{ data, meta } - Include all response fields with types
Step 5: Implement Logic Steps
For each file in logic/:
-
validate-request.ts— Validate request against schema -
validate-business.ts— Check business rules and entity state -
pre-processing.ts— Transform and enrich data -
operation.ts— Execute core business logic -
post-operation.ts— Trigger side effects (events, notifications) -
response.ts— Format response with envelope
Step 6: Create Handler Entry Point
- Import all logic steps
- Wire up the {{CONFIG.patterns.handlerFlowSteps}}-step flow
- Add error handling with try/catch
- Add structured logging with correlationId
- Export handler function
Step 7: Register Route
- Add route in the appropriate router file
- Apply authentication middleware
- Apply rate limiting if needed
Step 8: Add Tests
- Create test file:
{entity}/{operation}/__tests__/handler.test.ts - Test each logic step independently
- Test handler integration (success path)
- Test error cases (validation, business, not found)
- Verify {{CONFIG.testing.coverageMinimum}}% coverage
Step 9: Validate
- Run type check:
{{CONFIG.testing.typeCheckCommand}} - Run tests for the new handler only
- Verify schemas match implementation
Completion
Handler is created, tested, and type-checked. Ready for code review.
If a step fails
- Step 2 (directory): Ensure
{{CONFIG.paths.handlerBasePath}}exists. Runmkdir -pfrom project root. - Step 3–4 (schemas): If schema validation fails, check JSON Schema syntax. Use a minimal schema first.
- Step 5 (logic): If imports fail, verify paths match
{{CONFIG.paths.commonPath}}and handler structure. - Step 8 (tests): If tests fail, run
{{CONFIG.testing.typeCheckCommand}}first. Fix type errors before test logic. - Step 9 (validate): If type-check fails, fix reported errors before proceeding. Do not skip validation.