SuperAPI AI 工具集

api-design-principles

编程与开发

查看项目

更新于 10-16 07:22

技能介绍

用途:该技能聚焦 REST 与 GraphQL API 设计原则,用于设计新 API、重构现有 API、制定团队设计标准、评审 API 规范、在 REST 与 GraphQL 之间迁移、编写开发者友好文档,以及针对移动端或第三方集成优化 API。

主要能力:REST 方面强调面向资源的架构,资源用名词、动作用 HTTP 方法,URL 表示资源层级,命名一致;说明 GET、POST、PUT、PATCH、DELETE 的语义。GraphQL 方面强调 schema 优先,用类型定义领域模型,查询读取、变更修改、订阅实时更新,客户端按需取数、单一端点、强类型 schema、内置内省。版本策略涵盖 URL 版本(/api/v1/users)、请求头版本(Accept: application/vnd.api+json; version=1)和查询参数版本(/api/users?version=1)。

最佳实践:REST 建议集合用复数名词、无状态、正确使用 HTTP 状态码、从第一天规划版本、分页、限流、用 OpenAPI/Swagger 提供交互式文档。GraphQL 建议 schema 优先、用 DataLoader 避免 N+1、在 schema 与解析器层校验输入、在变更负载中返回结构化错误、使用游标分页(Relay 规范)、用 @deprecated 指令渐进迁移、监控查询复杂度与执行时间。

常见陷阱:REST 的过度取数/取数不足、破坏性变更、错误格式不一致、缺少限流、文档缺失、忽视 HTTP 语义、API 结构与数据库 schema 紧耦合。

限制:更详细的模式与示例位于 references/details.md,需在该文件导航层级不足时阅读。资料未提供安装命令、收费、价格或平台信息。