一个 API 的 OpenAPI 文件可以看起来很整洁，却仍然让每个消费者猜测部分失败后会发生什么。

为什么需要这个 Skill

API 设计质量评审用于在实现或版本演进前检查 API 契约，把输入、输出、错误、权限、生命周期和消费者影响写到足够可验证。

Skill 用来做什么

在实现或版本演进前，依据提供的 API 设计开展评审。按 operation 建立覆盖矩阵，检查资源命名、请求/响应字段与边界、错误和 HTTP 状态、认证/授权、幂等与重试、分页、限流、版本演进、消费者迁移、隐私和可观测性。

每项缺口都要绑定 API-## 发现，注明 operation、来源和证据、状态、消费者影响与兼容风险、负责人和决策问题，以及验证方法。一个请求/响应样例或 OpenAPI 文件只能证明材料存在，不足以证明契约完整或兼容。

Awesome QA Skills 按语言和测试阶段组织 Skill；系列总览 介绍通用安装方式。

它不做什么

这个 Skill 不调用 API、不执行安全或性能测试，也不批准版本策略。它不会凭惯例补造缺失的字段、错误、权限、重试、限流或幂等行为。缺少运行身份、时间、环境、输入、响应和原始结果时，运行状态仍为未执行或未评估。

它主要检查哪些内容

operation 级维度复核问题需要保留的证据
资源与请求/响应命名、必填字段、类型、可空性和边界是否明确？有版本的 Schema 和有来源的样例
错误与状态每个 operation 的业务码、HTTP 状态和重试含义是否定义？错误目录、操作例外、消费者行为
身份与副作用谁可以调用？如何避免重复或未授权写入？授权规则、幂等/重试契约、状态副作用
集合行为是否说明分页、排序、过滤和限流？契约来源和消费者约束
演进与迁移支持哪些新旧客户端/服务端组合？如何通知消费者？版本策略、迁移顺序、兼容证据
隐私与可观测性响应/日志允许出现什么？如何追踪一次操作？脱敏和关联规则

一个样例不能证明一个 operation 已经完整覆盖。记录已声明的例外和消费者特定约束，不要假设一份响应适用于所有人。

开始之前先审计输入

围绕“契约发现”开始分析时，先把输入分成六种状态。缺口不会自动变成失败，但也不能被隐藏在结论里。

状态含义本 Skill 的处理方式
known材料直接证明的事实标出来源、版本和时间，允许进入判断
missing本轮需要但尚未提供的材料列出最小补证动作，结论保持受限
conflicting来源之间互相矛盾并列来源和冲突点，交给负责人裁决
stale材料存在但版本或时间已经过期标出新鲜度，不把旧结论当当前事实
out_of_scope有关但不在本轮范围内明确排除，避免分析悄悄扩大
assumptions为继续分析而暂时采用的假设写出验证方式和失效条件

至少把输入版本、范围、环境、证据位置和负责人放在一起。没有运行记录时，只能交付分析、设计或验证计划，不能写执行通过。

从问题到结构化发现

API-## 发现字段

每条发现都要注明稳定的 operation、来源/证据、状态（assessed、missing、conflicting、stale 或 unassessed）、消费者/数据/安全影响与兼容风险及 P0–P3 依据、负责人及决策/迁移问题，以及含前置条件、动作、预期结果和原始证据要求的验证方法。事实、推断、建议和 Human 决策要分开。

一个完整案例

本节按输入、分析、发现、决策和验证展开；材料不足时保留 missing、conflicting 或 assumptions，不把它们改写成通过。

输入

材料这次提供什么缺失时怎么处理
契约材料OpenAPI、请求与响应示例、状态码和版本策略未定义字段列为缺口，不要猜
消费者上下文移动端、Web、计费、重试行为和发布顺序写出尚未咨询的消费者
风险边界授权、幂等、状态变化和向后兼容发布批准仍由负责人决定

可以这样调用：


请使用 api-design-quality-review Skill。

任务：在移动端、Web 端和计费服务接入前，评审订阅取消 API
输入材料：[需求、版本、链接、日志、报告或数据路径]
范围：[本次包含和排除的对象]
未知项：[缺失的环境、账号、数据或权限]
期望输出：[按风险排序的发现、证据状态和下一步动作]

先审计输入。分开写事实、假设和待确认问题。没有运行记录时不要声称已经执行。

分析

先从一个边界清楚的小回合开始：在移动端、Web 端和计费服务接入前，评审订阅取消 API。对取消订阅，需要定义订阅已经取消、计费服务不可用和请求重复时的行为。契约应该告诉消费者是重试、轮询、展示最终状态，还是请求人工介入。

交接产物要同时保留输入版本、时间窗口、证据索引、负责人和下一次验证动作。Skill 可以整理不确定性，不能制造缺失的产物。

发现

以下是评审候选格式，不是执行结果：

字段示例
ID / operationAPI-01 —— POST /subscriptions/{id}/cancel
来源 / 状态提供的取消设计及其版本；尚未定义重复请求和计费服务故障行为时标为 missing
影响 / 兼容风险移动端、Web 和计费服务可能对重试或最终状态作出冲突判断；按项目影响证据排序
负责人 / 决策API 负责人确认重复取消规则；消费者负责人确认迁移要求
验证规则定义后复核请求/响应与消费者样例；运行结论需有调用身份、环境、输入、输出、日志和原始结果

决策

API 负责人决定契约与版本策略。移动端、Web 和计费负责人提供兼容和迁移约束；Skill 负责呈现取舍，不替团队批准方案。

验证

实现前确认每个受影响 operation 都有适用来源、明确边界、消费者预期和可关闭的决策。这属于设计证据，不要称为兼容性或运行时测试。

发现如何进入下一阶段

交接产物

输出字段它要回答什么示例状态
契约发现缺失、冲突、过期或不可验证的 API 规则API-##、影响和来源
消费者影响客户端哪些行为会变得模糊或不安全受影响消费者和版本
就绪动作需要明确的字段、错误、策略或迁移决定负责人和关闭证据

没有运行记录、查询结果或原始产物时，不要写“已通过”。好的评审会走一遍消费者主流程、一条失败路径和一次版本变化。它不会用接口数量来批准设计。

下一步路由

将缺失的 operation 规则交给 API 负责人，将迁移问题交给各消费者负责人。交接时保留 operation、版本、证据状态、决策问题和兼容风险。

怎样准备更好的输入

提供 API 目标、operation、OpenAPI/契约版本、请求/响应样例、所有已知消费者、授权模型、错误与重试规则、分页/限流、发布顺序和迁移说明。标明哪些消费者或版本尚未复核，不要让一个样例代替其余情况。

和其他 Skill 怎么配合

容易踩的坑

  1. 只看接口结构，不走消费者流程。
  2. 把 200 响应当成完整成功契约。
  3. 把版本和重试行为留给实现者自行猜测。

安装与调用

全局安装这个 Skill：


npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/api-design-quality-review -g

安装后使用 api-design-quality-review Skill，并附上真实项目材料。

常见问题

代码还没写可以评审吗？

可以，这正是它的用途：在契约选择变成兼容性负担之前发现不可验证或冲突的地方。

这个 Skill 会替团队决定 API 版本吗？

不会。它展示取舍与证据缺口，版本决定仍由负责人做。

参考

源 Skill 与执行契约

完整执行契约位于 API 设计质量评审 提示词。调用 Skill 前先阅读它；提示词定义了详细流程和输出契约。源目录 中还包含入口文件以及实际存在的配套资料。

入口文件重点约束操作契约、错误模型、授权、幂等、兼容性和消费者影响。写结论前先阅读配套提示词，并保留这个 Skill 的决策边界。

参考链接

安全测试白盒测试背靠背测试本地化测试边界测试
分享