---
name: api-interface-testing
description: 按项目规范执行接口测试，包含获取 Token、使用 curl 调用接口及验证要点。在开发或修改接口、需要验证接口行为或用户提及接口测试时使用。
---

# 接口测试

## 何时使用

- 新增或修改了后端 API，需要验证接口行为
- 用户明确要求进行接口测试或提供测试示例
- 提交代码前确认接口符合「必须测试」规范

## 执行方式（必须按此执行）

当用户本地 API 已启动（如 `http://localhost:2011`）时，**必须直接使用 Shell 执行 curl 命令**进行接口测试，而不是只给出 curl 示例让用户自己执行。

1. **登录获取 Token**：用 Shell 执行登录 curl，从返回 JSON 中解析 `data.token`
2. **调用目标接口**：用 Shell 依次执行 curl，请求头带上 `Authorization: {data.token}`
3. **数据库验证**：涉及增删改的接口，**必须**用 MCP MySQL 工具执行 SELECT 查库验证（遵循 `mcp-mysql-and-sql-validation` skill）
4. **输出测试报告**：汇总 HTTP 状态、返回值、数据库校验结果，给出通过/不通过结论

## 测试流程

1. **获取 Token**：先调用登录接口拿到 `data.token`
2. **调用目标接口**：请求头带上 `Authorization: {data.token}`
3. **验证结果**：按下方清单检查返回值与行为
4. **查库验证**：对新增/修改/删除类接口，用 MCP 执行 SQL 验证数据是否正确落库

## 获取 Token

- **地址**：`POST /api/oauth/Login`
- **Content-Type**：`application/x-www-form-urlencoded`
- **参数**：`account=admin`，`password=66762a3ccde2a2cff3060d7a4a0a576b`
- **Base URL**：本地一般为 `http://localhost:2011`，以实际运行环境为准

**curl 示例：**

```bash
curl -X POST "http://localhost:2011/api/oauth/Login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "account=admin&password=66762a3ccde2a2cff3060d7a4a0a576b"
```

**返回说明**：`data.token` 已包含 `"Bearer "` 前缀，请求其他接口时**直接使用**：`Authorization: {data.token}`（无需再拼 Bearer）。

## 调用接口示例

**GET（项目规范：GET 使用 data 传参，不用 params）：**

```bash
curl -X GET "http://localhost:2011/api/xxx/YourAction?key=value" \
  -H "Authorization: <data.token 完整值>"
```

**POST（JSON body）：**

```bash
curl -X POST "http://localhost:2011/api/xxx/YourAction" \
  -H "Authorization: <data.token 完整值>" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'
```

将 `<data.token 完整值>` 替换为登录响应里 `data.token` 的整段字符串（已含 `Bearer `）。

## 验证清单

测试时需覆盖并确认：

- [ ] **功能**：用真实/合理数据调用，返回符合接口约定
- [ ] **正确性**：关键字段类型、取值、分页与业务逻辑一致
- [ ] **边界**：空列表、无数据、参数缺省等处理正确
- [ ] **异常**：非法参数、未登录等返回合理错误码与提示
- [ ] **性能**：响应时间可接受，无超时或明显卡顿

只有测试通过后再提交相关代码。

## 工具

可使用 curl、Postman、Swagger 等；给出示例时优先提供 **curl**，便于在终端直接执行。

## 完整执行示例（Shell + MCP 查库）

以下为 SbRecords StartViewRecord / EndViewRecord 接口的实测流程，**以后接口测试均按此方式执行**：

1. **Shell 执行登录**，获取 token：
   ```bash
   curl -s -X POST "http://localhost:2011/api/oauth/Login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "account=admin&password=66762a3ccde2a2cff3060d7a4a0a576b"
   ```
   从返回 JSON 中提取 `data.token`，后续请求头使用 `Authorization: $TOKEN`

2. **Shell 执行目标接口**（如 StartViewRecord）：
   ```bash
   curl -s -X POST "http://localhost:2011/api/Extend/SbRecords/Actions/StartViewRecord" \
     -H "Authorization: $TOKEN" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "reId=xxx&type=查看设备"
   ```
   记录返回的 `data`（如 recordId）

3. **Shell 执行后续接口**（如 EndViewRecord）：
   ```bash
   curl -s -X POST "http://localhost:2011/api/Extend/SbRecords/Actions/EndViewRecord" \
     -H "Authorization: $TOKEN" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "recordId=xxx"
   ```

4. **MCP 查库验证**：调用 `mcp_HongHua-JJ-my-sql-db_query` 执行 SELECT，校验关键字段（如 F_LeaveTime、F_DurationSeconds）是否正确写入

5. **输出测试报告**：表格汇总各用例的预期 vs 实际、数据库校验结果，给出「通过/不通过」结论