@umacloud/knowledge 1.0.1

package/backend/01-standards/caching-strategies-complete.md

@@ -0,0 +1,390 @@
+---
+id: caching-strategies-complete
+title: 缓存策略完整指南
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [backend, caching, complete, http, redis, strategies, 应用层缓存, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 缓存策略完整指南
+
+## 概述
+
+缓存是提升系统性能和降低数据库负载的核心手段。正确的缓存策略可以将响应时间从秒级降至毫秒级，但错误的缓存策略会导致数据不一致、缓存雪崩等严重问题。本指南覆盖 Redis、Memcached、CDN、HTTP 缓存和应用缓存的完整策略。
+
+---
+
+## 缓存层次架构
+
+```
+客户端 -> CDN -> 反向代理缓存 -> 应用层缓存 -> 分布式缓存 -> 数据库
+  L1       L2        L3              L4            L5          L6
+
+L1: 浏览器缓存 (HTTP Cache-Control)
+L2: CDN 边缘缓存 (CloudFlare/CloudFront)
+L3: Nginx/Varnish 反向代理缓存
+L4: 进程内缓存 (LRU/本地 Map)
+L5: Redis/Memcached 分布式缓存
+L6: 数据库查询缓存
+```
+
+---
+
+## Redis 缓存
+
+### 基本操作
+
+```python
+import redis
+import json
+from datetime import timedelta
+
+r = redis.Redis(host="localhost", port=6379, decode_responses=True)
+
+# 缓存读取模式 (Cache-Aside)
+def get_user(user_id: str) -> dict | None:
+    # 1. 先查缓存
+    cached = r.get(f"user:{user_id}")
+    if cached:
+        return json.loads(cached)
+
+    # 2. 缓存未命中，查数据库
+    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
+    if user is None:
+        # 缓存空值，防止缓存穿透
+        r.set(f"user:{user_id}", json.dumps(None), ex=60)
+        return None
+
+    # 3. 写入缓存
+    r.set(f"user:{user_id}", json.dumps(user), ex=3600)
+    return user
+```
+
+### 缓存更新模式
+
+```python
+# 模式1: Cache-Aside (旁路缓存) - 最常用
+def update_user(user_id: str, data: dict):
+    db.execute("UPDATE users SET ... WHERE id = %s", user_id)
+    r.delete(f"user:{user_id}")   # 删除缓存，下次读取时重建
+
+# 模式2: Write-Through (直写缓存)
+def update_user_write_through(user_id: str, data: dict):
+    db.execute("UPDATE users SET ... WHERE id = %s", user_id)
+    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
+    r.set(f"user:{user_id}", json.dumps(user), ex=3600)  # 同步更新缓存
+
+# 模式3: Write-Behind (异步写回)
+def update_user_write_behind(user_id: str, data: dict):
+    r.set(f"user:{user_id}", json.dumps(data), ex=3600)
+    queue.send("user_update", {"user_id": user_id, "data": data})
+    # 异步消费者批量写入数据库
+```
+
+### 缓存穿透防护
+
+```python
+import hashlib
+
+# 布隆过滤器防穿透
+from pybloom_live import BloomFilter
+
+user_bloom = BloomFilter(capacity=1000000, error_rate=0.01)
+
+# 初始化时加载所有 ID
+for user_id in db.query("SELECT id FROM users"):
+    user_bloom.add(user_id)
+
+def get_user_safe(user_id: str) -> dict | None:
+    # 布隆过滤器快速判断
+    if user_id not in user_bloom:
+        return None   # 确定不存在
+
+    cached = r.get(f"user:{user_id}")
+    if cached == "null":  # 缓存空值
+        return None
+    if cached:
+        return json.loads(cached)
+
+    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
+    if user is None:
+        r.set(f"user:{user_id}", "null", ex=60)  # 缓存空值 60s
+        return None
+
+    r.set(f"user:{user_id}", json.dumps(user), ex=3600)
+    return user
+```
+
+### 缓存雪崩防护
+
+```python
+import random
+
+def set_with_jitter(key: str, value: str, base_ttl: int):
+    """添加随机抖动，避免大量 key 同时过期"""
+    jitter = random.randint(0, base_ttl // 10)
+    r.set(key, value, ex=base_ttl + jitter)
+
+# 互斥锁防止缓存击穿
+def get_hot_data(key: str) -> dict:
+    cached = r.get(key)
+    if cached:
+        return json.loads(cached)
+
+    lock_key = f"lock:{key}"
+    if r.set(lock_key, "1", nx=True, ex=10):  # 获取锁
+        try:
+            data = db.query_heavy_data(key)
+            r.set(key, json.dumps(data), ex=3600)
+            return data
+        finally:
+            r.delete(lock_key)
+    else:
+        # 未获取锁，等待后重试
+        time.sleep(0.1)
+        return get_hot_data(key)
+```
+
+### Redis 数据结构应用
+
+```python
+# 排行榜 (Sorted Set)
+r.zadd("leaderboard", {"user:1": 100, "user:2": 85, "user:3": 92})
+top_10 = r.zrevrange("leaderboard", 0, 9, withscores=True)
+
+# 计数器 (String + INCR)
+r.incr("page_views:homepage")
+r.incrby("api_calls:today", 1)
+
+# 分布式锁
+def acquire_lock(resource: str, ttl: int = 10) -> str | None:
+    token = str(uuid.uuid4())
+    if r.set(f"lock:{resource}", token, nx=True, ex=ttl):
+        return token
+    return None
+
+def release_lock(resource: str, token: str):
+    script = """
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+    end
+    return 0
+    """
+    r.eval(script, 1, f"lock:{resource}", token)
+
+# 会话存储 (Hash)
+r.hset("session:abc123", mapping={
+    "user_id": "123",
+    "role": "admin",
+    "login_at": str(int(time.time())),
+})
+r.expire("session:abc123", 3600)
+```
+
+---
+
+## HTTP 缓存
+
+### Cache-Control 策略
+
+```nginx
+# 不可变资源（带 hash 的静态文件）
+location /assets/ {
+    add_header Cache-Control "public, max-age=31536000, immutable";
+}
+
+# HTML 入口文件（总是验证）
+location / {
+    add_header Cache-Control "no-cache";
+    etag on;
+}
+
+# API 响应（私有短期缓存）
+location /api/ {
+    add_header Cache-Control "private, max-age=0, must-revalidate";
+    add_header Vary "Authorization, Accept-Encoding";
+}
+
+# 图片（公共中期缓存）
+location /images/ {
+    add_header Cache-Control "public, max-age=86400, stale-while-revalidate=3600";
+}
+```
+
+### ETag 与条件请求
+
+```python
+# FastAPI ETag 实现
+from fastapi import Request, Response
+import hashlib
+
+@app.get("/api/products/{product_id}")
+async def get_product(product_id: str, request: Request, response: Response):
+    product = await db.get_product(product_id)
+    etag = hashlib.md5(json.dumps(product).encode()).hexdigest()
+
+    if request.headers.get("if-none-match") == etag:
+        return Response(status_code=304)
+
+    response.headers["ETag"] = etag
+    response.headers["Cache-Control"] = "private, max-age=60"
+    return product
+```
+
+---
+
+## CDN 缓存
+
+### CDN 配置策略
+
+```yaml
+# CloudFlare Page Rules 示例
+rules:
+  - match: "*.example.com/assets/*"
+    cache_level: cache_everything
+    edge_cache_ttl: 2592000      # 30 天
+
+  - match: "*.example.com/api/*"
+    cache_level: bypass           # API 不缓存
+
+  - match: "*.example.com/"
+    cache_level: cache_everything
+    edge_cache_ttl: 300           # 5 分钟
+    browser_cache_ttl: 0
+```
+
+### CDN 缓存失效
+
+```python
+import requests
+
+def purge_cdn_cache(urls: list[str]):
+    """CloudFlare 缓存清除"""
+    requests.post(
+        f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/purge_cache",
+        headers={"Authorization": f"Bearer {CF_TOKEN}"},
+        json={"files": urls},
+    )
+
+# 部署后自动清除
+def post_deploy():
+    purge_cdn_cache([
+        "https://example.com/",
+        "https://example.com/manifest.json",
+    ])
+```
+
+---
+
+## 应用层缓存
+
+### Python LRU 缓存
+
+```python
+from functools import lru_cache
+from cachetools import TTLCache
+
+# 简单 LRU
+@lru_cache(maxsize=1000)
+def get_config(key: str) -> str:
+    return db.query_config(key)
+
+# TTL 缓存
+config_cache = TTLCache(maxsize=500, ttl=300)
+
+def get_setting(key: str) -> str:
+    if key in config_cache:
+        return config_cache[key]
+    value = db.query_setting(key)
+    config_cache[key] = value
+    return value
+```
+
+### Node.js 本地缓存
+
+```typescript
+import NodeCache from "node-cache";
+
+const localCache = new NodeCache({
+  stdTTL: 300,          // 默认 5 分钟
+  checkperiod: 60,      // 每分钟清理过期
+  maxKeys: 10000,
+});
+
+async function getProduct(id: string): Promise<Product> {
+  const cached = localCache.get<Product>(`product:${id}`);
+  if (cached) return cached;
+
+  const product = await db.product.findUnique({ where: { id } });
+  if (product) {
+    localCache.set(`product:${id}`, product, 600);
+  }
+  return product;
+}
+```
+
+---
+
+## 缓存失效策略
+
+| 策略 | 说明 | 适用场景 |
+|------|------|----------|
+| TTL 过期 | 设置固定过期时间 | 通用场景 |
+| 主动删除 | 数据变更时删除缓存 | 一致性要求高 |
+| 事件驱动失效 | 监听变更事件清除 | 微服务架构 |
+| 版本号方案 | Key 包含版本号 | 批量失效 |
+| LRU 淘汰 | 空间满时淘汰最久未用 | 内存受限 |
+
+```python
+# 事件驱动缓存失效
+async def on_user_updated(event: UserUpdatedEvent):
+    # 清除相关缓存
+    r.delete(f"user:{event.user_id}")
+    r.delete(f"user_profile:{event.user_id}")
+    # 清除列表缓存（版本号方案）
+    r.incr("users_list_version")
+```
+
+---
+
+## 监控指标
+
+| 指标 | 说明 | 目标 |
+|------|------|------|
+| Hit Rate | 缓存命中率 | > 90% |
+| Miss Rate | 缓存未命中率 | < 10% |
+| Eviction Rate | 淘汰率 | 低且稳定 |
+| Memory Usage | 内存使用量 | < 80% maxmemory |
+| Latency P99 | 缓存访问延迟 | < 5ms |
+
+---
+
+## 常见反模式
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|----------|
+| 缓存所有数据 | 内存浪费 | 只缓存热点和高频数据 |
+| TTL 统一设置 | 缓存雪崩 | 添加随机抖动 |
+| 不缓存空值 | 缓存穿透 | 空值短 TTL 缓存 |
+| 先更新缓存再更新 DB | 数据不一致 | 先更新 DB，再删除缓存 |
+| 缓存 Key 无前缀 | 命名冲突 | 统一前缀规范 |
+| 不设 maxmemory | OOM | 配置 maxmemory + 淘汰策略 |
+
+---
+
+## Agent Checklist
+
+- [ ] 明确缓存分层策略（客户端/CDN/反向代理/应用/分布式）
+- [ ] 使用 Cache-Aside 模式（先查缓存，未命中查 DB，回填缓存）
+- [ ] 数据更新时先更新数据库，再删除缓存
+- [ ] 缓存 TTL 添加随机抖动防止雪崩
+- [ ] 缓存空值防止穿透（短 TTL）
+- [ ] 热点 Key 使用互斥锁防止击穿
+- [ ] Redis maxmemory 和淘汰策略已配置
+- [ ] 缓存 Key 命名规范（前缀:实体:ID）
+- [ ] 静态资源带 hash，Cache-Control: immutable
+- [ ] HTML 使用 no-cache + ETag
+- [ ] 接入缓存命中率监控，目标 > 90%
+- [ ] 部署时自动清除 CDN 缓存

package/backend/01-standards/config-and-observability.md

@@ -0,0 +1,77 @@
+---
+id: config-and-observability
+title: 配置管理与可观测性规范（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [配置, config, 12-factor, 环境变量, 密钥, 日志, logging, 指标, metrics, 追踪, tracing, 健康检查, 优雅停机, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 配置管理与可观测性规范（商业级必读）
+
+> 商业系统要**可配置、可观测、可运维**。配置外置（12-Factor）、结构化日志、指标、追踪、健康检查、优雅停机——线上出问题时能快速定位，是商业级与玩具的分水岭。
+
+## 1. 配置管理（12-Factor）
+
+- **配置与代码分离**：所有环境差异（DB 地址、密钥、开关、外部 URL）从**环境变量**读，绝不硬编码、绝不写死在代码里按环境 if。
+- 启动时**校验必需配置**，缺失立即失败并给清晰错误（fail-fast），不要运行到一半才崩。
+- 提供 `.env.example` 列出所有变量（占位值）；`.env` 入 gitignore。
+- 密钥走密钥管理（Vault/KMS/云 secret），不进仓库、不进镜像、不进日志。
+- 配置有合理默认 + 类型校验（如端口是数字）；分环境（dev/staging/prod）但同一份代码。
+
+## 2. 结构化日志
+
+- 日志输出**结构化 JSON**（而非纯字符串拼接），便于检索聚合。
+- 每条日志带：时间、级别、**request_id/trace_id**、服务名、关键上下文（userId、orderId）。
+- 级别用对：DEBUG(排查) / INFO(关键业务事件) / WARN(可恢复异常) / ERROR(需关注)。生产默认 INFO。
+- **绝不打印**密码、token、密钥、完整 PII（脱敏）。
+- 日志写 stdout/stderr，由平台收集（12-Factor），不自己管理日志文件轮转。
+- 请求贯穿同一 request_id，从入口到各层到响应可串联。
+
+## 3. 指标（Metrics）
+
+- 暴露关键指标（Prometheus 风格）：
+  - **RED**（面向请求的服务）：Rate(请求量)、Errors(错误率)、Duration(延迟分布 p50/p95/p99)。
+  - **USE**（面向资源）：Utilization、Saturation、Errors。
+  - 业务指标：下单数、支付成功率、注册转化等。
+- 延迟看分位数（p95/p99），不要只看平均。
+
+## 4. 分布式追踪（Tracing）
+
+- 跨服务调用传递 trace context（OpenTelemetry / W3C traceparent），串联一次请求经过的所有服务/DB/外部调用。
+- 关键 span 标注耗时与状态，定位慢在哪一环。
+
+## 5. 健康检查与优雅停机
+
+- 提供 **liveness**（进程活着）与 **readiness**（依赖就绪、可接流量）端点，供 k8s/LB 探测。
+- **优雅停机**：收到 SIGTERM 后停止接新请求、处理完在途请求、关闭连接池/释放资源再退出，避免请求被硬切。
+- 启动顺序：先连依赖（DB/缓存）就绪再标 ready。
+
+## 6. 错误与告警
+
+- 未捕获异常集中处理 + 上报（Sentry 类）；带 request_id 可回溯。
+- 对关键指标设告警阈值（错误率、p99 延迟、队列积压、支付失败率）。
+- 错误响应对客户端模糊（500 不泄露内部），日志记完整上下文。
+
+## 7. 反模式（出现即不合格）
+
+- 配置硬编码、按环境 if、密钥进代码/镜像。
+- 缺失配置运行到一半才崩（没 fail-fast）。
+- 纯字符串日志、无 request_id、无法串联一次请求。
+- 日志打印密钥/PII。
+- 只有平均延迟、没有 p95/p99；没有错误率/业务指标。
+- 没有健康检查；停机硬切导致在途请求失败。
+
+## 8. 最低交付 checklist
+
+- [ ] 配置全从 env 读、启动 fail-fast 校验、提供 .env.example、密钥走密钥管理不入仓库。
+- [ ] 结构化 JSON 日志，带 request_id/trace_id 与上下文，脱敏，输出 stdout。
+- [ ] 暴露 RED/USE + 关键业务指标，延迟看 p95/p99。
+- [ ] 跨服务传递 trace context（OpenTelemetry）。
+- [ ] liveness/readiness 端点 + 收到 SIGTERM 优雅停机。
+- [ ] 未捕获异常上报告警；关键指标设阈值告警。
+
+---
+**参考**：12-Factor App、OpenTelemetry、Google SRE（RED/USE、SLI/SLO）、Prometheus。

package/backend/01-standards/data-modeling-and-persistence.md

@@ -0,0 +1,94 @@
+---
+id: data-modeling-and-persistence
+title: 数据建模与持久化规范（商业级后端必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [数据建模, 数据库, 持久化, schema, 迁移, migration, 索引, index, 事务, transaction, n+1, 软删除, 并发, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 数据建模与持久化规范（商业级后端必读）
+
+> 框架/数据库无关的持久化硬性规范。数据层一旦设计错，后期改动代价极高。建表、迁移、索引、事务、并发都要按本标准来。
+
+## 1. Schema 设计
+
+- 每张表有**主键**：用 UUID（分布式友好、不暴露规模）或自增 BigInt（单库简单）；全项目统一一种风格。
+- 必备审计列：`created_at`、`updated_at`（带时区，UTC 存储）；需要追溯的加 `created_by`/`updated_by`。
+- 字段类型选对：金额用 `DECIMAL`/整数最小单位（**绝不用 float/double 存钱**）；时间用 `timestamptz`；枚举用受约束的字符串或原生 enum，不要用魔法数字。
+- **非空约束 + 默认值**显式声明；该唯一的加唯一约束（如 email），别只靠应用层查重（有并发漏洞）。
+- 外键 + 级联策略明确（`ON DELETE RESTRICT/CASCADE/SET NULL`）；关系正确（1:1 / 1:N / N:M 用中间表）。
+- 命名一致：表用复数 snake_case（`order_items`），列 snake_case，外键 `<entity>_id`。
+
+## 2. 范式与反范式
+
+- 默认第三范式（消除冗余、保证一致性）。
+- 仅在有明确读性能证据时，针对性反范式（冗余字段/物化视图），并写清同步策略，别一上来就反范式。
+- JSON 列适合稀疏/可变结构（设置、元数据），但**不要**把核心可查询业务字段塞进 JSON（无法建索引、难约束）。
+
+## 3. 迁移（Migration）—— 数据库变更的唯一通道
+
+- 所有 schema 变更走**版本化迁移文件**（Flyway/Liquibase/Prisma/Alembic/TypeORM migrations），纳入版本控制，**禁止手改生产库**。
+- 迁移要**可前滚**，关键变更准备回滚方案；一个迁移聚焦一件事。
+- **向后兼容的扩展式变更**（expand/contract）：加列→双写→回填→切读→删旧列，分多步上线，避免停机和锁表。
+- 大表加索引/改列用在线 DDL（`CREATE INDEX CONCURRENTLY` 等），避免长事务锁表。
+- 回填大数据分批，别一条 SQL 锁全表。
+
+## 4. 索引
+
+- 给**高频查询条件、外键、排序字段、唯一约束**建索引。
+- 复合索引遵循最左前缀；覆盖索引减少回表。
+- 不要无脑全建——索引拖慢写入、占空间；按真实查询建。
+- 定期看慢查询日志 + `EXPLAIN`，针对性优化，而非凭感觉。
+
+## 5. 事务与一致性
+
+- 事务边界在**服务层**（一个用例一个事务），不在 repository、不在 controller。
+- 事务尽量短：把外部调用（发邮件、调第三方）移出事务，失败用补偿/重试，别让外部 IO 拖长锁。
+- 并发写用乐观锁（`version`/`updated_at` 比对，冲突 409）或必要时悲观锁（`SELECT ... FOR UPDATE`）。
+- 跨服务一致性用 Saga/事件 + 幂等消费，而非分布式 2PC。
+- 钱/库存等关键不变量在 DB 层兜底（约束、唯一索引、`CHECK`），不只靠应用逻辑。
+
+## 6. 查询性能：消灭 N+1
+
+- **N+1 是后端头号性能杀手**：循环里逐条查关联 = N+1 次查询。
+- 解决：预加载（eager load / `JOIN` / `include` / `selectinload`）、批量查（`WHERE id IN (...)`）、DataLoader 批处理。
+- 列表接口务必检查是否产生 N+1；ORM 默认懒加载要警惕。
+- 只查需要的列，别 `SELECT *` 拉大对象。
+
+## 7. 软删除与数据生命周期
+
+- 需要追溯/合规的数据用**软删除**（`deleted_at` 置时间），查询默认过滤；硬删除仅用于真正一次性数据。
+- 唯一约束要考虑软删除（如 email 唯一 + 未删除）。
+- 明确数据保留策略与归档；个人数据遵守合规（可删除/可导出）。
+
+## 8. 仓储层（Repository）边界
+
+- Repository 只做持久化：领域对象 ↔ 持久化模型互转、封装查询，**不含业务规则**、**不 commit 事务**。
+- 领域层不感知 ORM；查询构造、SQL、ORM API 都关在 repository 内。
+- 复杂查询给清晰命名的方法（`findOpenOrdersByUser`），别让上层拼条件。
+
+## 9. 反模式（出现即不合格）
+
+- 手改生产库、不走迁移；迁移不可回滚、一次改一大堆。
+- 用 float 存钱；时间不带时区。
+- 唯一性只靠应用层查重（并发下重复）。
+- 列表接口 N+1；`SELECT *`；无索引的高频查询。
+- 事务写在 controller/repository；事务里调外部服务拖长锁。
+- 核心业务字段塞 JSON 列无法查询/约束。
+- 一把梭硬删除导致无法追溯/合规。
+
+## 10. 最低交付 checklist
+
+- [ ] 主键 + created_at/updated_at(UTC) + 非空/默认/唯一约束 + 外键级联明确。
+- [ ] 金额非 float、时间带时区、枚举受约束。
+- [ ] 所有 schema 变更走版本化迁移、可回滚、大表在线 DDL/分批回填。
+- [ ] 高频查询/外键/排序有索引；列表无 N+1（预加载/批量）。
+- [ ] 事务边界在服务层、短事务、关键写幂等+乐观锁、DB 层兜底不变量。
+- [ ] 需追溯数据软删除；唯一约束考虑软删除；合规可删可导出。
+- [ ] Repository 只做持久化、不含业务、不 commit。
+
+---
+**参考**：数据库范式、Expand/Contract 迁移模式、Use The Index Luke、Saga 模式、12-Factor（后端服务无状态、配置外置）。