api-testing

分类: 开发与编程 | 上传者: jnMetaCode | 下载: 0 | 版本: v1.0（最新）
API 测试方法论 — 系统化的接口测试流程，覆盖功能、契约、安全和性能
更新日志: Source: GitHub https://github.com/jnMetaCode/superpowers-zh
目录结构

当前层级: skills/api-testing/
📄 SKILL.md 9.2 KB
SKILL.md

---
name: api-testing
description: API 测试方法论 — 系统化的接口测试流程，覆盖功能、契约、安全和性能
---

# API 测试

## 概述

API 是系统的脊梁。前端看到的 Bug，有一半是后端接口的问题。系统化的 API 测试在问题到达用户之前，在接口层面就把它拦住。

**核心原则：** 文档里写的和实际返回的必须一致，没有商量余地。

## 何时使用

- 新接口开发完成，需要验证正确性
- 接口变更后的回归测试
- 前后端联调前的接口预检
- CI/CD 流水线中的自动化测试
- 安全审计和性能基线建立

## API 测试策略

### 分层测试模型

```
┌─────────────────────────────┐
│     E2E 测试（少量）         │  完整业务流程
├─────────────────────────────┤
│     集成测试（适量）         │  多接口协作、数据流
├─────────────────────────────┤
│     契约测试（关键）         │  Schema 一致性、兼容性
├─────────────────────────────┤
│     单接口测试（大量）       │  功能、边界、异常
└─────────────────────────────┘
```

### 功能测试

每个接口至少覆盖三类场景：

- **正向测试**：合法输入 -> 预期输出，覆盖所有参数组合
- **逆向测试**：非法输入、缺失字段、类型错误 -> 合理错误响应
- **边界测试**：极值、空值、超长字符串、特殊字符

原则：每个接口至少 3 个正向用例 + 5 个逆向用例。

### 契约测试

验证接口的"承诺"是否兑现：响应 Schema 与文档一致、必填字段不缺失不漂移、新版本向后兼容、错误码规范统一。

### 集成测试

验证多接口协作的数据一致性：创建 -> 查询 -> 更新 -> 删除的完整生命周期，接口间数据传递正确性，事务原子性。

## 测试用例设计方法

### 等价类划分

```
输入：年龄字段（要求 1-150 的整数）
有效等价类：25（正常值）
无效等价类：0（下界外）、151（上界外）、-1（负数）、"abc"（非数字）、null、3.14（浮点）
```

### 边界值分析

Bug 最爱藏在边界。范围 1-150 测 `0, 1, 2, 149, 150, 151`。字符串长度 1-255 测 `"", "a", "a"*255, "a"*256`。分页 per_page 1-100 测 `0, 1, 100, 101`。

### 错误猜测

基于经验的高频问题：空数组 vs null vs 缺失字段、Unicode/emoji/SQL 注入字符串、时区边界、并发创建相同唯一键、超大 payload。

## RESTful API 测试规范

### HTTP 方法语义验证

```
GET    /resources      -> 200 + 列表（空列表返回 [] 不是 404）
GET    /resources/:id  -> 200 + 单条（不存在返回 404）
POST   /resources      -> 201 + 新资源（含 Location 头）
PUT    /resources/:id  -> 200 + 完整更新后的资源
PATCH  /resources/:id  -> 200 + 部分更新后的资源
DELETE /resources/:id  -> 204 + 空 body（幂等，重复删不报错）
```

### 状态码速查

```
200 OK / 201 Created / 204 No Content — 成功
400 Bad Request — 格式错误   | 401 Unauthorized — 未认证
403 Forbidden — 无权限       | 404 Not Found — 资源不存在
409 Conflict — 重复创建      | 422 Unprocessable — 业务校验失败
429 Too Many Requests — 限流 | 500 Internal — 不该出现
```

## 请求/响应验证

### 请求验证要素

1. **Content-Type** 正确（application/json、multipart/form-data）
2. **必填参数** 缺失时返回明确错误
3. **参数类型** 错误时不崩溃（字符串传到整数字段）
4. **参数范围** 超出时返回 422 而不是 500
5. **额外字段** 被忽略或拒绝（取决于策略）

### 响应验证函数

```python
def validate_response(resp, expected_status, schema=None):
    assert resp.status_code == expected_status
    assert "application/json" in resp.headers.get("Content-Type", "")
    assert resp.elapsed.total_seconds() < 2.0, "响应超时"
    if schema:
        from jsonschema import validate
        validate(resp.json(), schema)
    # 不泄露内部信息
    assert "stack trace" not in resp.text.lower()
```

## 认证和授权测试

### 认证矩阵

```
不带 Authorization 头 / token 格式错误 / 过期 / 签名篡改 -> 401
有效 token -> 正常响应
```

### 授权矩阵

```
普通用户访问自己的数据 -> 200
普通用户访问他人私有数据 -> 403（水平越权 IDOR）
普通用户访问管理端接口 -> 403（垂直越权）
已禁用账户访问任何接口 -> 401 或 403
```

### 安全测试示例

```python
class TestSecurity:
    def test_idor(self):
        """水平越权：用户 A 不能操作用户 B 的资源"""
        resp = requests.get(f"{BASE_URL}/users/{OTHER_ID}/orders", headers=user_a_headers)
        assert resp.status_code == 403

    def test_privilege_escalation(self):
        """垂直越权：普通用户不能调用管理接口"""
        resp = requests.delete(f"{BASE_URL}/admin/users/{uid}", headers=normal_headers)
        assert resp.status_code == 403

    def test_sql_injection(self):
        resp = requests.get(f"{BASE_URL}/users?name='; DROP TABLE users;--", headers=self.headers)
        assert resp.status_code in (200, 400, 422)  # 绝不能是 500
```

## 数据驱动测试

```python
@pytest.mark.parametrize("email,expected_status", [
    ("valid@example.com", 201),       # 正常
    ("user+tag@example.com", 201),    # 带 + 号
    ("", 422),                         # 空
    ("not-an-email", 422),            # 格式错误
    ("a" * 255 + "@test.com", 422),   # 超长
    (None, 422),                       # null
])
def test_email_validation(email, expected_status):
    resp = requests.post(f"{BASE_URL}/users", json={"name": "test", "email": email}, headers=AUTH)
    assert resp.status_code == expected_status
```

**数据管理原则**：每个用例自行准备和清理数据；敏感数据通过环境变量注入；使用独立测试数据库。

## Mock 和 Stub 策略

```
第三方支付/短信/邮件     -> Mock（不能真扣钱、真发短信）
依赖服务尚未开发完成      -> Stub（按约定返回固定响应）
测试异常/超时场景         -> Mock（模拟 500、超时、断连）
正常的内部接口            -> 不 Mock（用真实服务做集成测试）
```

```python
import responses

@responses.activate
def test_payment_callback():
    responses.add(responses.POST, "https://pay.example.com/charge",
                  json={"status": "success", "tx_id": "tx_123"}, status=200)
    result = process_order(order_id="order_001")
    assert result.payment_status == "paid"
    assert len(responses.calls) == 1
```

## 契约测试（Pact / OpenAPI Schema）

### OpenAPI Schema 验证

```python
def test_user_api_matches_contract():
    spec = yaml.safe_load(open("openapi.yaml"))
    schema = spec["paths"]["/users/{id}"]["get"]["responses"]["200"]["content"]["application/json"]["schema"]
    resp = requests.get(f"{BASE_URL}/users/1", headers=AUTH)
    validate(resp.json(), schema)
```

### 向后兼容性规则

- 可以新增字段，不可以删除已有字段
- 可以放宽校验（必填变选填），不可以收紧
- 可以新增 enum 值，不可以删除
- URL 变更必须保留旧路径转发

### Pact 消费者驱动

前端定义期望 -> 生成 Pact 文件 -> 后端验证。接口变更时契约测试先挂，比线上挂好得多。

## 自动化测试框架选择

```
pytest + requests  | Python  | 通用 REST API，简单灵活
Jest + supertest   | JS/TS   | Node.js 项目，前后端统一
REST Assured       | Java    | Spring 项目，链式 BDD 风格
k6                 | JS      | 性能 + 功能混合测试
Hurl               | DSL     | 纯文本定义，CI 友好
```

### 推荐项目结构

```
tests/api/
  conftest.py          # 公共 fixture（认证、基础 URL、清理）
  schemas/             # JSON Schema 定义
  test_users.py        # 按资源组织测试文件
  test_auth.py         # 认证授权专项
  test_security.py     # 安全专项
  helpers/factories.py # 测试数据工厂
```

## 检查清单

### 每个接口必测项

- [ ] 正向请求返回正确状态码和数据
- [ ] 必填字段缺失返回 422 + 字段级错误信息
- [ ] 类型错误不返回 500
- [ ] 不带 token 返回 401
- [ ] 用他人 token 访问受限资源返回 403
- [ ] 响应 body 符合 JSON Schema
- [ ] 响应时间在 SLA 范围内
- [ ] 错误响应不泄露内部信息（堆栈、SQL、文件路径）

### 写操作附加项

- [ ] 幂等性：相同请求发两次行为正确
- [ ] 并发：同时修改同一资源不产生脏数据
- [ ] 事务：部分失败时正确回滚
- [ ] 创建后立即查询能查到（读写一致性）

### 列表接口附加项

- [ ] 空列表返回 `[]` 不是 404 或 null
- [ ] 分页 total 准确、翻页无遗漏无重复
- [ ] 排序和筛选参数生效
- [ ] 超大结果集有分页强制

### 上线前终检

- [ ] 所有接口自动化测试通过
- [ ] 契约测试通过（文档 = 实现）
- [ ] 安全测试通过（认证、授权、注入）
- [ ] 性能基线已建立，无退化
登录后下载/点赞/收藏 ❤ 8 | ★ 0
api-testing

目录结构

SKILL.md

举报内容

提示
