| name | api-blackbox-test-planner |
| description | 编码前接口黑盒测试方案 Skill。当用户需要在开发或执行测试前，根据需求和项目现状梳理测试范围、兼容性验证、测试用例、边界测试、安全测试、跨接口集成编排链路、性能测试建议和测试数据计划时使用。 |
编码前接口黑盒测试方案
目标
在编码前或执行接口测试前，输出可直接指导执行阶段的黑盒测试方案。方案必须覆盖当前需求、向下兼容、边界条件、安全风险、跨接口集成编排、性能测试建议、数据准备和复杂接口编排。
文件输出
本阶段必须将完整测试方案写入 Markdown 文件。默认路径为：
tests/【需求】_YYYYMMDD/测试方案.md
规则：
【需求】 使用用户需求的简短标题；如果用户未提供标题，应根据需求内容提炼 8 到 20 个中文字符。YYYYMMDD 使用执行当天日期，例如 20260428；如果用户明确指定日期，以用户指定日期为准。- 文件名中的
/、空格、冒号、引号等不适合作为路径的字符应替换为 _。
- 写入文件后，在回复中说明文件路径和方案摘要。
- 无法写入文件时，必须标记为阻塞并说明原因，不得只在对话中输出完整方案后视为完成。
分析输入
阅读需求、变更文件、路由定义、接口处理器、中间件、DTO、API 文档、已有测试、配置和数据库访问逻辑，识别：
- 目标接口的方法、路径、请求字段、响应字段、鉴权、限流和副作用。
- 现有客户端、旧测试或文档中体现的历史接口契约。
- 接口读取或写入的表、集合和关键字段。
- 多接口业务流程中的上下游接口、执行顺序、可并行节点、分支条件和数据传递字段；即使某些上下游接口不在本次变更范围内，只要是当前业务流程必需步骤，也要纳入集成编排测试分析。
- 变更接口是否存在性能风险，例如高频调用、大数据量查询、复杂 JOIN、循环调用、外部依赖、锁竞争、异步积压、缓存失效、分页/排序/搜索或批量写入。
- 执行测试所需的环境信息：base URL、token、服务启动方式、数据库实例、固定测试数据。
必须输出
**测试范围**
- 范围内：
- 范围外：
- 假设：
**兼容性验证**
| 契约区域 | 既有行为 | 验证方式 | 风险 |
| --- | --- | --- | --- |
**测试数据计划**
| 数据用途 | 表/集合 | 必填字段 | 构造或获取方式 | 清理方式 |
| --- | --- | --- | --- | --- |
**测试用例**
| ID | 场景 | 前置数据 | 请求 | 预期响应 | 预期数据库状态 |
| --- | --- | --- | --- | --- | --- |
**边界测试**
| ID | 参数/字段 | 边界值 | 请求 | 预期响应 | 风险 |
| --- | --- | --- | --- | --- | --- |
**安全测试**
| ID | 风险类型 | 攻击/异常输入 | 请求位置 | 预期防护结果 | DB/日志验证 |
| --- | --- | --- | --- | --- | --- |
**接口编排/集成测试**
| 链路 ID | 场景 | 接口顺序/依赖 | 是否包含非本次变更接口 | 数据提取与传递 | 预期结果 | DB 验证 |
| --- | --- | --- | --- | --- | --- | --- |
**补充验证项**
| ID | 验证类型 | 场景 | 验证方式 | 预期结果 |
| --- | --- | --- | --- | --- |
**性能测试评估与建议**
| 接口/链路 | 是否建议性能测试 | 原因 | 建议场景 | 指标建议 | 数据量/并发建议 |
| --- | --- | --- | --- | --- | --- |
用例覆盖要求
- 正常路径。
- 必填字段缺失。
- 类型、枚举、范围、长度和边界值。
- 边界测试，例如
page < 0、page = 0、pageSize = 0、超大分页、空字符串、超长字符串、最小/最大金额、最早/最晚时间、数组为空和数组超长。
- 安全测试，例如 XSS、SQL 注入、NoSQL 注入、命令注入、路径穿越、越权访问、IDOR、敏感字段泄露、批量赋值、重放请求、弱鉴权和错误信息泄露。
- 鉴权、权限、租户或用户隔离。
- 不存在、重复、禁用、删除、过期等异常数据。
- 写接口的幂等、重试和重复提交行为。
- 列表接口的分页、筛选、排序和默认值。
- 状态码、响应结构、错误码、字段含义和数据库副作用的向下兼容性。
- 多接口编排/集成链路，包括串行依赖、并行前置、条件分支、前置接口失败、前置响应缺失关键字段、后续接口使用旧值或错误值；链路可以包含本次未变更但业务流程必经的接口。
- 其他未列举但根据接口语义、业务规则、历史缺陷、依赖服务、异步任务、缓存、消息队列、幂等键、限流和审计要求需要验证的场景。
边界测试设计要求
- 对所有数字、分页、金额、时间、长度、数组大小和枚举字段列出边界值。
- 对查询接口至少考虑负数分页、零值分页、超大分页、排序字段非法、筛选条件为空和筛选条件冲突。
- 对写接口至少考虑空值、缺失字段、超长字段、非法枚举、重复提交、金额精度和时间边界。
- 边界测试必须说明预期状态码、错误码、错误消息和是否允许产生数据库写入。
安全测试设计要求
- 针对所有用户可控输入设计 XSS 和注入类 payload，至少覆盖 query、path、header 和 body 中的关键字段。
- 对涉及用户、租户、角色、订单、资源 ID 的接口设计越权和 IDOR 场景。
- 对写接口设计批量赋值、重放请求、重复提交和幂等绕过场景。
- 对错误响应设计信息泄露检查，避免 SQL、堆栈、内部服务地址、密钥或敏感字段暴露。
- 安全测试应以黑盒验证为主，不要求破坏性攻击；涉及高风险或可能污染环境的 payload，应标记需要隔离测试环境。
补充验证判断
需求未列举但存在以下情况时，必须补充测试项：
- 接口依赖缓存、异步任务、消息队列、第三方服务、定时任务或回调。
- 接口包含金额、积分、库存、权限、状态机、审批流、订阅、支付或结算。
- 接口有历史缺陷、线上事故、兼容旧客户端或多端共用。
- 接口涉及审计日志、操作记录、通知、搜索索引或统计计数。
- 接口存在并发、重试、超时、限流、熔断或降级逻辑。
接口编排/集成测试设计要求
- 明确每条链路的入口接口、终止接口和业务目标。
- 明确链路中的接口是否属于本次变更范围；未变更接口如果是业务流程前置、后置或数据来源，也应纳入集成测试链路。
- 明确为什么需要纳入未变更接口，例如获取 token、创建前置资源、查询可用额度、创建订单后支付、支付后查询状态、先上传文件再提交业务单据。
- 明确接口之间的数据依赖，例如从接口 1 响应中提取
orderId，作为接口 2 的 path 参数或 body 字段。
- 明确并行前置场景，例如先分别请求接口 1 和接口 2，再合并二者返回的数据请求接口 3。
- 明确条件分支，例如接口 1 返回状态 A 时请求接口 2，返回状态 B 时请求接口 3。
- 明确失败链路，例如前置接口失败、返回空数据、返回不兼容字段时，后续接口是否应停止、降级或返回明确错误。
- 明确每一步需要验证的响应契约和数据库状态，而不是只验证最后一步。
- 如果判断不需要接口编排测试，必须写明原因。
性能测试建议判断
编码前必须评估变更接口或关键集成链路是否需要性能测试，并输出建议，不要求在本阶段执行性能测试。
建议做性能测试的常见条件：
- 接口是高频入口、核心交易链路、列表/搜索/分页接口或移动端首屏依赖接口。
- 变更涉及数据库查询、复杂 JOIN、排序、模糊搜索、聚合统计、大字段返回或批量写入。
- 变更涉及缓存策略、异步任务、消息队列、第三方调用、文件上传下载或回调链路。
- 变更可能影响锁、库存、余额、额度、订单状态、支付状态、计数器或热点资源。
- 新增或修改循环调用、N+1 查询、跨服务调用、重试、限流、熔断或降级逻辑。
- 历史上该接口或相关链路有慢查询、超时、抖动、容量不足或线上事故。
性能测试建议至少说明：
- 是否建议性能测试：是、否、暂不确定。
- 建议原因：结合项目和需求说明，不只写“可能有性能风险”。
- 建议场景：单接口基准、集成链路压测、分页大数据量、批量写入、并发冲突、缓存命中/未命中、依赖服务慢响应等。
- 指标建议：P50/P95/P99、错误率、吞吐量、并发数、CPU/内存、数据库慢查询、锁等待、队列积压、外部依赖耗时。
- 数据量和并发建议：给出符合业务的初始建议；如果证据不足，标记需要业务流量或历史监控补充。
兼容性判断
以下变化即使新需求功能通过，也必须列为兼容性风险：
- 删除或重命名响应字段。
- 修改字段类型、是否可为空、默认值、枚举值、排序或分页默认值。
- 修改成功或失败状态码。
- 修改客户端可能依赖的错误码字符串。
- 新增必填请求字段且没有默认值或迁移路径。
- 收紧已有调用方的鉴权或权限行为。
- 修改幂等、重复提交处理或写入副作用。
- 修改多接口链路中的字段传递、状态流转、步骤顺序或失败处理语义。
- 修改关键接口或链路的性能特征，例如响应时间、分页默认值、返回数据量、缓存命中路径或依赖调用次数。
- 修改逻辑删除、软删除可见性或审计字段。
