⚡

API设计审查技能Skill api-review

这个技能用于自动审查 API 设计，确保符合最佳实践、一致性和常见问题诊断。它支持多种 API 类型（如 REST、GraphQL、gRPC），提供结构化报告，帮助优化开发流程。关键词：API 审查, 设计优化, 最佳实践, 一致性检查, 问题诊断, 自动化报告。

架构设计 0 次安装 0 次浏览 更新于 3/11/2026

name: API 审查 description: 审查 API 设计的最佳实践、一致性和常见问题 allowed-tools: 读取, 全局, 搜索, 任务 argument-hint: “[规范文件或模式]”

API 审查命令

审查 API 设计的最佳实践、一致性和潜在问题。

用法

/sd:api-review [规范文件或模式]

参数

  • 规范文件或模式（可选）：OpenAPI 规范、API 文件或通配符模式的路径
    • 如果提供：审查指定的文件
    • 如果省略：搜索常见的 API 规范文件（openapi.yaml、swagger.json 等）

示例

/sd:api-review openapi.yaml
/sd:api-review src/api/**/*.ts
/sd:api-review

工作流程

  1. 定位 API 定义

    • 如果提供规范文件，读取它
    • 否则，搜索：openapi.yaml、openapi.json、swagger.yaml、swagger.json、*.graphql、*.proto
    • 同时在代码中查找路由/端点定义

  2. 启动 API 审查代理 使用 api-reviewer 代理分析 API 设计。代理将：

    • 识别 API 类型（REST、GraphQL、gRPC）
    • 应用加载技能中的最佳实践
    • 生成结构化审查报告

  3. 呈现发现 显示按以下类别组织的审查：

    • 关键问题（必须修复）
    • 警告（应该处理）
    • 建议（可有可无）
    • 正面观察

审查内容

REST API

  • 资源命名和 URL 结构
  • HTTP 方法使用
  • 状态码
  • 错误响应格式
  • 分页模式

GraphQL API

  • 模式设计
  • 查询复杂性
  • N+1 问题预防
  • 错误处理

gRPC API

  • 消息设计
  • 服务模式
  • 向后兼容性

跨领域

  • 版本策略
  • 速率限制
  • 幂等性
  • 安全模式
  • 文档质量

输出

该命令生成结构化审查报告，包括：

  • API 摘要和总体评估
  • 按严重性分类的问题
  • 具体建议和示例
  • 需要加强的正面模式