Back to Details

api-endpoint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Endpoint Skill

API Endpoint 技能

When to Apply

适用场景

  • User asks to add a new API endpoint or CRUD route.
  • Existing API contract needs extension.
  • Backend changes require request validation and response contract updates.
  • 用户需要添加新的API端点或CRUD路由时。
  • 现有API契约需要扩展时。
  • 后端变更需要更新请求验证和响应契约时。

Workflow

工作流程

  1. Read project specs first: 
    specs/specs.md
    , then role-specific specs as needed.
  2. Detect backend conventions from the repo (routing, controller/service patterns, validation style).
  3. Define endpoint contract before implementation:
    • Path + method
    • Auth requirements
    • Request validation
    • Response shape and error shape
  4. Implement with thin transport layer and business logic in domain/service/action classes.
  5. Add focused tests for success path, validation failure, and authorization failure.
  1. 首先阅读项目规范：
    specs/specs.md
    ，然后根据需要阅读特定角色的规范。
  2. 从代码仓库中识别后端约定（路由、控制器/服务模式、验证风格）。
  3. 在实现前定义端点契约：
    • 路径 + 请求方法
    • 权限要求
    • 请求验证
    • 响应结构和错误结构
  4. 实现时采用轻量传输层，将业务逻辑放在领域/服务/动作类中。
  5. 针对成功路径、验证失败和权限失败场景添加针对性测试。

Quality Bar

质量标准

  • Keep endpoint behavior idempotent where required.
  • Avoid N+1 queries and over-fetching.
  • Return consistent JSON payloads.
  • 在需要时保持端点行为的幂等性。
  • 避免N+1查询和过度获取数据。
  • 返回格式一致的JSON响应体。