用途
API Design 技能用于按照行业最佳实践设计健壮、可扩展的 REST 与 GraphQL API。它面向需要构建或规范 API 接口的开发者,提供从资源命名到文档编写的成套设计模式与示例代码。
主要能力
REST API 模式
- 资源命名:推荐使用名词、复数、层级结构,例如 GET /api/v1/users、GET /api/v1/users/{id}/posts;避免在 URL 中使用动词、单数形式或动作词。
- HTTP 方法:列出 GET(读取,幂等且安全)、POST(创建,非幂等)、PUT(替换,幂等)、PATCH(更新,幂等)、DELETE(删除,幂等)的用途与特性。
- 响应码:涵盖成功(200、201、204)、客户端错误(400、401、403、404、409、422、429)与服务端错误(500、503)的语义。
- 标准响应格式:给出成功响应、错误响应与分页响应的 JSON 结构示例,包含 data、meta、links 等字段。
Next.js API 路由
提供 Route Handler 与动态路由的示例代码,演示如何使用 zod 进行请求校验、返回分页数据、处理 422 校验错误与 404 未找到错误。
认证模式
给出基于 jose 的 JWT 中间件示例,从 Authorization 头提取 Bearer token,校验失败时返回 401。
限流
给出基于 @upstash/ratelimit 与 @upstash/redis 的限流中间件示例,使用滑动窗口(如 10 秒 10 次请求),超限时返回 429 并附带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 响应头。
API 版本控制
介绍 URL 版本控制(推荐,如 /api/v1/users)、请求头版本控制(Accept: application/vnd.frankx.v1+json)与查询参数版本控制(建议避免)。
OpenAPI 文档
给出 openapi.yaml 示例,包含 info、paths、components/schemas 等结构,用于描述接口与数据模型。
反模式与推荐做法
列出应避免的做法(URL 含动词、命名不一致、错误返回 200、列表无分页、暴露内部 ID、无限流)与推荐做法(名词资源 URL、一致响应格式、正确状态码、分页、公开 ID 用 UUID、全端点限流)。
使用方式
该技能以文档与代码示例形式提供,用户可参照其中的模式与示例代码,在自身项目中应用 REST/GraphQL 设计规范、Next.js 路由实现、认证与限流中间件、版本控制策略以及 OpenAPI 文档编写。具体安装或调用方式暂未提供。
适用场景
适用于需要设计或审查 REST/GraphQL API 的开发者,尤其是使用 Next.js 构建 API 路由、需要统一响应格式、认证、限流与文档规范的团队。
限制
资料未提供该技能的安装命令、运行环境要求、收费信息或平台支持范围,这些内容暂未提供。