SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 10-16 03:36

技能介绍

用途:设计清晰、一致、对开发者友好的 REST API,也可用于评审既有 API 设计、建立团队 API 标准,以及设计请求/响应格式、分页、版本控制和认证方案。

主要能力:以资源(名词)为中心建模,而非动词;保持 URL 结构、响应格式与行为的一致可预测;提供明确契约,包括显式 schema、已记录错误和带版本的端点;优化开发者体验,如可读的错误信息、示例和合理默认值。

使用方式(快速检查清单):识别资源及其关系;定义 CRUD 操作与自定义动作并匹配正确 HTTP 方法;设计一致的请求/响应 schema 与信封格式;规划错误格式,含状态码、错误码和字段级细节;编写带示例的 OpenAPI 规范;最后从一致性、安全性和可用性角度评审。方法速查:GET 读取、幂等、无请求体;POST 创建、非幂等、有请求体;PUT 替换、幂等、有请求体;PATCH 部分更新、幂等(标注为 Yes*)、有请求体;DELETE 删除、幂等、无请求体。

参考文档:endpoints.md(URL 设计、HTTP 方法、资源建模)、requests-responses.md(请求/响应格式、请求头、内容类型)、status-codes.md(状态码与错误处理)、pagination-filtering.md(分页、过滤、排序、搜索)、versioning.md(版本策略)、openapi.md(OpenAPI 规范与文档)、security.md(认证、授权、限流)、tdd-patterns.md(REST 端点的测试优先模式、supertest 模板)、review-checklist.md(校验、认证、性能、文档的评审清单)。

不适用场景:消费外部 API 应使用 api-integration;为 API 编写测试应使用 testing-strategy;评审现有 API 安全应使用 security-audit;若认证机制本身是全部任务,评审用 security-audit,从零设计仍可用本技能。

限制:资料未提供具体收费方式、价格、支持平台或运行环境要求,暂未提供。