api-test

完整扫描工程中各客户端（web 管理后台、小程序、Android、iOS）调用的后端 API：静态收集生成 URL 清单 → 逐个请求验证 HTTP 200 → 非 200 定位修复 → 响应业务合理性检查与修复 → 输出测试结果。

定位：联调阶段的接口自测。验证"接口通不通、返回对不对"，不替代完整业务功能测试。

触发条件：用户要求检查/验证/修复工程各端调用的后端 API，或要求生成 API 清单并逐个验证。

执行方式：HTTP 请求必须串行推进。 默认 --bucket=2，按清单顺序每 2 条连续请求编成一桶同时发出；--bucket=1 为严格逐条发请求、逐条记结果。并发只允许发生在桶内：--bucket=N（N 为 1-4 的整数，上限 4）表示把连续 N 条请求编成一个桶发出；桶与桶之间严格串行——上一桶全部返回、逐条结果落台账后，才可起下一桶。写操作与"修复后复验"一律不进桶（见第三节）。

零、参数处理

如果用户传入 -h 或 --help，不执行任何操作，直接把下面的帮助信息原样输出在本次回复正文里后结束（斜杠命令把 SKILL.md 注入我的上下文不等于已展示给用户，正文里只回一句"已输出"就是没输出）。-h 与其它参数或说明文字同时出现时，一律只出帮助、忽略其余参数：本轮不猜附加要求，需要同时执行就把 -h 去掉分两次调用：

用法: /api-test [选项]

选项（通过命令行传入的参数直接使用，不再交互询问）
  --base-url=URL      后端 API 基础地址（如 http://localhost:8080/api/xxx）。
                      不传则自动探测（各端 env / proxy 配置 / nginx vhost / specs）
  --client=<端>       只扫描指定端（web / miniapp / android / ios，可多次传入）。
                      不传则扫描工程中实际存在的所有端
  --allow-write       允许直接探测 POST/PUT/DELETE 等写操作 API（默认逐个询问）
  --bucket=N          请求桶并发大小（可选，整数 1-4，默认 2 = 每 2 条连续请求一桶
                      并发；1 = 严格串行逐条）。N>1 时把清单连续 N 条编为一桶同时发出，
                      桶与桶之间仍串行：上一桶全部返回并记入台账后才起下一桶。
                      写操作（POST/PUT/DELETE）与修复后的复验一律不进桶。
                      N>4 直接报错终止（避免后端承压与响应时长失真）
  --no-fix            只检查并输出报告，不修改任何代码
  -h, --help          显示本帮助（出现即忽略其它参数，只出帮助）

工作流程
  1. 前置检查：识别工程中存在的客户端目录（web 管理后台 / 小程序 / Android / iOS），
     探测后端 base url、确认后端服务在线（健康检查）、确认鉴权 token 获取方式
  2. 全端扫描：静态收集各端代码调用的后端 API（方法 + 路径 + 参数），
     整理成 URL 清单写入 test/api/url-list.md
  3. 逐个验证：curl 实际请求，首先判断 HTTP 响应码是否 200，同时记录响应时长；
     按串行推进（默认 --bucket=2 两条一桶，--bucket=1 严格逐条，上限 4，桶间串行）；
     需登录接口做鉴权正反验证（带有效 token 应 200，无/无效 token 应 401/403）
  4. 诊断修复：非 200 请求按状态码定位前端/后端原因，最小化修复并复验
  5. 响应时长分析：按 ≤100ms / 100-200ms / 200-500ms / 500ms-1s / ≥1s 五档分级；
     >200ms 重点关注，>500ms 必须分析原因
  6. 业务合理性检查：对 200 响应检查返回内容，业务层面明显不合理的
     （错误码非 0、数据缺失/矛盾、与页面预期不符等）分析并修复
  7. 结果输出：汇总写入 test/api/test-result.md

产物
  test/api/url-list.md     API URL 清单（端 × 页面/模块 × 方法 × 路径 × 参数）
  test/api/test-result.md  验证与修复结果（首次状态 × 最终状态 × 处置 × 修改文件）

示例
  /api-test                                    扫描全部端，自动探测后端地址，检查并修复
  /api-test --client=web                       只扫描 web 管理后台
  /api-test --base-url=http://localhost:8080/api/mall --allow-write
  /api-test --bucket=4                         清单很长时按 4 条一桶并发提速（桶间仍串行）
  /api-test --bucket=1                         严格逐条请求（要看准响应时长分级时用）
  /api-test --no-fix                           只出报告，不改代码
  /api-test -h                                 显示本帮助

一、前置检查

1.1 识别各端代码目录

扫描当前工作目录，确定存在哪些客户端（存在才扫描，一个都没有则报告并终止）：

目录形态无法确定时，向用户确认各端代码位置。

传入 --client=<端> 时只扫描点名的端（可多次传入，取并集），未点名的端整端跳过：URL 清单、逐个验证与报告的口径同步收窄到已扫端，不点名的端不进清单。点名的端在工程里不存在时直接报错终止（输出 错误：工程中不存在 <端> 代码目录），不静默回退成全端扫描。

1.2 探测后端 base url

按以下优先级确定后端 API 基础地址，命中即停：

1. 命令行 --base-url。
2. 各端环境/配置文件：web 的 .env*（NEXT_PUBLIC_* / VITE_*）、小程序的 env 配置或请求封装常量、Android 的 BuildConfig / local.properties / Retrofit baseUrl、iOS 的 Info.plist / 请求封装常量。
3. 代理配置：next.config.* rewrites、vite.config.* server.proxy。
4. 各端请求封装文件（axios instance / fetch wrapper / Retrofit / URLSession 封装）中硬编码的 baseURL。
5. deploy-conf/nginx/*.dev.conf（站点配置）或 specs/deployment.md 中登记的后端地址。

全部无法确定时，询问用户提供 base url。多个后端服务（不同 context-path）时，按服务分别记录。

1.3 确认后端服务在线

1. 确定后端服务名（src/backend/<name>/，唯一目录即默认）。
2. 健康检查：curl -s -o /dev/null -w "%{http_code}" {BASE_URL}/health，或按 specs/deployment.md 约定的健康检查端点（如 /api/<name>/health）。
3. 返回 200 → 继续。
4. 不在线 → 询问用户：由用户启动，还是尝试本地启动（src/backend/<name> 下 ./mvnw spring-boot:run / mvn spring-boot:run，后台运行并等待健康检查通过）。用户拒绝则终止。

1.4 确认鉴权方式

检查各端请求封装是否自动附加 Authorization 头：

• 需要登录 → 找到登录 API 与凭据来源：
  • 优先测试环境账号配置（src/backend/<服务名>/.env.test、specs 文档、前端 mock）。
  • 找不到 → 请用户提供测试账号或一个有效 token。
  • 拿到后先调登录接口换取 token，后续所有探测请求带上 Authorization 头。
• 无需登录 → 直接继续。

凭据只用于请求，不写入任何文件，不在输出中明文展示。

二、全端扫描与 URL 清单

2.1 按端收集 API 调用

对每个存在的端，静态收集所有后端调用：

只追后端调用，不追 UI 组件与纯本地逻辑。每条记录：所属端、页面/模块、HTTP 方法、完整路径（含 base url 前缀）、参数来源（path / query / body）。

2.2 写入 URL 清单文件

将收集结果写入 test/api/url-list.md（目录不存在则创建）：

# API URL 清单

后端地址：<base url>（来源：自动探测/用户提供）
生成时间：<YYYY-MM-DD>
扫描范围：web 管理后台 / 小程序 / Android / iOS（按实际存在的端列出）

| # | 端 | 页面/模块 | 方法 | API 路径 | 参数 | 类型 |
|---|-----|----------|------|----------|------|------|
| 1 | web | /home | GET | /api/mall/banners | - | 读 |
| 2 | web | /order/create | POST | /api/mall/orders | {productId,...} | 写 |
| 3 | miniapp | pages/index | GET | /api/mall/banners | - | 读 |
| 4 | android | OrderRepository | GET | /api/mall/orders | page,size | 读 |

2.3 确定测试参数

实际探测需要具体参数值，按以下顺序取值：

1. 代码中现成的示例值 / mock 数据 / 默认参数。
2. 从接口语义推断的最小可用值（如 page=1&size=10、列表首条记录的 id）。
3. 依赖其他接口返回值的（如详情接口依赖列表接口返回的 id）→ 先探测上游接口，从响应体中提取真实值。
4. 仍无法确定 → 标记 待参数，全部收集完后一次性向用户询问。

2.4 确认后开始验证

向用户展示清单摘要（各端条数、写操作条数）并确认：

• 读操作（GET）：默认直接探测。
• 写操作（POST/PUT/DELETE）：默认逐条询问用户是否执行；传入 --allow-write 时直接探测。写操作提示用户将作用于当前后端环境的数据。

三、逐个验证（HTTP 200 检查）

对清单中每条 API 执行：

curl -s -w "\n[HTTP_STATUS:%{http_code}] [TIME:%{time_total}s]" -X {METHOD} "{URL}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{BODY}'

• 首先判断 HTTP 响应码是否为 200；非 200 时保留响应体（截断至 50 行以内）供诊断。
• 同时记录 [TIME] 响应时长（毫秒，取 time_total），供第五节分级分析；每条只测一次时长，若结果处于 >200ms 临界区间可复测一次取稳定值。
• 逐条输出即时结果：[#3] GET /api/mall/orders → 200 OK (87ms) 或 [#5] POST /api/mall/orders → 500 ✗ (12ms)。
• 多端调用同一接口时只需实际探测一次，结果共享到各端记录。

执行方式（串行推进 + 桶并发上限 4，必做）

1. 桶参数校验：--bucket 缺省为 2（每 2 条连续请求一桶并发）；需要严格串行逐条时显式传 --bucket=1。取值必须是 1-4 的整数；非法值（0、负数、非数字）或 >4 一律直接报错终止（输出 错误：--bucket 必须为 1-4 的整数，桶大小上限 4），不得静默钳制（用户要 8 并发却被跑成 4 会让其对节奏与后端承压的判断失真）。
2. 切桶：按 test/api/url-list.md 的编号顺序，每 B 条连续记录切成一桶（B = --bucket，末桶不足按实际条数）。同一条记录的正向 + 鉴权反向两次请求属该条内部动作，不额外占桶位。
3. 发桶：一桶内的请求在同一条 Bash 命令里并发发出并等齐（如 curl ... & curl ... & wait，或 xargs -P {B}），整桶返回后按编号顺序逐行输出即时结果、记入台账，才能起下一桶。禁止一次抛出整张清单，禁止上一桶结果未落台账就发下一桶。
4. 不进桶的三类（无论 B 取多少，一律单条串行）：
   • 写操作（POST/PUT/DELETE）：顺序敏感且并发写互相污染数据，仍按 2.4 逐条经用户确认；
   • 修复后的复验（第四节）及任何重编译/重启后端的动作：重启会打断同桶在途请求，把正常接口误判成 502/超时；
   • 有前后依赖的成对请求（2.3 先从上游接口取 id 再打下游、登录换 token 与其后依赖该 token 的请求）：被依赖方与依赖方不得同桶，按依赖顺序拆到相邻桶串行执行。
5. 时长口径（关键）：桶内并发共享后端连接池与网络带宽，耗时会互相放大（默认 B=2 同样存在放大），因此桶内测得的时长只能作初筛。凡落入 >200ms 档（尤其 >500ms 必须分析原因）的记录，以及超时 / [HTTP_STATUS:000] 的记录，必须在 --bucket=1 单条串行模式下复测取稳定值，才可按第五节定级或进第四节诊断；报告中注明该时长为串行复测值。
6. 选型：要看准响应时长分级 → 显式 --bucket=1 严格逐条；常规联调（连通性 + 时长初筛）→ 默认 --bucket=2；清单上百条、本轮只判状态码 → --bucket=4 提速，再对 >200ms 的少数条目串行复测。

鉴权正反验证（公参 Authorization: Bearer <token>）

对需要登录的接口（请求封装自动附加 Authorization 头的），每条做正反两面验证：

1. 正向：带有效 Authorization: Bearer <token> 请求 → 预期 200。
2. 反向：去掉 Authorization 头（再补测一次带无效/过期 token，如 Bearer invalid）→ 预期 401/403。
3. 反向结果判定：
   • 返回 401/403 → 鉴权正常。
   • 返回 200 或业务数据 → 鉴权缺陷（未授权可访问），标记 鉴权漏洞，按第四节修复规则处理（后端安全配置/拦截器白名单过宽），修复后正反两面都要复验。
4. 公开接口（登录、健康检查、注册等白名单路径）只做正向验证，不做反向。
5. 即时结果追加鉴权标记：[#3] GET /api/mall/orders → 200 OK / 无 token → 401 ✓ 或 ... / 无 token → 200 ✗ 鉴权漏洞。

四、非 200 诊断与修复

传入 --no-fix 时跳过本节与第六节，直接汇总报告。

对每条非 200 请求，按下表定位，遵循先客户端后后端的顺序排查：

修复规则

1. 最小化修复：只改导致该请求失败的位置，不顺手重构。
2. 判定为客户端问题 → 修改对应端代码后重新执行该请求验证。
3. 判定为后端问题 → 修改后端代码后重新编译并重启服务（等待健康检查通过），再复验该请求。
4. 复验仍失败 → 继续诊断，直至定位根因；确认无法修复（如依赖外部系统、缺测试数据）时记录具体原因，标记 未解决，继续处理下一条。
5. 修复一条后，若改动影响其他已通过接口（如改了公共路径前缀），对受影响的接口重新复验。

五、响应时长分析

探测阶段记录的 [TIME] 全部汇总，按五档分级并输出各档 API 清单：

1. 分级清单：每档列出 端 / 方法 / API 路径 / 时长（ms），写入结果报告。
2. >500ms 原因分析（必做），按"先网络后后端"排查：
   • 用 curl -w 的时间分解（time_namelookup / time_connect / time_starttransfer）区分 DNS/连接耗时与后端处理耗时。
   • 后端处理慢 → 查后端日志与实现：慢 SQL / N+1 查询 / 缺索引、未分页的全量查询、响应体过大、同步调用第三方服务。
   • 客户端放大 → 检查是否在循环里串行调用该接口（应批量/并行）。
3. 处置：原因明确且修复风险低的，按第四节修复规则最小化修复并复测时长；--no-fix 时只输出原因与建议。测试数据量导致的慢（如百万行表无索引）记录为建议项。
4. 时长受测试环境影响，报告中注明测试环境（本地/服务器）；首条请求含预热开销，临界值以复测为准。桶并发（--bucket>1）时同桶请求耗时会互相放大，定级前必须按第三节第 5 条以 --bucket=1 串行复测。

六、业务合理性检查

对 HTTP 200 的响应，检查返回内容在业务层面是否明显不合理：

1. 协议层：响应体中的业务错误码（如 code != 0、success=false）与 200 状态矛盾。
2. 数据完整性：页面/模块预期必有数据的接口返回空（如首页 banner、登录用户信息为空）；字段缺失或为 null 但客户端代码直接使用会崩溃。
3. 数据一致性：列表 total 与条目数矛盾、金额/数量为负、状态值不在合法枚举内、关联数据对不上（如订单引用不存在的商品）。
4. 与客户端预期不符：字段名/结构与客户端 DTO、解析代码不一致。

判定为"明显不合理"才修复；属于测试数据问题（库里本来就没数据）的不算缺陷——记录为 缺测试数据，必要时经用户同意后造最小测试数据后复验。

修复同样遵循最小化原则：后端逻辑错误改后端，客户端解析错误改客户端；修复后复验该接口。

七、结果输出

将验证与修复结果写入 test/api/test-result.md：

# API 测试结果

后端地址：<base url>
测试时间：<YYYY-MM-DD>
扫描范围：<各端>
测试环境：<本地/服务器>
执行方式：<串行逐条 | 桶并发 B=N>（>200ms 条目均已 --bucket=1 串行复测定级）
URL 清单：test/api/url-list.md（共 M 条）

| # | 端 | 页面/模块 | API | 首次状态 | 最终状态 | 时长 | 处置 |
|---|-----|----------|-----|---------|---------|------|------|
| 1 | web | /home | GET /api/mall/banners | 200 | 200 | 87ms | 通过 |
| 2 | web | /order/list | GET /api/mall/orders | 404 | 200 | 320ms | 已修复（前端路径拼写）；重点关注 |
| 3 | miniapp | pages/order | GET /api/mall/orders/{id} | 200 | 200 | 650ms | 已修复（响应缺字段）；慢因：未分页全量查询 |
| 4 | web | /order/create | POST /api/mall/orders | 500 | 500 | - | 未解决（原因） |

结果：通过 X 条 / 修复 Y 条（HTTP 修复 a 条 + 业务修复 b 条）/ 未解决 Z 条 / 跳过（用户未确认写操作） W 条

## 响应时长分布

| 档位 | 数量 | API 清单 |
|---|---|---|
| ≤100ms | n1 | <端 方法 路径 (时长)> ... |
| 100-200ms | n2 | ... |
| 200-500ms（重点关注） | n3 | ... |
| 500ms-1s（重点关注） | n4 | ... |
| ≥1s（重点关注） | n5 | ... |

>500ms 原因分析：
  - <API>：<原因，如 慢 SQL 缺索引 / 未分页 / 第三方同步调用>，处置：<已修复/建议>

修改文件清单：
  - src/web/...（修复内容）
  - src/backend/<name>/...（修复内容）

同时向用户输出上述内容的中文摘要。

八、注意事项

• 工程根目录 v0/ 是只读产品设计文档，禁止修改；src/web/v0/ 是代码目录，可正常修改。
• 探测使用的账号、token 只出现在请求中，不写入文件、不提交版本库、不在报告中明文输出。
• 写操作 API（POST/PUT/DELETE）默认必须经用户确认才执行；提醒用户其作用于当前后端环境数据。
• HTTP 请求串行推进：默认 --bucket=2（每 2 条连续请求一桶并发），--bucket=1 为严格逐条发送；并发只允许发生在桶内，桶大小上限 4（非法值或 N>4 直接报错终止，不钳制），桶与桶之间严格串行——上一桶结果全部落台账后才起下一桶。写操作、修复后的复验与后端重启、有前后依赖的成对请求一律不进桶；桶内时长只作初筛，>200ms 与超时条目必须以 --bucket=1 串行复测后才能定级（详见第三节"执行方式"）。
• 后端改动后的重启遵循工程部署规范（supervisord 管理的生产服务不得随意重启，优先本地/dev 环境验证）。
• CORS 问题只能在 nginx 配置中解决，禁止改后端代码绕过。
• 本 skill 只修改代码文件与 test/api/ 下的两个产物文件，不执行 git commit，由用户决定是否提交。