---
name: api-test-create
description: 当用户需要根据接口规格生成API测试分析文档时使用此技能。接受OpenAPI/Swagger文档、简化接口定义或自然语言描述，基于140个常见API测试陷阱输出全面的测试分析文档，涵盖参数校验、业务逻辑、响应验证和安全测试分析点。
---

# 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、Infinity |
| enum | 所有有效值、无效值、大小写敏感、null、空字符串、数字枚举 |
| boolean | true/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. 定期评审测试点有效性

---
```

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

```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}
**下次评审**：建议每月评审一次
```

## 参考资源

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