Skip to Content
管理员后台API 耗时诊断

API 耗时诊断

配图占位：本节用于在后续视觉评审中插入「API 耗时诊断」整体视觉截图（玻璃面板、KPI 条 5 卡、过滤 chip 行、样本表格、慢 / 错误高亮）。

用途

本页面介绍 /admin/api-timing 路由——管理员对全平台 API 响应耗时的诊断入口。设计稿见 .design/dramagon-redesign/pages/admin-api-timing.html。

页面包含 5 段能力：

  • KPI 条：P50 / P95 / P99 / 总请求数 / 唯一路由数 5 卡
  • 过滤筛选：时间窗（1h / 24h / 7d）+ 慢接口 / 5xx 错误 chip + 关键字搜索
  • 样本表格：路由、Method、耗时、状态、命中、用户、时间窗 7 列
  • 行级高亮：critical（5xx 或 >2000ms）/ slow（1000-2000ms）/ normal
  • 跳转统计：右上角按钮直达 /admin/api-timing-stats

使用前准备

  • 仅管理员账号可见；登录态与会话由 AdminGuard 守护。
  • 后端依赖：/api/admin/api-timing/samples（样本列表）与 /api/admin/api-timing/stats（KPI 聚合）
  • 数据源：ApiTimingSample 模型（observer 在 apiHandler 响应结束后 fire-and-forget 采集；instrumentation.ts 每 5s 批量 flush）
  • 路径标准化：observer 会把 zh / en locale 前缀去掉，把数字 / UUID 段落替换为 [id]

操作步骤

API 列表

  1. 进入 /admin/api-timing，默认展示过去 24h 全部样本。
  2. 表格行高亮按耗时与状态码动态着色：
    • critical：状态码 ≥ 500 或耗时 > 2000ms（红）
    • slow：耗时 1000-2000ms（黄）
    • normal：其他（默认）

筛选

  1. 点击顶部 chip 切换时间窗：1h / 24h / 7d。
  2. 点击 慢接口 chip：自动应用 durationMs > 2000 过滤（与其他 chip 互斥）。
  3. 点击 5xx 错误 chip：自动应用 status >= 400 过滤（与其他 chip 互斥）。
  4. 在搜索框输入关键字：同时匹配 route 与 method（大小写不敏感）。
  5. 分页：默认 20 条 / 页，pageSize 上限 200。

KPI

  1. KPI 卡 1-3 展示 P50 / P95 / P99，单位智能切换：< 1000ms 显示整数 ms，≥ 1000ms 显示一位小数 s。
  2. KPI 卡 4 展示总请求数，单位智能切换：≥ 1M 显示 M，其他显示千分位整数。
  3. KPI 卡 5 展示唯一路由数 + 覆盖率提示（routeCoveragePct，分母启发式 = distinct × 1.07）。
  4. P95 / P99 tone：根据 ms 是否 > 1000 / > 2000 在容器 data-p95-tone / data-p99-tone 上输出 warn / error，admin.css 据此染色。
  5. P50 / P95 / P99 的趋势标签按当前语言显示上涨、下降或持平，不会回退为翻译键。

跳到统计

  1. 点击 toolbar 右侧「查看统计」按钮，跳转 /admin/api-timing-stats。
  2. 该页面以 P50/P95/P99 趋势图、Top10 慢路由、5xx 错误聚合为核心，每 60s 自动刷新。

数据契约

  • 响应：/api/admin/api-timing/samples 返回 { items, total, page, pageSize }
  • 样本字段：id / route / method / status / durationMs / userId / isAnonymous / ts
  • 路径已由 observer 归一化为 /api/<segment>/[id]/... 模板，可直接 groupBy 聚合
Last updated on
诊断问题API 耗时统计