SuperAPI AI 工具集

api-patterns

编程与开发

查看项目

更新于 10-16 06:16

技能介绍

用途:这是一套 API 设计原则与决策参考,面向 2025 年的 API 设计实践,核心目标是帮助使用者学会“思考”而非照搬固定模式。内容按主题分文件组织,提供内容地图,建议只阅读与当前需求相关的文件。

主要能力:各文件覆盖 REST 与 GraphQL、tRPC 的选型决策树;REST 的资源命名、HTTP 方法与状态码;响应结构中的信封模式、错误格式与分页;GraphQL 的 schema 设计、适用场景与安全;tRPC 在 TypeScript 单仓库与类型安全场景的应用;URI、Header、Query 三种版本管理方式;JWT、OAuth、Passkey、API Key 等鉴权模式选择;令牌桶与滑动窗口限流;OpenAPI/Swagger 文档最佳实践;以及针对 OWASP API Top 10 的安全测试。

使用方式:先查看内容地图,按需求读取对应文件,例如选型看 api-style.md,设计 REST 看 rest.md,梳理响应看 response.md。设计前可对照决策清单自检:是否询问过 API 消费者、是否针对当前上下文选定风格、是否定义一致的响应格式、是否规划版本策略、是否考虑鉴权、是否规划限流、是否确定文档方案。脚本 scripts/api_validator.py 可用于 API 端点校验,命令为 python scripts/api_validator.py <project_path>,请保持原样。

适用场景与限制:适合 API 设计初期的选型与规范制定、评审检查、安全与文档规划。反模式部分明确不建议默认一切用 REST、在端点中使用动词(如 /getUsers)、返回不一致的响应格式、向客户端暴露内部错误、跳过限流。资料未提供具体实现细节与更多示例,相关实现需参考其关联技能(后端开发、数据库设计、安全加固)。