@chenguangyao/devflow-kit 0.1.43

package/skills/verify/references/nfr-verification.md

@@ -0,0 +1,292 @@
+# verify / nfr-verification
+
+非功能性需求(性能 / 吞吐 / 可用性 / 资源 / 安全)的验证方法与工具选型。
+
+---
+
+## NFR 的类别
+
+| 类别 | 典型指标 | 验证 phase |
+| --- | --- | --- |
+| 延迟 | P50/P95/P99 响应时间 | verify(perf-test) |
+| 吞吐 | QPS / TPS / 每秒消息数 | verify(perf-test) |
+| 并发 | 同时活跃连接 / 用户 | verify(perf-test) |
+| 容量 | 最大存储 / 队列深度 | verify(perf-test + design 估算) |
+| 错误率 | 4xx/5xx 占比,业务错误率 | verify(perf-test + smoke) |
+| 可用性 | SLA(月可用时间 %) | 上线后监控 + runbook(不是 verify 阶段) |
+| 资源 | CPU / 内存 / 带宽 | verify(perf-test + monitoring) |
+| 可扩展性 | 扩容后是否线性 | design 估算 + 上线后验证 |
+| 安全 | 渗透测试、合规 | verify 独立 security-test,or 上线前 pen test |
+| 兼容性 | 老 client / 老版本互通 | verify 独立 regression |
+
+---
+
+## 每类的验证方法
+
+### 延迟(P50/P95/P99)
+
+**工具**:
+
+- Java: JMH(微基准)、JMeter、Gatling、wrk2
+- Go: `go test -bench`、wrk、hey
+- Node/Python: k6、locust、wrk、hey
+- HTTP 层:wrk / wrk2 / hey(任意语言后端都能压)
+
+**场景设计**:
+
+- 负载剖面:`ramp up → sustain → ramp down`,每段至少 5 分钟才稳定
+- 基于真实流量分布(不要 100% 单 API 压,用 weighted 场景)
+- 数据:用 prod-like 数据池,不要空库或同一条记录疯狂压
+
+**报告字段**:
+
+```yaml
+perf:
+  p50_ms: 78
+  p95_ms: 150
+  p99_ms: 180
+  max_ms: 320
+  baseline_p99_ms: 200   # 来自 design.md NFR
+```
+
+**判定**:P99 ≤ 基线 + 容差(5-10%)。
+
+---
+
+### 吞吐(QPS / TPS)
+
+**工具**:同延迟。
+
+**注意**:
+
+- 测吞吐要"拉到失败前"(找上限),不要只测"平时够用"
+- 吞吐和延迟是 trade-off:限制 P99 下的最大 QPS 才是合理数字
+- 分"突发吞吐"(1 分钟峰值)和"持续吞吐"(30 分钟平均),NFR 两者都要说
+
+**报告字段**:
+
+```yaml
+perf:
+  sustained_qps: 5400     # 30 分钟平均
+  peak_qps: 7200          # 1 分钟峰值
+  error_rate_at_peak: 0.02
+```
+
+---
+
+### 并发连接
+
+**工具**:
+
+- WebSocket:`autocannon` / k6 websocket scenario
+- HTTP/gRPC 长连:自研 client
+- 数据库连接池:jmeter thread group / 应用监控
+
+**注意**:
+
+- 区分"connected" vs "active RPS"
+- 连接数上限受 OS / kernel(ulimit)影响,测试前要调
+
+**报告字段**:
+
+```yaml
+perf:
+  concurrent_connections: 10000
+  connection_setup_p99_ms: 50
+```
+
+---
+
+### 容量 / 数据量
+
+**验证方式**:
+
+- 填充到目标量级(如 100M 行)后跑功能 / 性能测试
+- 看查询延迟是否随数据量线性 / 退化
+- 看磁盘占用、索引效率
+
+**注意**:
+
+- 不能只在空库测,所有大表功能都要在 prod-like 数据量下验
+- 批量操作(迁移、归档)要在目标数据量下 dry-run,记录耗时
+
+---
+
+### 错误率
+
+**工具**:压测工具的 error 输出,+ APM 监控。
+
+**判定**:
+
+- 业务错误率(400/422):< 0.5%(具体看 NFR)
+- 系统错误(5xx、timeout、connection reset):< 0.1%
+- 压测里 5xx 高 → 查连接池 / OS / 下游
+
+**报告字段**:
+
+```yaml
+perf:
+  error_rate: 0.0003
+  error_breakdown:
+    timeout: 0.0001
+    http_500: 0.0001
+    http_503: 0.0001
+```
+
+---
+
+### 资源(CPU / 内存 / IO)
+
+**工具**:
+
+- 应用侧:APM(Pyroscope / JFR / pprof / py-spy)
+- 系统侧:`top` / `htop` / `vmstat` / Prometheus + Grafana
+- 容器:Docker stats / k8s metrics-server
+
+**场景**:
+
+- 压测时开监控,记 CPU / 内存峰值
+- 看是否有内存泄漏(长压后 heap 增长)
+- 看 GC 频率(Java / Go)
+
+**报告字段**:
+
+```yaml
+perf:
+  cpu_peak_pct: 65
+  mem_peak_mb: 1200
+  gc_pause_p99_ms: 80
+```
+
+---
+
+### 可用性(SLA)
+
+**不在 verify 阶段**(verify 是短时测试,无法覆盖 99.9% / 99.99% 级别的 SLA)。
+
+做法:
+
+- 上线 rollout 时小流量监控(canary)
+- 7 天 / 30 天窗口的 SLI / SLO 监控
+- 在 `design.md` 的 runbook 里定义
+
+verify 阶段只检查:"压测里无明显崩溃点 / 连续错误 / 资源泄漏"。
+
+---
+
+### 安全
+
+**方式**:
+
+- Static:SAST 工具(SonarQube、semgrep、bandit)
+- Dynamic:OWASP ZAP、Burp Suite
+- Dependency:npm audit、snyk、trivy
+
+**通常**作为独立 `security-test.md` 或 `compliance-test.md` 报告。
+
+L3 大改涉及认证 / 授权 / PII 时强制要求。
+
+---
+
+### 兼容性 / 回归
+
+**方式**:
+
+- 跑老版本 client 调新 API(或反之),看行为
+- 老数据迁移后功能全跑一遍
+- 回归测试套件(自动化)
+
+**报告**:`regression-test.md` 或 `compatibility-test.md`。
+
+---
+
+## 压测环境的要求
+
+| 项 | 要求 |
+| --- | --- |
+| 规模 | 至少和 prod 同配(不要用 1 核测 8 核) |
+| 数据 | prod-like 数据量和分布 |
+| 网络 | 和 prod 类似的 latency / 带宽 |
+| 下游依赖 | 真实(integration 环境)或 high-fidelity mock |
+| 压测 client | 独立机器,不要和被测服务同机(会抢资源) |
+
+如果条件不足(如只能在小环境压),结果要加 disclaimer + 估算到 prod 的系数,并在 release 后用 canary 验证。
+
+---
+
+## 基线对比
+
+NFR 两种写法:
+
+1. **绝对值**:P99 ≤ 200ms — 简单,易判断
+2. **相对值**:P99 不回归超过前版本的 10% — 稳定,但要求有基线数据
+
+verify 时:
+
+- 如果 design.md 给了绝对值 → 直接比
+- 如果给了相对值 → 跑前版本基线 + 本次 → 对比
+- 两者都给 → 优先绝对,相对作为"是否退化"的 sanity check
+
+**基线的管理**:
+
+- 每次重大版本发布跑一次基线；默认存 `~/.devflow/workspace/changes/<feature-xx>/knowledge/解决方案/perf-baseline-<date>.md`（历史 in-repo 模式可存 `<repo>/devflow/knowledge/解决方案/...`）
+- 后续比较用最新 baseline
+
+---
+
+## 失败场景的处理
+
+### NFR 不达标
+
+| 严重度 | 处置 |
+| --- | --- |
+| P99 超 30% | 必回退 tech-spec,重新设计 |
+| P99 超 10-30% | orchestrator 决策:接受 or 回退 |
+| 超 5-10% | 记 concern + 跟进 task |
+| ≤ 5% | 接受,记 note |
+
+### 资源泄漏
+
+任何可检测的泄漏(heap / file handle / goroutine / 数据库连接)都必须回退 apply 修,不讨价还价。
+
+### 间歇性 flaky
+
+- 3 次压测都复现 → 是真问题,回退
+- 10 次中 1 次 → 排查但可能接受(若不涉及稳定性 NFR)
+- 和压测 client 本身 flaky 区分(比如 client 占 100% CPU)
+
+---
+
+## 常见坑
+
+- **压错端点**:url 配置错了压了健康检查,看到 10 万 QPS 以为很牛
+- **数据太少**:query cache 一直 hit,实际生产 miss 率高
+- **压测单个固定 user_id**:所有 branch / cache 走一个分支,不真实
+- **用 debug build 压**:Java 开了 verbose GC log,Go 开了 race detector → 性能下降 10x
+- **没热身**:JVM / V8 没 JIT warmup 就开始记数据,P99 虚高
+- **同机压测**:OS 调度互相影响,结果不可信
+- **只测一个实例**:集群场景下负载均衡 / 分片效应没测出来
+- **网络配置偷懒**:用 127.0.0.1 压,忽略 DNS / TLS / 网关开销
+
+---
+
+## 最小可行 NFR 验证流程(L2)
+
+当时间紧 / 环境受限:
+
+1. 用 wrk 或 hey 跑 5 分钟,固定并发(如 50)
+2. 看 P99 + error rate
+3. 对比 design NFR
+4. 记 perf-test.md
+
+粗但比没有强。L2 允许这种简化(需标明 "simplified perf test")。L3 不允许。
+
+---
+
+## 与 design.md 的对齐
+
+design.md 里的 NFR 是 verify 唯一的真源:
+
+- 没写在 design 的 NFR,verify 不测(不是"建议测")
+- design 改过 NFR(revise),verify 按最新
+- verify 发现 design 漏了关键 NFR → 回退 tech-spec 补(不是自己在 verify 里加)