用途
API Endpoint Builder 是一个面向 REST API 端点构建的工作流技能,用于在用户需要创建 API 端点、构建 REST API、添加后端功能、为现有 API 增加端点或实现 CRUD 操作时提供结构化指导。其目标是产出具备验证、错误处理、认证和文档的生产级端点,并遵循安全与可扩展性方面的最佳实践。
主要能力
该技能为每个端点覆盖以下构建要素:
- 按正确 HTTP 方法编写的路由处理器
- 输入验证(请求体、路径参数、查询参数)
- 身份认证/授权检查
- 业务逻辑
- 错误处理
- 响应格式化
- API 文档
- 测试(如有要求)
技能内包含端点结构说明(以 Express 和 Fastify 为例展示路由定义)、输入验证示例、处理器实现示例,以及 CRUD、分页、过滤与排序等常见模式。
使用方式
资料给出的典型调用方式包括:
- 直接请求上游工作流:使用
@api-endpoint-builder处理任务,从已复制的上游工作流开始,只加载会改变结果的文件,并在回答中保持来源可见。 - 基于来源的审查:对照
metadata.json和ORIGIN.md审查该技能,说明首先会加载哪些上游文件及原因。 - 缩小支持文件范围后执行:明确指定要加载的参考、示例或脚本文件后再继续。
- 构建审查材料:结合上游文件与来源信息进行审查,并在合并前总结缺口。
工作流步骤为:确认用户目标与范围;在加载上游支持文件前先阅读概述与来源文件;只加载对当前请求有实质影响的参考、示例、提示或脚本;执行上游工作流并保持来源与边界清晰;依据上游预期与可指认的证据验证结果;当工作超出该工作流范围时移交相关技能;在合并或关闭前记录所用内容、变更及待审查项。
适用场景
- 用户明确提出“创建 API 端点”或“构建 REST API”
- 构建新的后端功能
- 为现有 API 添加端点
- 用户提及“API”“endpoint”“route”或“REST”
- 创建 CRUD 操作
实践要点
资料中列出的 HTTP 状态码包括:200 成功(GET、PUT、PATCH)、201 已创建(POST)、204 无内容(DELETE)、400 错误请求(验证失败)、401 未认证、403 无权限、404 未找到、409 冲突(重复)、500 内部服务器错误。
响应格式建议保持统一结构:成功时为 {"success": true, "data": {...}};错误时为 {"error": "...", "details": {...}};列表分页时附带 pagination(page、limit、total)。
安全清单包括:受保护路由要求认证、授权检查(用户拥有资源)、所有字段输入验证、防止 SQL 注入(使用参数化查询)、公开端点限流、响应中不含敏感数据(密码、令牌)、正确配置 CORS、设置请求大小限制。
错误处理建议使用集中式错误处理器,并在生产环境不泄露错误细节。资料还给出测试示例(如 POST /api/users 返回 201、拒绝无效 email 返回 400)和 JSDoc 风格的端点文档模板。
限制
仅当任务明确匹配上述范围时使用该技能。输出不能替代针对具体环境的验证、测试或专家审查。若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。资料未提供该技能的收费、价格或平台等信息。