API测试分析文档生成器#

目的#

根据接口规格定义生成全面的API测试分析文档。将API定义转换为结构化的测试分析，确保覆盖参数校验、业务逻辑、响应验证和常见陷阱的测试点分析。

使用时机#

在以下情况下使用此技能：

• 为新API端点设计测试策略时
• 审查API测试覆盖完整性时
• 需要测试分析文档供团队评审时
• 针对常见陷阱审计API质量时
• 生成测试方案和测试点清单时

工作流程#

步骤1：解析接口定义#

从输入中提取：

1. 基本信息：端点路径、HTTP方法、描述
2. 请求参数：名称、类型、约束、必填/可选
3. 返回字段：名称、类型、描述
4. 业务规则：校验规则、状态转换、权限

支持的输入格式：

• OpenAPI/Swagger JSON/YAML
• 简化接口定义（Markdown格式）
• 自然语言描述

步骤2：生成参数校验测试点分析#

为每个参数基于类型生成测试点分析：

参数类型测试点分析维度string正常值、边界长度、空值、null、特殊字符、SQL注入风险、XSS风险、Unicode字符、编码问题integer正常值、最小/最大边界、零值、负数、小数（类型错误）、溢出、精度问题number正常值、精度、科学计数法、边界值、NaN、Infinityenum所有有效值、无效值、大小写敏感、null、空字符串、数字枚举booleantrue/false、字符串转换、数字转换、null、其他值array空数组、单元素、多元素、最大元素数、重复元素、无效元素、嵌套数组object完整对象、缺少必填字段、额外字段、空对象、嵌套对象深度datetime当前时间、过去时间、未来时间、闰年、无效日期、时区、格式错误、时间精度

步骤3：生成业务逻辑测试点分析#

识别规则模式并生成测试分析场景：

规则模式测试点分析存在性校验数据存在、不存在、已删除、逻辑删除、缓存不一致唯一性校验首次创建、重复尝试、并发创建、大小写敏感、特殊字符状态转换合法转换、非法转换、循环状态、终态、初始状态权限校验已授权、未授权、未登录、权限变更、角色变更、越权访问关联校验关联数据存在、不存在、已删除、外键约束、级联操作数量限制达到上限、超过上限、低于下限、批量操作限制、分页限制时间窗口有效期内、已过期、即将过期、时区影响

步骤4：生成响应验证测试点分析#

接口类型验证点分析列表查询结构完整性、分页字段、字段类型、空列表返回[]、null处理、排序详情查询必填字段存在、字段类型正确、404处理、null字段、关联数据完整性创建返回新ID、数据库验证、默认值、时间戳、返回字段完整性、状态码更新成功状态、数据变更验证、未变更字段保持原值、部分更新、全量更新删除成功状态、记录删除验证、软删除/硬删除、后续查询返回404、级联删除文件上传文件大小限制、文件类型、空文件、超大文件、文件名、多文件文件下载内容类型、文件名、文件完整性、断点续传、大文件分片

步骤5：生成安全测试点分析#

必须包含的安全测试分析：

• SQL注入：参数拼接、特殊字符转义、ORM框架使用、存储过程
• XSS攻击：输入过滤、输出转义、富文本处理、CSP策略
• 认证安全：Token强度、Token过期、Refresh机制、会话管理、暴力破解防护
• 授权安全：越权访问、水平越权、垂直越权、权限继承、权限缓存
• 敏感数据：密码加密存储、身份证号脱敏、日志脱敏、传输加密
• CSRF防护：Token验证、Referer检查、SameSite Cookie、双重提交
• 信息泄露：错误信息、堆栈跟踪、调试模式、敏感接口暴露
• 速率限制：IP限流、用户限流、接口限流、突发流量、熔断降级

步骤6：生成性能测试点分析#

适用时的性能测试分析：

• 响应时间阈值：P95、P99、平均响应、最大响应、超时设置
• 大数据量处理：分页深度、批量操作、大数据返回、内存占用
• 并发访问：锁竞争、死锁、连接池、线程池、异步处理
• 资源消耗：CPU、内存、磁盘IO、网络IO、文件句柄
• 缓存策略：缓存命中率、缓存穿透、缓存雪崩、缓存一致性
• 数据库性能：慢查询、索引使用、连接数、事务、锁等待

步骤7：对照常见陷阱检查#

最终确定前，验证Top 20必检项的覆盖：

类别必检项分析重点参数缺少必填、类型/格式错误、边界值验证是否考虑完整权限未认证访问、未授权访问权限矩阵是否覆盖安全SQL注入、XSS、敏感数据暴露安全场景是否分析业务幂等性、唯一性、状态转换业务规则是否完整响应状态码一致、字段完整、空结果响应契约是否验证性能响应阈值、分页限制、批量限制性能指标是否定义

参考 references/common-pitfalls.md 获取完整的140点清单。

输出格式#

单接口测试分析格式#

markdown

## API: {接口名称}

### 基本信息
- **端点**：{METHOD} {路径}
- **描述**：{接口描述}
- **标签**：{Swagger标签}
- **认证**：{是否需要认证}

### 请求参数分析

#### 1. {参数名} ({类型}, {必填/可选})
**约束条件**：{长度、格式、枚举值等}

**参数校验测试点分析**：
| 测试场景 | 测试值 | 预期结果 | 优先级 | 测试目的 |
|----------|--------|----------|--------|----------|
| 正常值 | {valid} | 成功 | P0 | 验证基本功能 |
| 边界值-最小 | {min} | 成功 | P1 | 验证下边界 |
| 边界值-最大 | {max} | 成功 | P1 | 验证上边界 |
| 边界值-超过 | {max+1} | 参数错误 | P1 | 验证越界处理 |
| 空值 | "" | 参数错误 | P0 | 验证空字符串 |
| null | null | 参数错误 | P0 | 验证null处理 |
| 特殊字符 | {special} | 参数错误 | P0 | 验证特殊字符过滤 |
| SQL注入 | {sql} | 参数错误 | P0 | 验证SQL注入防护 |
| XSS攻击 | {xss} | 参数错误 | P0 | 验证XSS防护 |

**风险分析**：{高/中/低}

#### 2. {参数名} ({类型}, {必填/可选})
...

### 业务逻辑测试点分析

#### 场景1：{业务场景名称}
**前置条件**：{条件描述}

| 操作步骤 | 输入数据 | 预期结果 | 优先级 | 测试目的 |
|----------|----------|----------|--------|----------|
| 步骤1 | {data1} | {result1} | P0 | {purpose1} |
| 步骤2 | {data2} | {result2} | P1 | {purpose2} |

**业务规则验证**：{规则描述}
**数据一致性检查**：{检查点}

#### 场景2：{业务场景名称}
...

### 响应验证测试点分析

#### 成功响应（2xx）
**状态码**：201 Created

**响应体验证**：
| 字段 | 类型 | 验证内容 | 优先级 |
|------|------|----------|--------|
| code | Integer | 等于200 | P0 |
| message | String | 包含"成功" | P0 |
| data | Object | 不为null | P0 |
| data.id | Long | 大于0 | P0 |
| data.createTime | DateTime | 不为null，格式正确 | P1 |

**数据完整性验证**：
- 数据库中记录已创建
- 时间戳字段自动填充
- 关联数据正确建立

#### 错误响应（4xx）
**状态码**：400 Bad Request

| 错误场景 | 响应体验证 | 优先级 |
|----------|------------|--------|
| 参数缺失 | code=400, message包含"必填" | P0 |
| 参数格式错误 | code=400, message包含"格式" | P0 |
| 业务规则违反 | code=409, message包含"已存在" | P0 |

#### 异常响应（5xx）
**状态码**：500 Internal Server Error

| 异常场景 | 响应体验证 | 日志验证 | 优先级 |
|----------|------------|----------|--------|
| 数据库异常 | code=500, message不包含敏感信息 | 记录错误堆栈 | P0 |
| 外部服务异常 | code=503, 触发熔断 | 记录熔断日志 | P1 |

### 安全测试点分析

#### 认证安全
| 测试场景 | 测试操作 | 预期结果 | 风险等级 |
|----------|----------|----------|----------|
| 未认证访问 | 不携带Token调用接口 | 返回401 Unauthorized | 高 |
| Token过期 | 使用过期Token | 返回401, message提示Token过期 | 高 |
| Token篡改 | 修改Token签名 | 返回401, message提示Token无效 | 高 |
| Token刷新 | 使用RefreshToken获取新Token | 返回新Token, 旧Token失效 | 中 |

#### 授权安全
| 测试场景 | 测试操作 | 预期结果 | 风险等级 |
|----------|----------|----------|----------|
| 越权访问 | 用户A访问用户B的数据 | 返回403 Forbidden | 高 |
| 垂直越权 | 普通用户访问管理员接口 | 返回403 Forbidden | 高 |
| 权限变更 | 权限变更后访问接口 | 按新权限控制 | 中 |

#### 数据安全
| 测试场景 | 测试操作 | 预期结果 | 风险等级 |
|----------|----------|----------|----------|
| SQL注入 | 输入SQL特殊字符 | 返回400, 不被注入 | 高 |
| XSS攻击 | 输入<script>标签 | 返回400, 内容被转义 | 高 |
| 敏感数据泄露 | 检查响应字段 | 密码、密钥不返回 | 高 |
| 日志脱敏 | 检查日志文件 | 敏感信息被脱敏 | 中 |

### 性能测试点分析

#### 响应时间要求
- **P0优先级接口**：< 200ms (95分位)
- **P1优先级接口**：< 500ms (95分位)
- **P2优先级接口**：< 1000ms (95分位)
- **P3优先级接口**：< 2000ms (95分位)

#### 压力测试场景
| 场景 | 并发数 | 持续时间 | 预期结果 | 关注点 |
|------|--------|----------|----------|--------|
| 基准测试 | 1 | 10分钟 | 响应稳定 | 基准响应时间 |
| 负载测试 | 10 | 30分钟 | 成功率>99.9% | 系统负载 |
| 压力测试 | 50 | 15分钟 | 成功率>99% | 系统瓶颈 |
| 峰值测试 | 100 | 5分钟 | 不崩溃 | 最大承载 |

#### 性能监控指标
- **响应时间**：平均、P95、P99、最大值
- **吞吐量**：TPS、QPS
- **错误率**：4xx、5xx比例
- **资源使用率**：CPU、内存、磁盘IO、网络IO
- **数据库指标**：连接数、慢查询、锁等待

### 兼容性测试点分析

#### 客户端兼容性
| 客户端类型 | 版本范围 | 测试重点 | 优先级 |
|------------|----------|----------|--------|
| Web浏览器 | Chrome, Firefox, Safari, Edge | 最新+前2个版本 | P1 |
| 移动端 | iOS, Android | 主流版本 | P2 |
| 桌面应用 | Windows, macOS, Linux | 主流版本 | P2 |

#### 数据格式兼容性
| 格式类型 | 测试内容 | 预期结果 | 优先级 |
|----------|----------|----------|--------|
| JSON | 标准JSON、嵌套对象、数组 | 正确解析 | P0 |
| XML | 支持情况 | 正确解析或返回415 | P2 |
| Form | application/x-www-form-urlencoded | 正确解析 | P1 |
| Multipart | multipart/form-data | 正确解析 | P1 |

### 测试数据设计

#### 正向测试数据
```json
{
  "username": "testuser",
  "password": "Test123456",
  "email": "test@example.com",
  "phone": "13800138000"
}

边界测试数据

json

{
  "username": "a",  // 最小长度
  "username": "a" * 20,  // 最大长度
  "username": "a" * 21  // 超过最大长度
}

异常测试数据

json

{
  "username": null,  // null值
  "username": "",  // 空字符串
  "username": "<script>alert(1)</script>",  // XSS
  "username": "admin'--",  // SQL注入
  "username": "../../etc/passwd"  // 路径遍历
}

测试执行建议#

执行优先级

1. P0测试点（核心功能）：100%执行，必须全部通过
2. P1测试点（重要功能）：100%执行，通过率>95%
3. P2测试点（一般功能）：80%执行，通过率>90%
4. P3测试点（次要功能）：50%执行，通过率>80%

执行阶段

• 冒烟测试：所有P0测试点，30分钟
• 功能测试：P0+P1测试点，2天
• 深度测试：P0+P1+P2测试点，3天
• 回归测试：全量测试点，1天

执行环境

• 开发环境：功能验证、快速反馈
• 测试环境：完整测试、集成测试
• 预生产环境：性能测试、安全测试
• 生产环境：冒烟测试、监控验证

风险分析#

高风险

• Token认证机制
• 权限控制体系
• 敏感数据处理
• 支付/交易接口

中风险

• 业务数据完整性
• 第三方服务集成
• 文件上传下载
• 批量操作

低风险

• 查询统计接口
• 只读数据接口
• 静态资源配置

总结#

测试点统计

• 参数校验测试点：X个
• 业务逻辑测试点：X个
• 响应验证测试点：X个
• 安全测试点：X个
• 性能测试点：X个
• 总计：X个测试点

测试覆盖

• 功能覆盖：100%
• 参数覆盖：100%
• 业务规则覆盖：100%
• 安全场景覆盖：100%
• 性能指标覆盖：80%

建议

1. 优先执行P0和P1测试点
2. 重点关注安全测试点
3. 在生产环境执行冒烟测试
4. 建立自动化测试回归套件
5. 定期评审测试点有效性

---

text

### 多接口测试分析格式

```markdown
# {系统名称} API测试分析报告

## 文档信息
- **生成日期**：{date}
- **接口总数**：{count}
- **测试点总数**：{total_points}
- **生成工具**：api-test-create v{version}

## 接口清单

| 序号 | 接口名称 | 路径 | 方法 | 优先级 | 测试点数 |
|------|----------|------|------|--------|----------|
| 1 | 用户注册 | /api/users | POST | P0 | 32 |
| 2 | 用户登录 | /api/auth/login | POST | P0 | 28 |
| ... | ... | ... | ... | ... | ... |

## 模块划分

### 1. 认证管理模块
**接口数量**：6个
**风险等级**：🔴 高
**测试重点**：Token认证、密码安全、输入验证
**测试点数**：150+

### 2. 产品管理模块
**接口数量**：6个
**风险等级**：🟡 中
**测试重点**：CRUD操作、数据一致性、分页逻辑
**测试点数**：120+

## 测试策略

### 测试优先级
- **P0（Critical）**：核心功能，必须测试通过
- **P1（High）**：重要功能，影响用户体验
- **P2（Medium）**：一般功能，优化体验
- **P3（Low）**：次要功能，可后期补充

### 测试类型
1. **功能测试**：验证业务逻辑正确性
2. **参数测试**：验证输入验证机制
3. **安全测试**：验证安全防护能力
4. **性能测试**：验证系统性能指标
5. **兼容性测试**：验证多环境兼容性

## 详细测试分析

### 1.1 用户注册接口

#### 基本信息
- **端点**：POST /api/users
- **描述**：创建新用户账号
- **认证**：否
- **模块**：认证管理

#### 参数校验测试点分析
...

#### 业务逻辑测试点分析
...

（后续内容同单接口格式）

## 测试数据设计

### 正向数据
```json
{
  "username": "valid_user",
  "password": "Valid123",
  "email": "test@example.com"
}

边界数据#

json

{
  "username": "a",          // 最小长度
  "username": "a" * 20,     // 最大长度
  "username": "a" * 21      // 超过最大长度
}

异常数据#

json

{
  "username": null,         // null值
  "username": "",           // 空字符串
  "username": "<script>",   // XSS
  "username": "admin'--"    // SQL注入
}

测试执行建议#

第一阶段：冒烟测试（2小时）#

执行所有P0测试点，验证核心功能

第二阶段：功能测试（2天）#

执行P0+P1测试点，覆盖主要业务场景

第三阶段：深度测试（3天）#

执行P0+P1+P2测试点，包括性能和安全

第四阶段：回归测试（1天）#

全量测试点回归，确保修改不影响已有功能

测试环境要求#

硬件要求#

• CPU：4核以上
• 内存：8GB以上
• 硬盘：50GB可用空间

软件要求#

• JDK 11+
• MySQL 8.0+
• Redis 6.0+
• Git 2.0+

风险分析#

高风险接口#

1. 认证相关接口（登录、注册、Token刷新）
2. 支付/交易接口
3. 权限管理接口

中风险接口#

1. 核心业务数据操作
2. 第三方服务集成
3. 文件上传下载

低风险接口#

1. 查询统计接口
2. 只读数据接口
3. 静态资源配置

总结#

测试点统计#

• 参数校验：XXX个
• 业务逻辑：XXX个
• 响应验证：XXX个
• 安全测试：XXX个
• 性能测试：XXX个
• 总计：XXXX个测试点

建议#

1. 建立测试用例管理系统
2. 实施自动化测试回归
3. 定期进行安全扫描
4. 监控生产环境性能指标
5. 持续优化测试策略

---

文档生成日期：{date} 生成工具：api-test-create v{version} 下次评审：建议每月评审一次

text

## 参考资源

| 文档 | 用途 |
|------|------|
| `references/test-case-design.md` | 详细的测试用例设计方法和代码示例 |
| `references/common-pitfalls.md` | 完整的140点API测试陷阱清单 |
| `examples/openapi-example.yaml` | OpenAPI格式示例 |
| `examples/simple-example.md` | 简化定义格式示例 |