SuperAPI AI 工具集

api-endpoint-builder

编程与开发

查看项目

更新于 11-03 03:14

技能介绍

用途

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 风格的端点文档模板。

限制

仅当任务明确匹配上述范围时使用该技能。输出不能替代针对具体环境的验证、测试或专家审查。若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。资料未提供该技能的收费、价格或平台等信息。