Performance design

Performance Design

用于设计项目性能策略。

When to Use

• 需要定义性能目标和基准
• 需要设计缓存策略
• 需要识别性能瓶颈和风险
• 需要制定性能测试计划
• 涉及高并发或大数据量处理

NOT When to Use

• 纯本地 CLI 工具，无性能压力
• MVP 阶段，性能不是首要关注
• 已有完整性能设计，只需实现

Input

来源	内容
system-design.md	架构和模块划分
api-spec.md	API 端点和数据流
scope.md	功能范围和规模预期

Output Schema

文件	类型	说明
wiki/03-architecture/performance.md	性能设计	目标/基准/缓存/风险

Minimum Viable Output

• 性能目标（延迟/吞吐量）
• 关键链路性能分析（≥2 条）
• 缓存策略概要
• 性能风险清单

Complete Output

• 完整性能设计，含：
  • 性能目标（延迟/吞吐量/容量）
  • 关键链路性能分析
  • 缓存策略详细设计
  • 数据库索引策略
  • 并发模型
  • 性能测试计划
  • 性能风险登记册
  • 资源预估（QPS/存储/带宽）

Dependencies

类型	说明
前置	architecture-decisions（架构已定）、data-api-design（API 已定义）
后置	delivery-planning（性能任务拆分）
依赖读取	system-design.md、api-spec.md、scope.md

Procedure

Phase 1: 理解上下文

1. 读取 system-design.md → 确定关键链路和数据流
2. 读取 api-spec.md → 确定 API 端点和调用频率
3. 读取 scope.md → 确定用户规模和增长预期
4. 识别性能敏感场景：哪些操作需要快速响应？

Phase 2: 定义性能目标

## 性能目标

### 用户感知目标

| 场景 | 目标 | 可接受上限 |
|------|------|-----------|
| 页面首次加载 | < 2s | 3s |
| API 响应（P50） | < 200ms | 500ms |
| API 响应（P99） | < 1s | 2s |
| 用户操作反馈 | < 100ms | 300ms |

### 系统容量目标

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 同时在线用户 | 100 | MVP 阶段 |
| 日活用户 | 1000 | 预期 |
| QPS（查询） | 50 | 峰值 |
| QPS（写入） | 10 | 峰值 |

### 资源约束

资源预算必须从性能目标推导而来，不能凭空设定：

```markdown
## 资源预算推导

**从性能目标推导**：

目标 QPS = 50 → 单机 API 服务器处理能力约 100 QPS（预留 50% 余量）
→ API 服务器：2 vCPU / 4GB（可水平扩展）

目标 P99 延迟 ≤ 1s → 数据库查询延迟 ≤ 50ms
→ 数据库：4 vCPU / 16GB（足够缓存热点数据）

日活 1000 用户 → 峰值 QPS ≈ 50，读写比 9:1
→ 缓存：2GB Redis（可缓存 90% 热数据）
→ 带宽：100Mbps（峰值 50 QPS × 200KB/响应 ≈ 10Mbps，留 10× 余量）

资源	预算	推导依据
API 服务器	2 vCPU / 4GB	目标 QPS 50 × 2 倍余量
数据库	4 vCPU / 16GB	目标 P99 ≤ 1s，DB 延迟 ≤ 50ms
缓存	2GB	日活 1000，峰值 QPS 50，Redis 可缓存热数据
带宽	100Mbps	峰值 10Mbps × 10 倍余量

### Phase 3: 关键链路分析

```markdown
## 关键链路性能分析

### 链路 1: 核心写入操作

用户 → API Gateway → Auth Service → Database → Cache (JWT)

| 步骤 | 当前预估 | 目标 | 优化空间 |
|------|---------|------|---------|
| 网络延迟 | 50ms | 30ms | CDN 优化 |
| API 处理 | 100ms | 50ms | 缓存 JWT |
| 数据库查询 | 50ms | 20ms | 索引优化 |
| **总计** | **200ms** | **100ms** | |

### 链路 2: 核心查询操作

用户 → Search API → Cache → Search Engine → Database

| 步骤 | 当前预估 | 目标 | 优化空间 |
|------|---------|------|---------|
| Cache 命中 | 5ms | 5ms | 缓存预热 |
| Cache 未命中 | 200ms | 100ms | ES 优化 |
| **总计（命中）** | **5ms** | **5ms** | |
| **总计（未命中）** | **200ms** | **100ms** | |

Phase 4: 缓存策略

## 缓存策略

### 缓存层级

┌─────────────────────────────────┐ │ CDN (静态资源) │ ← 浏览器缓存 / CDN ├─────────────────────────────────┤ │ 应用缓存 (Redis) │ ← 热数据 ├─────────────────────────────────┤ │ 数据库 (Query Cache) │ ← 慢查询缓存 └─────────────────────────────────┘

### 缓存策略矩阵

**概念区分**：
- **TTL（Time To Live）**：数据多久后自然过期，不依赖主动更新
- **更新策略**：数据变化时如何同步缓存（主动失效/后台刷新/不更新）
- **淘汰策略**：缓存在满时如何踢出旧数据（LRU/LFU/FIFO）

| 数据类型 | TTL | 更新策略 | 淘汰策略 |
|---------|-----|---------|---------|
| 用户 Session | 24h | 主动失效（变更时删除） | LRU |
| 配置信息 | 1h | 主动失效（变更时推送） | LFU |
| 列表数据 | 5min | TTL + 后台异步刷新 | LRU |
| 单个资源 | 10min | 主动失效（变更时删除） | LRU |
| 搜索结果 | 1min | TTL（不主动刷新） | LRU |

### 缓存键设计

```markdown
## 缓存键命名规范

格式: `<前缀>:<资源>:<ID>:<维度>`

示例:
- user:profile:123                    # 用户资料
- user:profile:123:v2                # 版本化
- post:list:page:2:size:20           # 分页
- post:feed:123:time                 # 用户动态

缓存问题处理

问题	解决方案
缓存穿透	布隆过滤器 / 空值缓存
缓存击穿	互斥锁 / 永不过期 + 后台刷新
缓存雪崩	TTL 随机偏移 / 热点数据永不过期

### Phase 5: 数据库优化

```markdown
## 数据库优化

### 索引策略

| 表 | 查询模式 | 索引 |
|----|---------|------|
| users | WHERE email = ? | idx_email (unique) |
| posts | WHERE user_id = ? ORDER BY created_at | idx_user_created |
| posts | WHERE status = ? | idx_status |

### 分页策略

```sql
-- 偏移分页（大数据量时慢）
SELECT * FROM posts ORDER BY id LIMIT 100 OFFSET 10000;

-- 游标分页（推荐）
SELECT * FROM posts WHERE id < last_id ORDER BY id DESC LIMIT 100;

连接池配置

## 连接池

| 场景 | 池大小 | 说明 |
|------|--------|------|
| 读操作 | 20 连接 | 可配置 |
| 写操作 | 10 连接 | 少于读 |
| 批量操作 | 5 连接 | 后台任务 |

### Phase 6: 并发模型

```markdown
## 并发模型

### 线程/进程设计

┌─────────────────────────────────────────┐ │ 主线程 (请求入口) │ ├─────────────────────────────────────────┤ │ Worker Pool (10-50 workers) │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ W1 │ │ W2 │ │ W3 │ │ W4 │ ...│ │ └─────┘ └─────┘ └─────┘ └─────┘ │ └─────────────────────────────────────────┘

### 限流策略

```markdown
## 限流

| 限流维度 | 阈值 | 策略 |
|---------|------|------|
| IP | 100 QPM | 令牌桶 |
| User | 1000 QPH | 令牌桶 |
| API | 50 QPS | 令牌桶 |

### 熔断策略

当错误率 > 10% 或延迟 > 2s 时：
- [ ] 熔断器开启
- [ ] 快速返回降级响应
- [ ] 后台探测恢复

### Phase 7: 性能测试计划

```markdown
## 性能测试计划

### 测试类型

| 类型 | 工具 | 目标 |
|------|------|------|
| 基准测试 | ab / wrk | 单接口性能 |
| 负载测试 | k6 / JMeter | 峰值 QPS |
| 压力测试 | 逐步加压 | 崩溃点 |
| 持久测试 | 长时间运行 | 内存泄漏 |

### 测试场景

| ID | 场景 | 并发 | 持续时间 | 目标 |
|----|------|------|---------|------|
| PT1 | 首页访问 | 50 | 5min | P99 < 500ms |
| PT2 | 核心查询 | 30 | 5min | P99 < 1s |
| PT3 | 混合读写 | 20 | 10min | 无错误 |

### 性能回归

- 每次发布前运行基准测试
- P99 退化 > 20% 阻塞发布
- 建立性能监控仪表盘

Phase 8: 性能风险登记

## 性能风险登记

| ID | 风险描述 | 影响 | 可能性 | 缓解措施 |
|----|---------|------|--------|---------|
| P1 | 数据库无索引导致慢查询 | 高 | 中 | 上线前加索引 |
| P2 | 缓存失效导致雪崩 | 高 | 低 | TTL 随机偏移 |
| P3 | 第三方 API 延迟不稳定 | 中 | 中 | 超时 + 重试 + 降级 |
| P4 | 大数据量导出 OOM | 高 | 低 | 流式处理 + 分页 |

Target Pages

• <项目根目录>/wiki/03-architecture/performance.md

Changelog

日期	变更	原因
2026-07-15	性能链路示例改为核心读写操作	避免示例预设产品功能
2026-04-30	修复：缓存策略矩阵新增"概念区分"说明（TTL vs 更新策略 vs 淘汰策略），更新策略列补全具体方式；资源约束新增推导过程（从 QPS/延迟目标推导服务器/数据库/缓存/带宽配置）	缓存策略概念混淆、资源预算未从性能目标推导
2026-04-30	新建 skill	性能设计是架构重要维度，之前缺失