# 接口测试规范

**文档版本**: 1.0.0
**最后更新**: 2026-04-19

---

## 1. 概述

本文档定义项目所有 API 接口的测试规范。测试按接口分组组织，与 [09-API契约.md](./09-API契约.md) 章节结构一致。

### 1.1 测试目标

| 目标 | 说明 |
|------|------|
| **契约一致性** | 验证所有接口的请求/响应格式与 API 契约完全一致 |
| **状态码正确性** | 验证每个接口在各种场景下返回正确的 HTTP 状态码 |
| **错误码准确性** | 验证错误响应中的 code 和 message 符合错误码规范 |
| **安全性** | 验证认证机制、权限控制和注入防护 |
| **边界条件** | 验证空值、超长输入、特殊字符等边界场景 |
| **性能基准** | 验证接口响应时间满足非功能性需求 |

### 1.2 测试工具

| 工具 | 用途 | 适用范围 |
|------|------|----------|
| **pytest** | 测试框架 | 全部 |
| **httpx** | HTTP 客户端 | 全部 |
| **faker** | 测试数据生成 | 全部 |

### 1.3 HTTP 状态码速查

| 状态码 | 场景 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无响应体） |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 409 | 冲突 |
| 500 | 服务端内部错误 |

---

## 2. 通用响应格式验证

### 2.1 成功响应结构

**验证点**：
- 响应体必须包含 `data` 和 `meta` 两个顶层字段
- `meta` 必须包含 `request_id`

### 2.2 错误响应结构

**验证点**：
- 响应体必须包含 `error` 和 `meta` 两个顶层字段
- `error` 必须包含 `code` 和 `message`

### 2.3 分页响应结构

**验证点**：
- `meta` 必须包含 `total`、`page`、`per_page`
- `data` 为数组类型

---

## 3. 接口测试文档索引

<!-- 按接口分组拆分为独立文件后在此列出索引 -->

| 文件 | 内容 | 章节来源 |
|------|------|----------|
| [测试-接口-分类.md](./测试-接口-分类.md) | 分类接口测试用例模板 | §3+ |

---

## 4. 测试文件组织结构

```
apps/<!-- 模块 -->/
└── tests/
    └── api/
        ├── conftest.py          # API 公共 fixtures
        └── <!-- test_*.py -->   # 接口测试文件
```

---

**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板