team/docs/测试-接口.md

接口测试规范

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

---

1. 概述

本文档定义项目所有 API 接口的测试规范。测试按接口分组组织，与 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	分类接口测试用例模板	§3+

---

4. 测试文件组织结构

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

---

版本历史:

• v1.0.0 (2026-04-19): 初始化模板