api-blackbox-test-planner

name	api-blackbox-test-planner
description	编码前接口黑盒测试方案 Skill。当用户需要在开发或执行测试前，根据需求、技术方案和项目现状梳理测试范围、直接影响、扩散影响、业务场景拆解、兼容性验证、测试用例、接口 x 字段语义等价类矩阵、场景 x 边界/异常覆盖矩阵、跨接口一致性用例、边界测试、安全测试、跨接口集成编排链路、性能测试建议和测试数据计划时使用。

编码前接口黑盒测试方案

目标

在编码前或执行接口测试前，输出可直接指导执行阶段的黑盒测试方案。方案必须先基于需求分析和技术方案做测试范围初判，拆分所有可识别的业务场景，覆盖直接影响和可能的扩散影响，再覆盖向下兼容、边界条件、安全风险、接口 x 字段语义等价类矩阵、场景 x 边界/异常覆盖矩阵、逻辑类似接口的跨接口一致性用例、跨接口集成编排、性能测试建议、数据准备和复杂接口编排。

测试方案不得只围绕 Happy Path 设计。每个业务场景必须分析正常路径、适用异常路径、字段边界值、状态边界、权限边界、数据存在性边界和跨接口链路边界；确实不适用的边界或异常必须写明需求、技术方案或业务规则依据。

文件输出

本阶段必须将完整测试方案写入 Markdown 文件。默认路径为：

tests/【需求】_YYYYMMDD/测试方案.md

规则：

• 【需求】 使用用户需求的简短标题；如果用户未提供标题，应根据需求内容提炼 8 到 20 个中文字符。
• YYYYMMDD 使用执行当天日期，例如 20260428；如果用户明确指定日期，以用户指定日期为准。
• 文件名中的 /、空格、冒号、引号等不适合作为路径的字符应替换为 _。
• 写入文件后，在回复中说明文件路径和方案摘要。
• 无法写入文件时，必须标记为阻塞并说明原因，不得只在对话中输出完整方案后视为完成。

分析输入

阅读需求、变更文件、路由定义、接口处理器、中间件、DTO、API 文档、已有测试、配置和数据库访问逻辑，识别：

• 基于需求分析和技术方案推导的测试范围、直接影响和潜在扩散影响。
• 从需求、技术方案、验收标准、状态机、用户角色、权限规则、数据生命周期、业务前置条件和失败分支中拆分所有业务场景；业务场景必须覆盖主流程、可选流程、异常流程、状态流转、重复/回退/跳步骤、历史数据和兼容旧行为。
• 如果涉及公共方法、共享组件、公共校验、公共查询、权限逻辑、缓存逻辑、序列化结构、错误处理或数据模型，识别可能被间接影响的其他接口、任务、消费者和业务链路。
• 目标接口的方法、路径、请求字段、响应字段、鉴权、限流和副作用。
• 每个目标接口中有业务语义的请求字段和查询字段，以及同名、近义或可互相映射的字段，例如 account、userID、手机号、靓号、外部 ID、资源 ID、状态字段、枚举字段和筛选字段。
• 字段语义等价类：同一字段在业务上可能代表的不同输入类别，例如账号字符串、用户 ID、靓号、不存在账号、无手机号账号、禁用用户、已删除用户、跨租户用户、空字符串、非法格式、超长值。
• 逻辑类似接口：共享字段语义、共享查询规则、共享权限边界、共享数据来源或共享响应契约的接口，即使实现或路由不同，也必须识别出来并设计一致性验证。
• 现有客户端、旧测试或文档中体现的历史接口契约。
• 接口读取或写入的表、集合和关键字段。
• 多接口业务流程中的上下游接口、执行顺序、可并行节点、分支条件和数据传递字段；即使某些上下游接口不在本次变更范围内，只要是当前业务流程必需步骤，也要纳入集成编排测试分析。
• 变更接口是否存在性能风险，例如高频调用、大数据量查询、复杂 JOIN、循环调用、外部依赖、锁竞争、异步积压、缓存失效、分页/排序/搜索或批量写入。
• 执行测试所需的环境信息：base URL、token、服务启动方式、数据库实例、固定测试数据。

必须输出

**测试范围**
- 范围内：
- 范围外：
- 假设：

**影响范围初判**
| 影响ID | 来源 | 证据来源 | 置信度 | 影响类型 | 影响对象 | 风险等级 | 测试覆盖方式 | 关联用例/矩阵/链路 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |

**业务场景拆解**
| 场景ID | 需求/业务规则来源 | 业务场景 | 用户/角色 | 前置状态/数据 | 主流程 | 分支/异常/边界点 | 风险等级 | 关联接口/链路 | 关联用例/矩阵 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |

**兼容性验证**
| 契约区域 | 既有行为 | 验证方式 | 风险 |
| --- | --- | --- | --- |

**测试数据计划**
| 数据用途 | 表/集合 | 必填字段 | 构造或获取方式 | 清理方式 |
| --- | --- | --- | --- | --- |

**接口 x 字段语义等价类矩阵**
| 矩阵单元 ID | 接口 | 字段 | 字段语义 | 等价类/取值类别 | 代表值或构造方式 | 必测级别 | 关联用例 ID | 预期响应/错误 | DB/副作用预期 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |

**场景 x 边界/异常覆盖矩阵**
| 覆盖单元 ID | 场景ID | 覆盖类型 | 输入/状态组合 | 边界值或反例 | 必测级别 | 关联用例 ID | 预期响应/错误 | DB/副作用预期 | 豁免依据 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |

**测试用例**
| ID | 场景 | 前置数据 | 请求 | 预期响应 | 预期数据库状态 |
| --- | --- | --- | --- | --- | --- |

**边界测试**
| ID | 参数/字段 | 边界值 | 请求 | 预期响应 | 风险 |
| --- | --- | --- | --- | --- | --- |

**安全测试**
| ID | 风险类型 | 攻击/异常输入 | 请求位置 | 预期防护结果 | DB/日志验证 |
| --- | --- | --- | --- | --- | --- |

**接口编排/集成测试**
| 链路 ID | 场景 | 接口顺序/依赖 | 是否包含非本次变更接口 | 数据提取与传递 | 预期结果 | DB 验证 |
| --- | --- | --- | --- | --- | --- | --- |

**跨接口一致性测试**
| 一致性 ID | 逻辑类似接口组 | 字段/业务规则 | 等价类覆盖 | 对比方式 | 关联用例 ID | 预期一致性 |
| --- | --- | --- | --- | --- | --- | --- |

**补充验证项**
| ID | 验证类型 | 场景 | 验证方式 | 预期结果 |
| --- | --- | --- | --- | --- |

**性能测试评估与建议**
| 接口/链路 | 是否建议性能测试 | 原因 | 建议场景 | 指标建议 | 数据量/并发建议 |
| --- | --- | --- | --- | --- | --- |

用例覆盖要求

• 测试范围必须覆盖 影响范围初判 中的直接影响和潜在扩散影响；每个影响必须标明证据来源和置信度（高/中/低）。如果某个影响不需要测试，必须写明范围外依据或豁免原因。
• 必须根据需求、技术方案、验收标准、状态机、角色权限、数据生命周期和接口链路拆分所有业务场景，并输出 业务场景拆解。不能只列接口或需求点，必须写清楚每个业务场景的前置状态、主流程、分支、异常和边界点。
• 每个业务场景必须在 场景 x 边界/异常覆盖矩阵 中至少覆盖正常路径和适用的反向路径；反向路径包括参数非法、字段缺失、边界值、权限不足、状态不允许、数据不存在/重复/禁用/删除、依赖失败、重复提交、乱序请求和兼容性风险中的适用项。
• 对每个业务场景涉及的数字、金额、时间、长度、数组大小、枚举、状态、分页、排序、筛选、资源 ID、用户/租户/角色字段，必须列出适用边界值和越界值，并关联到用例 ID。只写一个正常值或只测 Happy Path 不得视为覆盖完整。
• 如果某个业务场景只有 Happy Path 用例，必须写明为什么不存在适用异常、边界、权限、状态或数据变体；核心、写入、鉴权、资产、订单、审批、支付、权限和敏感数据场景不得用泛化理由豁免。
• 置信度为低的影响项不能直接忽略；必须在 reviewer 阶段继续核实，或补充代码搜索、GitNexus、接口文档、调用链、数据库 schema、日志/监控等证据。
• 对公共方法、共享组件、公共校验、公共查询、权限逻辑、缓存逻辑、序列化结构、错误处理或数据模型带来的扩散影响，必须为受影响接口、任务、消费者或业务链路设计验证方式。

影响范围置信度标准

• 高：至少有两类相互印证的证据，例如需求/技术方案明确说明，且代码 diff、调用链、接口文档、数据库 schema、配置或 GitNexus 分析能确认影响对象。
• 中：有一类直接证据或多类间接证据，例如技术方案提到可能影响某模块，或代码搜索发现共享方法调用方，但缺少完整调用链或运行时证据。
• 低：只有推断或经验判断，缺少代码、文档、调用链、schema、日志/监控等直接证据；低置信度项必须在 reviewer 阶段继续核实，不得作为“无须测试”的依据。
• 如果置信度无法判断，按 低 处理，并写明需要补充的证据。

证据来源应写具体来源，例如需求文档段落、技术方案章节、代码文件/函数、GitNexus 查询结果、API 文档路径、数据库表名、配置项、日志/监控指标或历史缺陷记录。

• 正常路径。
• 所有业务场景的 Happy Path 只是最低覆盖要求，不能替代边界、异常、权限、状态、数据一致性和跨接口链路覆盖。
• 对每个目标接口输出 接口 x 字段语义等价类矩阵。矩阵必须细到“接口 + 字段 + 字段语义 + 等价类”单元，不能只按需求 ID 或场景粗粒度列覆盖。
• 对用户身份、账号、资源 ID、状态、枚举、筛选条件等关键字段，至少区分有效值、格式非法、值不存在、权限不可见、状态不可用和空/缺失等价类；如果字段存在业务特例，例如靓号、无手机号、禁用、删除、跨租户、历史账号，也必须单列。
• 每个必测矩阵单元必须关联至少 1 个用例 ID；不适用或低优先级矩阵单元必须写明理由，不能留空。
• 逻辑类似接口必须分别设计用例并做跨接口一致性验证。可以复用测试数据和断言思路，但不得用接口 A 的执行结果替代接口 B 的执行结果。
• 必填字段缺失。
• 类型、枚举、范围、长度和边界值。
• 边界测试，例如 page < 0、page = 0、pageSize = 0、超大分页、空字符串、超长字符串、最小/最大金额、最早/最晚时间、数组为空和数组超长。
• 安全测试，例如 XSS、SQL 注入、NoSQL 注入、命令注入、路径穿越、越权访问、IDOR、敏感字段泄露、批量赋值、重放请求、弱鉴权和错误信息泄露。
• 鉴权、权限、租户或用户隔离。
• 不存在、重复、禁用、删除、过期等异常数据。
• 写接口的幂等、重试和重复提交行为。
• 列表接口的分页、筛选、排序和默认值。
• 状态码、响应结构、错误码、字段含义和数据库副作用的向下兼容性。
• 多接口编排/集成链路，包括串行依赖、并行前置、条件分支、前置接口失败、前置响应缺失关键字段、后续接口使用旧值或错误值；链路可以包含本次未变更但业务流程必经的接口。
• 其他未列举但根据接口语义、业务规则、历史缺陷、依赖服务、异步任务、缓存、消息队列、幂等键、限流和审计要求需要验证的场景。

边界测试设计要求

• 对所有业务场景涉及的数字、分页、金额、时间、长度、数组大小和枚举字段列出边界值；边界值必须回填到 场景 x 边界/异常覆盖矩阵，并关联具体用例。
• 边界值必须同时考虑字段级边界和业务规则边界，例如最小/最大金额、刚好达到额度、超过额度 1 单位、状态刚好可操作、状态刚好不可操作、开始/结束时间相等、跨天/月/年边界、数组为空/1 个/最大个数/超过最大个数。
• 对查询接口至少考虑负数分页、零值分页、超大分页、排序字段非法、筛选条件为空和筛选条件冲突。
• 对写接口至少考虑空值、缺失字段、超长字段、非法枚举、重复提交、金额精度和时间边界。
• 边界测试必须说明预期状态码、错误码、错误消息和是否允许产生数据库写入。

安全测试设计要求

• 针对所有用户可控输入设计 XSS 和注入类 payload，至少覆盖 query、path、header 和 body 中的关键字段。
• 对涉及用户、租户、角色、订单、资源 ID 的接口设计越权和 IDOR 场景。
• 对写接口设计批量赋值、重放请求、重复提交和幂等绕过场景。
• 对错误响应设计信息泄露检查，避免 SQL、堆栈、内部服务地址、密钥或敏感字段暴露。
• 安全测试应以黑盒验证为主，不要求破坏性攻击；涉及高风险或可能污染环境的 payload，应标记需要隔离测试环境。

补充验证判断

需求未列举但存在以下情况时，必须补充测试项：

• 接口依赖缓存、异步任务、消息队列、第三方服务、定时任务或回调。
• 接口包含金额、积分、库存、权限、状态机、审批流、订阅、支付或结算。
• 接口有历史缺陷、线上事故、兼容旧客户端或多端共用。
• 接口涉及审计日志、操作记录、通知、搜索索引或统计计数。
• 接口存在并发、重试、超时、限流、熔断或降级逻辑。

接口编排/集成测试设计要求

• 明确每条链路的入口接口、终止接口和业务目标。
• 明确链路中的接口是否属于本次变更范围；未变更接口如果是业务流程前置、后置或数据来源，也应纳入集成测试链路。
• 明确为什么需要纳入未变更接口，例如获取 token、创建前置资源、查询可用额度、创建订单后支付、支付后查询状态、先上传文件再提交业务单据。
• 明确接口之间的数据依赖，例如从接口 1 响应中提取 orderId，作为接口 2 的 path 参数或 body 字段。
• 明确并行前置场景，例如先分别请求接口 1 和接口 2，再合并二者返回的数据请求接口 3。
• 明确条件分支，例如接口 1 返回状态 A 时请求接口 2，返回状态 B 时请求接口 3。
• 明确失败链路，例如前置接口失败、返回空数据、返回不兼容字段时，后续接口是否应停止、降级或返回明确错误。
• 明确每一步需要验证的响应契约和数据库状态，而不是只验证最后一步。
• 如果判断不需要接口编排测试，必须写明原因。

跨接口一致性设计要求

• 识别逻辑类似接口，例如公开查询和后台查询、精简查询和完整查询、按账号查询和按用户 ID 查询、移动端接口和管理端接口、旧接口和新接口。
• 对逻辑类似接口列出共同字段语义和差异点，明确哪些行为必须一致，哪些差异是产品或权限设计允许的。
• 对相同字段语义的同一等价类，必须分别请求每个接口并比较状态码、错误码、响应字段语义、权限过滤、空结果语义和数据库副作用。
• 跨接口一致性用例必须有独立 ID，关联到每个参与接口的普通用例或矩阵单元。
• 如果某个逻辑类似接口不纳入一致性测试，必须说明业务或权限差异证据，不能只写“逻辑类似已测过”。

性能测试建议判断

编码前必须评估变更接口或关键集成链路是否需要性能测试，并输出建议，不要求在本阶段执行性能测试。

建议做性能测试的常见条件：

• 接口是高频入口、核心交易链路、列表/搜索/分页接口或移动端首屏依赖接口。
• 变更涉及数据库查询、复杂 JOIN、排序、模糊搜索、聚合统计、大字段返回或批量写入。
• 变更涉及缓存策略、异步任务、消息队列、第三方调用、文件上传下载或回调链路。
• 变更可能影响锁、库存、余额、额度、订单状态、支付状态、计数器或热点资源。
• 新增或修改循环调用、N+1 查询、跨服务调用、重试、限流、熔断或降级逻辑。
• 历史上该接口或相关链路有慢查询、超时、抖动、容量不足或线上事故。

性能测试建议至少说明：

• 是否建议性能测试：是、否、暂不确定。
• 建议原因：结合项目和需求说明，不只写“可能有性能风险”。
• 建议场景：单接口基准、集成链路压测、分页大数据量、批量写入、并发冲突、缓存命中/未命中、依赖服务慢响应等。
• 指标建议：P50/P95/P99、错误率、吞吐量、并发数、CPU/内存、数据库慢查询、锁等待、队列积压、外部依赖耗时。
• 数据量和并发建议：给出符合业务的初始建议；如果证据不足，标记需要业务流量或历史监控补充。

兼容性判断

以下变化即使新需求功能通过，也必须列为兼容性风险：

• 删除或重命名响应字段。
• 修改字段类型、是否可为空、默认值、枚举值、排序或分页默认值。
• 修改成功或失败状态码。
• 修改客户端可能依赖的错误码字符串。
• 新增必填请求字段且没有默认值或迁移路径。
• 收紧已有调用方的鉴权或权限行为。
• 修改幂等、重复提交处理或写入副作用。
• 修改多接口链路中的字段传递、状态流转、步骤顺序或失败处理语义。
• 修改关键接口或链路的性能特征，例如响应时间、分页默认值、返回数据量、缓存命中路径或依赖调用次数。
• 修改逻辑删除、软删除可见性或审计字段。