接口回归测试 / API Regression Suite

技能文档

---
name: web-api-regression-suite
display_name: 接口回归测试 / API Regression Suite
description: "Web API 回归与冒烟测试：断言响应里的业务码而非只看 HTTP 状态（某些框架返回 200 + 业务失败码）。Run regression and smoke tests against web APIs with correct assertions: check the business code inside the response body, not just the HTTP status, because some frameworks return 200 with a business failure code. 触发词：接口回归测试、冒烟测试、业务码断言、HTTP 200 不等于成功、API regression。"
summary_zh: Web API 回归与冒烟测试方法论：断言响应里的业务码而非只看 HTTP 状态，含成功判定、用例集与幂等验证。
summary_en: Web API regression and smoke-test methodology that asserts the business code inside the response—not just HTTP status—with a success helper, case set, and idempotency checks.
version: 1.0.0
category: testing
tags: [testing, api, regression, smoke, qa, automation]
---

# web-api-regression-suite

把"Web API 回归测试"的方法论固化为可复用流程。核心认知：**HTTP 200 不等于业务成功**。很多后端框架统一返回 200，把业务结果包在 body 的 `code` 字段里（如 `200 + {code:500}`），只看状态码会得出"假绿"。

可套到任意带登录态的 Web 系统（订单系统、会员中心、内容平台等），与具体业务无关。

## 简介 / Introduction

**中文**：把"Web API 回归测试"方法论固化：核心认知是"HTTP 200 不等于业务成功"。很多框架统一返回 200 把结果包在 body 的 code 字段。提供 okc 成功判定、冒烟用例集、幂等验证与可读报告。

**English**: A regression/smoke-test methodology for web APIs, built on "HTTP 200 ≠ business success" (many frameworks wrap results in a body code field). Provides an okc success helper, a smoke-case set, idempotency checks, and a readable report.

## 何时用

- 发版前回归验证
- 写 API 冒烟测试
- 论证"为什么不能只断言 HTTP 状态"

## 核心原则

1. **断言业务码**：定义 `okc(resp)`，解析 body 业务码（如 `code == 0`）统一判定，不只用 HTTP status。
2. **冒烟用例集**：覆盖核心读 + 写接口，数量可控（约 20 项足够日常回归）。
3. **幂等验证**：同一写操作跑两次，确认不产生重复数据 / 副作用。
4. **先解析结构**：响应可能是 `data.rows` + `data.total` 或裸数组，先识别再取字段。
5. **报告可读**：输出每项 通过 / 失败 + 业务码，失败项一眼定位。

## 分步流程

1. 定义 `okc(resp)`：解析业务码，返回 bool（可配成功码集合）。
2. 列冒烟用例：核心接口 + 关键字段断言。
3. 逐用例调用，断言 `okc` 通过 + 关键字段存在。
4. 幂等用例：写操作跑两次，第二次应被拒或幂等（业务码指示重复）。
5. 输出报告：通过数 / 失败数 / 失败明细。

## 坑（来自真实事故）

- **HTTP 200 即成功**：框架返回 `200 + {code:500}` → 误判通过，真实故障漏网。
- **只断言 status**：不解析业务码 → 假绿。
- **幂等未验**：回归脚本重复跑产生重复数据，污染环境。
- **响应结构假设**：硬取 `records` / `list` → 实际 `data.rows` 取空。

## 骨架脚本

`scripts/regression_runner.py`：参数化回归运行器。`okc` 可配；`run_suite` 支持注入探测函数（便于 mock）；输出报告。改用例 / base_url / token 即可跑，无业务耦合。

## 验收清单

见 `references/acceptance-checklist.md`（7 条，上架 / 改版前必跑）。

## 触发词

接口回归测试、冒烟测试、业务码断言、HTTP 200 不等于成功、API regression。

使用说明

## 解决什么问题

为带登录态的 Web API 提供回归与冒烟测试集：核心是 **断言响应里的业务码而非只看 HTTP 状态**。

## 核心认知

- **HTTP 200 ≠ 业务成功**：RuoYi 系统一返回 200，结果包在 body 的 `code` 字段（如 `200+{code:500}`）；只看状态码会假绿。
- **okc 成功判定**：技能提供 `okc(body)` 工具，解析业务码 0/200 = OK，其他 = FAIL，附原始响应便于排查。
- **写操作幂等验证**：同一用例跑两次不应产生重复数据；技能里带幂等用例模板。
- **分页结构适配**：自动识别 `data.rows+total`（RuoYi 风格）和裸数组两种形态。

## 使用方式

1. 在 `cases/` 写 yaml 用例（method / path / body / expect）。
2. 配 `config.yaml` 的 base_url / token / headers。
3. 跑 `regression_runner.py`，输出通过/失败 + 业务码 + 响应摘要。
4. CI 集成：退出码非零即失败，可直接挂到流水线。

## 适用场景

上线前回归、跨版本兼容测试、API 变更监控；尤其适配 RuoYi-Vue / 同类"业务码包在 200 里"的框架。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。