vault backup: 2026-06-03 10:30:42

hzh/Gen2D/12-三级降级策略.md

@@ -1,25 +1,32 @@
-# 12. 三级降级策略
-
-> **一句话概括**：Generate handler 实现三级降级 — TaskQueue -> WorkerPool -> Legacy FIFO，宁可降级也不拒绝服务。
-
+---
+tags: [fallback-pattern, resilience, degradation, error-handling, go]
+create time: 2026-06-03 10:55
 ---
 
-## 降级链总览
+# 12. 三级降级策略
+
+## 概述
+
+Generate handler 实现三级降级 — TaskQueue -> WorkerPool -> Legacy FIFO，宁可降级也不拒绝服务。
+
+## 正文
+
+### 降级链总览
 
 ```mermaid
 flowchart TD
-    R["HTTP Request\nPOST /api/v1/generate"] --> A{"TaskQueue\n可用?"}
+    R["HTTP Request\nPOST /api/v1/generate"] --> A{"TaskQueue 可用?"}
 
     A -->|"Submit 成功"| S1["200 OK\ntaskId 返回"]
-    A -->|"Submit 失败"| B{"WorkerPool\n可用?"}
+    A -->|"Submit 失败"| B{"WorkerPool 可用?"}
 
     B -->|"Submit 成功"| S2["200 OK\ntaskId 返回"]
     B -->|"ErrPoolFull"| E2["503 Service\nUnavailable"]
-    B -->|"ErrUserLimit"| E3["429 Too Many\nRequests"]
-    B -->|"Pool 不可用"| C{"Legacy FIFO\nQueue 可用?"}
+    B -->|"ErrUserLimit"| E3["429 Too Many Requests"]
+    B -->|"Pool 不可用"| C{"Legacy FIFO Queue 可用?"}
 
     C -->|"Enqueue 成功"| S3["200 OK\ntaskId 返回"]
-    C -->|"Queue 不可用"| E4["500 Internal\nServer Error"]
+    C -->|"Queue 不可用"| E4["500 Internal Server Error"]
 
     style A fill:#4caf50,stroke:#333,color:#fff
     style B fill:#ff9800,stroke:#333,color:#fff
@@ -29,11 +36,9 @@ flowchart TD
     style S3 fill:#8bc34a,stroke:#333,color:#fff
 ```
 
----
+### 三级详解
 
-## 三级详解
-
-### 第一级：TaskQueue（优先路径）
+#### 第一级：TaskQueue（优先路径）
 
 | 属性 | 说明 |
 |------|------|
@@ -55,7 +60,7 @@ if taskQueue != nil {
 }
 ```
 
-### 第二级：WorkerPool（有界并发）
+#### 第二级：WorkerPool（有界并发）
 
 | 属性 | 说明 |
 |------|------|
@@ -80,7 +85,7 @@ if workerPool != nil {
 }
 ```
 
-### 第三级：Legacy FIFO（最后保底）
+#### 第三级：Legacy FIFO（最后保底）
 
 | 属性 | 说明 |
 |------|------|
@@ -98,7 +103,7 @@ c.JSON(200, taskId)
 
 ---
 
-## HTTP 状态码映射
+### HTTP 状态码映射
 
 ```mermaid
 flowchart LR
@@ -133,7 +138,7 @@ flowchart LR
 
 ---
 
-## 为什么需要三级？
+### 为什么需要三级？
 
 ```mermaid
 flowchart TB
@@ -157,9 +162,18 @@ flowchart TB
 | WorkerPool | 并发控制 + 背压 | 单机部署，需要限制资源 |
 | Legacy FIFO | 可用性兜底 | 开发/测试环境，或队列组件故障 |
 
+> [!tip] 分级降级的核心原则
+>
+> **每一级都是前一级功能的超集**。也就是说：
+> - TaskQueue = 持久化排队 + 重试 + Consumer 消费 + WorkerPool 执行
+> - WorkerPool = 有界并发 + 直接执行（跳过持久化和消费者）
+> - Legacy FIFO = 最简串行队列（跳过所有高级特性）
+>
+> 这种设计确保降级过程是**渐进的**——功能逐步减少但服务始终可用。类比现实中的「应急灯」：市电断了 → 应急灯亮 → 最差情况还有手电筒。永远保留一条最低限度的通路。
+
 ---
 
-## 设计哲学
+### 设计哲学
 
 > **宁可降级，也不能拒绝服务。**
 
@@ -171,13 +185,9 @@ flowchart TB
 
 每一级降级都意味着功能的减少，但服务的可用性始终得到保障。前端收到 `200 OK` 后，通过 SSE 或轮询获取任务进度，对用户而言体验一致。
 
----
-
 ## 关联文档
 
-| 文档 | 关系 |
-|------|------|
-| [11 - Consumer-Producer 桥接](11-consumer-producer.md) | Consumer 连接 TaskQueue 和 WorkerPool |
-| [02 - 协程池](02-worker-pool.md) | WorkerPool 的背压和限流机制 |
-| [03 - 任务队列](03-task-queue.md) | TaskQueue 接口的可插拔设计 |
-| [00 - 索引](00-index.md) | 返回文档总览 |
+- [[11-Consumer-Producer桥接]] — Consumer 连接 TaskQueue 和 WorkerPool
+- [[02-协程池]] — WorkerPool 的背压和限流机制
+- [[03-任务队列]] — TaskQueue 接口的可插拔设计
+- [[00-索引]] — 返回文档总览