antissoft / HongHua-JJ

SKILL.md 4.58 KB

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 示例：

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）：

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

POST（JSON body）：

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：

    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）：

    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）：

    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 实际、数据库校验结果，给出「通过/不通过」结论