@umacloud/knowledge 1.0.1

package/performance/01-standards/performance-standards.md

@@ -0,0 +1,156 @@
+---
+id: performance-standards
+title: 性能优化标准（前后端）
+domain: performance
+category: 01-standards
+difficulty: advanced
+tags: [performance, optimization, database, query, index, cache, frontend, lcp, bundle, cdn, lazy-loading]
+quality_score: 92
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# 性能优化标准
+
+## 数据库性能
+
+### 索引策略
+```sql
+-- B-tree（默认）：等值查询、范围查询、排序
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_created_at ON orders(created_at DESC);
+
+-- 复合索引：多列查询（顺序很重要！最左前缀）
+CREATE INDEX idx_orders_user_status ON orders(user_id, status, created_at);
+
+-- GIN：JSONB / 全文搜索 / 数组
+CREATE INDEX idx_products_attrs ON products USING GIN(attrs);
+
+-- 部分索引：只索引活跃数据
+CREATE INDEX idx_active_orders ON orders(user_id) WHERE status != 'cancelled';
+```
+
+### 查询优化
+```sql
+-- ❌ SELECT * 返回不需要的列
+SELECT * FROM users WHERE team_id = 123;
+
+-- ✅ 只选需要的列
+SELECT id, name, email FROM users WHERE team_id = 123;
+
+-- ❌ COUNT(*) 做分页 total（大表慢）
+SELECT COUNT(*) FROM orders WHERE user_id = 123;
+
+-- ✅ 估算总数（大表）
+SELECT reltuples::bigint FROM pg_class WHERE relname = 'orders';
+
+-- ❌ N+1：循环内查子资源
+-- ✅ JOIN 或批量 IN
+SELECT o.*, u.name FROM orders o JOIN users u ON o.user_id = u.id WHERE o.status = 'pending';
+```
+
+### 连接池
+```
+# PostgreSQL 连接池配置
+max_connections: 100
+pool_size: 20        # 应用连接池
+pool_max_overflow: 10
+pool_recycle: 3600   # 1小时回收防泄漏
+statement_timeout: 30000  # 30s 超时
+```
+
+## 缓存策略
+
+### 多层缓存
+```
+浏览器缓存 → CDN → 应用缓存(Redis) → 数据库缓存 → 数据库
+```
+
+### Redis 缓存模式
+```python
+# Cache-Aside（最常用）
+def get_user(user_id):
+    # 1. 查缓存
+    cached = redis.get(f"user:{user_id}")
+    if cached:
+        return json.loads(cached)
+    # 2. 查数据库
+    user = db.query(User).get(user_id)
+    # 3. 写缓存（带 TTL）
+    redis.setex(f"user:{user_id}", 300, json.dumps(user.to_dict()))
+    return user
+
+# Write-Through（写时更新缓存）
+def update_user(user_id, data):
+    user = db.update(User, user_id, data)
+    redis.setex(f"user:{user_id}", 300, json.dumps(user.to_dict()))
+```
+
+### 缓存失效
+- TTL 失效（5-60 分钟）
+- 主动失效（数据变更时删除缓存键）
+- LRU 淘汰（内存不足时）
+
+## 前端性能
+
+### Core Web Vitals 目标
+| 指标 | 目标 | 测量 |
+|------|------|------|
+| LCP（最大内容绘制） | < 2.5s | 首屏最大元素渲染时间 |
+| INP（交互延迟） | < 200ms | 用户交互到响应时间 |
+| CLS（布局偏移） | < 0.1 | 视觉稳定性 |
+
+### Bundle 优化
+```javascript
+// ❌ 全量导入
+import _ from 'lodash';
+
+// ✅ 按需导入
+import debounce from 'lodash/debounce';
+
+// ✅ 动态导入（代码分割）
+const Chart = lazy(() => import('./Chart'));
+
+// ✅ 路由级分割
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+```
+
+### 图片优化
+```html
+<!-- ❌ 不优化的原图 -->
+<img src="/photos/big.jpg">
+
+<!-- ✅ 响应式 + 懒加载 + 现代格式 -->
+<img
+  src="/photos/medium.avif"
+  srcset="/photos/small.avif 480w, /photos/medium.avif 800w, /photos/large.avif 1200w"
+  sizes="(max-width: 600px) 480px, 800px"
+  loading="lazy"
+  decoding="async"
+  width="800" height="600"
+/>
+```
+
+### API 响应优化
+```http
+# 启用 gzip/brotli 压缩
+Content-Encoding: br
+
+# 条件请求（304 Not Modified）
+ETag: "abc123"
+Cache-Control: public, max-age=300
+
+# 字段过滤
+GET /api/users?fields=id,name,email
+```
+
+## 性能预算
+
+| 资源 | 预算 |
+|------|------|
+| JS bundle | < 150KB (gzip) |
+| CSS | < 30KB (gzip) |
+| 图片 | < 200KB (首屏) |
+| 字体 | < 50KB |
+| API 响应 | p95 < 200ms |
+| 数据库查询 | p95 < 50ms |

package/performance/02-playbooks/query-optimization-playbook.md

@@ -0,0 +1,103 @@
+---
+id: query-optimization-playbook
+title: 数据库查询优化实战手册
+domain: performance
+category: 02-playbooks
+difficulty: advanced
+tags: [performance, database, postgresql, query, optimization, index, explain, analyze, n-plus-1, pagination, cache]
+quality_score: 92
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 数据库查询优化实战手册
+
+## 诊断工具：EXPLAIN ANALYZE
+
+```sql
+-- 查看真实执行计划（实际跑一遍）
+EXPLAIN ANALYZE
+SELECT * FROM orders WHERE user_id = 123 ORDER BY created_at DESC LIMIT 20;
+
+-- 关键看：
+-- Seq Scan（全表扫描）→ 需要索引
+-- Index Scan（索引扫描）→ 好
+-- Bitmap Heap Scan（批量索引）→ 还行
+-- Sort（内存排序）→ 可能需要索引
+-- Nested Loop（JOIN）→ 大表可能慢
+```
+
+## 常见优化模式
+
+### 1. 全表扫描 → 加索引
+```sql
+-- EXPLAIN 显示 Seq Scan
+EXPLAIN ANALYZE SELECT * FROM orders WHERE status = 'pending';
+-- → 加索引
+CREATE INDEX idx_orders_status ON orders(status);
+```
+
+### 2. 大 OFFSET 分页 → cursor 分页
+```sql
+-- ❌ OFFSET 10000 扫 10020 行
+SELECT * FROM products ORDER BY id OFFSET 10000 LIMIT 20;
+
+-- ✅ WHERE 直接定位（扫 20 行）
+SELECT * FROM products WHERE id > 5000 ORDER BY id LIMIT 20;
+```
+
+### 3. N+1 → 批量查询
+```python
+# ❌ 100 用户 = 101 次 DB 查询
+for u in users:
+    u.profile = db.query("SELECT * FROM profiles WHERE user_id=?", u.id)
+
+# ✅ 1 次查全部
+profiles = db.query("SELECT * FROM profiles WHERE user_id IN %s", user_ids)
+```
+
+### 4. COUNT(*) 慢 → 估算
+```sql
+-- ❌ 精确 COUNT（大表几秒）
+SELECT COUNT(*) FROM orders WHERE status = 'pending';
+
+-- ✅ 统计信息估算（毫秒）
+SELECT reltuples::bigint FROM pg_class WHERE relname='orders';
+
+-- ✅ 或维护一个计数器表
+UPDATE counters SET count = count + 1 WHERE table_name = 'orders' AND status = 'pending';
+```
+
+### 5. 慢 JOIN → 物化视图 / 缓存
+```sql
+-- ❌ 复杂 JOIN 每次都算
+SELECT o.*, u.name, p.title FROM orders o
+JOIN users u ON o.user_id = u.id
+JOIN products p ON o.product_id = p.id
+WHERE o.status = 'pending';
+
+-- ✅ 物化视图定期刷新
+CREATE MATERIALIZED VIEW order_summary AS
+SELECT o.*, u.name, p.title FROM ...;
+REFRESH MATERIALIZED VIEW CONCURRENTLY order_summary;
+```
+
+## 连接池配置
+
+```python
+# SQLAlchemy 示例
+engine = create_engine(url,
+    pool_size=20,          # 常驻连接数
+    max_overflow=10,       # 突发连接
+    pool_pre_ping=True,    # 使用前检查连接活性
+    pool_recycle=3600,     # 1 小时回收（防 "server closed the connection"）
+)
+```
+
+## 查询超时
+
+```sql
+-- PostgreSQL 语句级超时
+SET statement_timeout = '30s';
+SELECT ...;  -- 超过 30s 自动取消
+```

package/performance/03-checklists/performance-checklist.md

@@ -0,0 +1,56 @@
+---
+id: performance-checklist
+title: 性能审查清单
+domain: performance
+category: 03-checklists
+difficulty: intermediate
+tags: [performance, checklist, database, frontend, cache, index, bundle, lcp, lazy-loading, query, redis]
+quality_score: 88
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 性能审查清单
+
+## 数据库
+- [ ] 没有 Seq Scan（全表扫描）→ 所有查询命中索引
+- [ ] 没有 N+1 查询 → 用 JOIN / eager loading / batch
+- [ ] list 端点有 LIMIT + 分页
+- [ ] COUNT(*) 大表用估算
+- [ ] 连接池大小合理（20 基础 + 10 突发）
+- [ ] 查询有超时（statement_timeout 30s）
+- [ ] 慢查询日志已启用
+
+## 缓存
+- [ ] 热点数据有缓存（Redis / 内存）
+- [ ] 缓存有 TTL（不永久缓存）
+- [ ] 写操作更新缓存（cache-aside 或 write-through）
+- [ ] 缓存击穿防护（singleflight 或互斥锁）
+- [ ] 缓存有降级策略（Redis 挂了仍能服务）
+
+## 前端
+- [ ] JS bundle < 150KB（gzip）
+- [ ] 路由级代码分割（lazy import）
+- [ ] 图片用 AVIF/WebP + 响应式 srcset
+- [ ] 图片懒加载（loading="lazy"）
+- [ ] 字体用 font-display: swap
+- [ ] 关键 CSS 内联（首屏不阻塞）
+
+## API 响应
+- [ ] 启用 gzip/brotli 压缩
+- [ ] 响应有 ETag + Cache-Control
+- [ ] 大响应支持字段过滤（?fields=id,name）
+- [ ] p95 < 200ms
+- [ ] 无阻塞调用（重操作走异步队列）
+
+## Core Web Vitals
+- [ ] LCP < 2.5s
+- [ ] INP < 200ms
+- [ ] CLS < 0.1
+- [ ] TTFB < 600ms
+
+## 资源使用
+- [ ] CPU 使用率 < 70%（常态）
+- [ ] 内存使用率 < 80%（常态）
+- [ ] 数据库连接池 < 80%
+- [ ] 磁盘 IOPS 在预算内

package/performance/04-antipatterns/performance-antipatterns.md

@@ -0,0 +1,146 @@
+---
+id: performance-antipatterns
+title: 性能反模式（避坑指南）
+domain: performance
+category: 04-antipatterns
+difficulty: intermediate
+tags: [performance, antipattern, frontend, backend, database, cache, bundle, waterfall, debounce, memoization, lazy-loading]
+quality_score: 88
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 性能反模式（避坑指南）
+
+## 前端
+
+### 1. 巨型 bundle（不分割）
+```javascript
+// ❌ 全量导入 + 单 chunk
+import _ from 'lodash';           // 70KB
+import moment from 'moment';       // 70KB
+import * as Icons from 'lucide';   // 全部图标！
+
+// ✅ 按需导入 + 路由分割
+import debounce from 'lodash/debounce';   // 1KB
+import { format } from 'date-fns';         // 7KB
+import { Search } from 'lucide-react';     // 单图标
+const Settings = lazy(() => import('./Settings'));  // 路由分割
+```
+
+### 2. 渲染瀑布（阻塞渲染的 CSS/JS）
+```html
+<!-- ❌ CSS 阻塞渲染 + JS 阻塞解析 -->
+<head>
+  <link rel="stylesheet" href="/all.css">  <!-- 200KB，渲染阻塞 -->
+  <script src="/analytics.js"></script>     <!-- 解析阻塞 -->
+</head>
+
+<!-- ✅ 关键 CSS 内联 + JS 异步 -->
+<head>
+  <style>/* 关键 CSS 内联 */</style>
+  <link rel="preload" href="/rest.css" as="style" onload="this.rel='stylesheet'">
+  <script src="/analytics.js" defer></script>
+</head>
+```
+
+### 3. 不用 key 的列表渲染
+```jsx
+// ❌ 无 key → React 每次全量 diff（慢）
+{items.map(item => <Row data={item} />)}
+
+// ✅ 稳定 key → React 精准 diff（快）
+{items.map(item => <Row key={item.id} data={item} />)}
+```
+
+### 4. 不防抖的高频事件
+```jsx
+// ❌ 每次按键都发请求（打字 10 字 = 10 次请求）
+<input onChange={e => search(e.target.value)} />
+
+// ✅ 防抖（停止输入 300ms 后才请求）
+<input onChange={e => debouncedSearch(e.target.value)} />
+const debouncedSearch = useMemo(() => debounce(search, 300), []);
+```
+
+## 后端
+
+### 5. 同步阻塞做重操作
+```python
+# ❌ 请求内发邮件 / 处理图片（用户等 10s）
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    send_welcome_email(user)      # 阻塞 5s
+    resize_avatar(user)            # 阻塞 5s
+    return user  # 用户等了 10s
+
+# ✅ 异步队列（用户立刻拿到响应）
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    enqueue_job("send_welcome_email", user.id)  # 毫秒
+    enqueue_job("resize_avatar", user.id)        # 毫秒
+    return user  # 用户等了 200ms
+```
+
+### 6. 无缓存的重复计算
+```python
+# ❌ 每次请求都算排行榜（重查询）
+@app.get("/leaderboard")
+def leaderboard():
+    return db.query("SELECT ... ORDER BY score DESC LIMIT 100")  # 2s
+
+# ✅ 缓存 + 后台刷新
+@app.get("/leaderboard")
+@cache(ttl=300)  # 缓存 5 分钟
+def leaderboard():
+    return db.query("...")
+```
+
+### 7. 无连接池
+```python
+# ❌ 每次请求新建数据库连接（TCP 握手 + 认证 ~50ms）
+def query(sql):
+    conn = psycopg2.connect(url)  # 50ms 开销
+    result = conn.execute(sql)
+    conn.close()
+    return result
+
+# ✅ 连接池复用（~1ms 获取已建连接）
+pool = create_connection_pool(url, size=20)
+def query(sql):
+    with pool.get_conn() as conn:
+        return conn.execute(sql)
+```
+
+### 8. 未设置查询超时
+```python
+# ❌ 慢查询无限等待（连接池耗尽）
+db.execute("SELECT * FROM big_table")  # 可能跑 10 分钟
+
+# ✅ 语句级超时（30s 自动取消）
+db.execute("SET statement_timeout = 30000")
+db.execute("SELECT * FROM big_table")  # 超 30s 取消
+```
+
+## 数据库
+
+### 9. SELECT * 返回不需要的列
+```sql
+-- ❌ 传输 + 序列化不需要的列（BLOB/JSONB 很大）
+SELECT * FROM products WHERE category = 'electronics';
+
+-- ✅ 只查需要的列
+SELECT id, name, price_cents FROM products WHERE category = 'electronics';
+```
+
+### 10. 应用层排序（不在 SQL 里排）
+```python
+# ❌ 查全部 → Python 排序（内存爆炸 + 慢）
+products = db.query("SELECT * FROM products")
+sorted_products = sorted(products, key=lambda p: p.price, reverse=True)
+
+# ✅ SQL 排序（利用索引，快）
+products = db.query("SELECT * FROM products ORDER BY price DESC")
+```