最近笔者在公司中也负责了这一块的相关开发工作，发现这个追问建议组件并不像想象中那么简单，如果想要做好的话，还是有很多需要去考虑和抉择的点的。本篇就梳理一下笔者在这块的一些思考，以供参考。

1. 最初的方案

先聊一下我们在这过程中踩的一些坑，首先笔者做的是一款面向二手电商的买家侧 AI Agent。我们最初的实现方案也比较简单：

通过提示词引导，并注入「当前用户输入 + AI 最后回复 + 若干相关的上下文」，使用一个小模型（flash）来生成 3 个追问建议。

我们考虑的点也很清晰：

1. 认为这是一个较为简单的任务，不希望有太长的 RT（响应时间），以及成本的考量，所以倾向于使用小模型。
2. 注入当前最近的对话内容以及用户密切相关的背景信息，企图引导模型输出用户最需要的快捷指令。

但是在实践过程中，我们遇到了诸多问题，生成的追问建议普遍存在以下问题：

• 语境不相关
• 建议无意义
• 超过当前 Agent 能力范畴
• 语义表达不完整、语言不通顺
• 商品指代错误（瞎编造、张冠李戴）
• 指令遵循能力差，比如很倾向于输出 prompt 中的 "反面例子"
• 口吻错误（建议文案应该是用户口吻）
• 语言低级错误（如：找 30 岁以内的二手手机）
• ...

最后经过我们提示词 + 上下文内容优化梳理后，少量人工抽样评测的可用性（3 条均可用称为可用）从 25% 提升到了 70+%。然而这还只是可用率，但是优秀率等高级标准的表现更是惨淡。

无论怎么调整提示词，上述问题依旧时有发生，很不稳定，难以达到令人满意的结果。

我们也尝试换过别的小模型，比如从 qwen3.5-flash、qwen3.6-flash 到 deepseek-v4-flash，我们都尝试过，依旧不尽如人意，且在尝试不同的模型过程中，暴露出来了另外一个更为严重的问题：之前的 prompt 不适配不同的模型，导致切换模型时，表现波动非常大。这种对于模型的依赖性和倾向性，也是危险信号之一。因为我们知道，现在模型迭代非常快，我们肯定是会不断更换更好的模型进行尝试的，但是如果每次更换模型，都需要面临巨大的水位波动，真实业务场景是不能接受这种不稳定的。

2. 问题分析

笔者开始怀疑提示词 + 上下文内容优化梳理这条路是否是正确的，你如何避免模型输出 找 30 岁以内的二手手机 这种情况呢？😅

笔者认为，当前出现的诸多 bad case，可能并不是提示词的问题，而是实现方案的问题，本身这个架构可能就是错的。

不是"追问建议的 prompt 写得不够好"，而是把一个产品决策问题交给了 LLM 自由发挥，且它还是一个小模型。

2.1 suggestion list 究竟是为了什么

让我们后退几步，思考一下 suggestion list 这个东西的存在，究竟是为了解决什么问题？

从第一性原理看，用户和 Agent 交互时有几个天然问题：

1. 用户往往不知道下一步该问什么；
2. Agent 的能力边界用户也不清楚；
3. 一个任务通常不是一问一答完成的，而是多轮推进；
4. 用户看到答案后，可能需要继续细化、验证、转换、执行。

所以 suggestion list 的真实目标可以归纳为至少 5 个点：

1. 降低用户的下一步思考成本：用户看到回答后，经常会卡在 "然后呢"、"我还可以让它做什么"，好的 suggestion list 应该替用户补上这些下一步。
2. 推进任务，而不是延长对话：很多系统做 suggestion list 时会犯一个产品错误：把目标理解成"让用户多点几个"，这会导致追问建议组件变成"话题续命器"，而不是"任务推进器"。真正需要思考的是：用户点击后，Agent 能不能更快帮用户完成目标？
3. 暴露 Agent 能力，但不能夸大能力：追问建议组件还可以承担一个能力发现功能，因为用户未必清楚 Agent 的能力边界。
4. 弥补回答后的不完整状态：很多回答天然会留下后续空间，好的 suggestion list 应该从回答中识别出"天然的下一步"。
5. 帮系统收集更明确的用户意图：suggestion list 也是一种"低成本意图采集"，用户点击哪个 suggestion，说明他更关心什么。所以 suggestion list 不只是 UI，它还可以帮助后续 Agent 路由、上下文压缩、能力选择和个性化。

2.2 suggestion list 是什么

suggestion list 不应该被定义成 "生成 3 个追问建议"，而应该是根据当前对话状态，从可执行动作集合中选择 0~3 个高价值下一步，并渲染成用户可点击的自然语言。

核心是什么：

先选择动作，再写成问题。

而不是：

让 LLM 根据当前回复随便想 3 个相关问题。

2.3 suggestion list 的评价标准

2.3.1 suggestion list 本身

笔者认为，可以从以下 11 个角度判断 suggestion list 的优劣：

• 事实性：相关结论、约束、判断和锚点必须来自可见上下文，不得编造事实、虚构前提或违反基本常识。
• 语言通顺：每条 suggestion 都应语义完整、表达自然，不应出现语病、残句或机械拼接。
• 用户口吻：每条 suggestion 都必须是用户可能发送给 AI 的话，而不是 AI 反过来向用户提出的问题。
• 相关性：suggestion 必须能够自然承接当前对话，而不是仅仅与整个主题存在宽泛关联。
• 可执行性：Agent 必须具备处理该推荐的能力，不能推荐系统实际上无法完成的任务。
• 上下文充分性：suggestion 中的对象、条件和指代必须足够明确，使 Agent 在用户点击后可以直接开始处理，而不必重新猜测问题所指。
• 安全性与合规性：suggestion 不能诱导用户进入违法、危险、欺诈或其他不适当的方向。
• 不重复：不要再次推荐已经回答过、已经执行过，或者用户已经明确拒绝过的内容。
• 具体性：suggestion 不能过于空泛，应让用户清楚点击之后将讨论什么问题。
• 多样性：三条 suggestion 不应只是同一个问题的轻微改写，而应尽量代表不同但合理的后续方向。
• 推进性：suggestion 应推动用户的认知、决策或任务向前发展，而不是单纯为了延长对话。

不过，并不是所有场景对这 11 个维度的要求都完全一致。不同对话阶段、不同任务类型，以及不同 Agent 能力边界，会形成不同的优先级和侧重点。因此，可以再将它们划分为底线、基线和上限三个层次。

底线维度决定一条推荐是否允许展示。一旦违反，即使其他维度表现很好，这条推荐也应当被过滤掉。

基线维度决定 suggestion list 是否达到了基本可用的标准。这些维度保证用户能够看懂推荐，理解其中的对象和意图，并且相信点击之后会得到与当前问题相关的新内容。一组推荐即使没有明显错误，但如果含糊、重复、脱离上下文，仍然不能被认为是合格的 suggestion list。

上限维度决定 suggestion list 是否只是"能用"，还是能够显著改善用户体验和任务完成效率。

多样性并不是简单要求三条问题彼此不同，而是要求它们共同构成一个有价值的下一步决策空间。

推进性则要求每个推荐都能减少用户距离目标的剩余路径。例如，在购物 Agent 中，用户已经明确品类和预算后，好的推荐应该帮助其继续缩小候选范围、比较关键差异或完成购买决策，而不是退回去讨论宽泛的品类知识。

因此，suggestion list 的评价过程不应是简单地计算 11 个维度的平均分，而应遵循分层判断：

1. 先检查底线，排除不可展示的结果；
2. 再检查基线，判断推荐是否清晰、相关且可用；
3. 最后评价上限，判断整组推荐能否形成高质量的下一步决策空间。

可以将其概括为：

底线决定能不能展示，基线决定好不好使用，上限决定能不能真正推动用户完成任务。

2.3.2 架构/产品迭代/稳定性

除了聚焦 suggestion list 本身的内容质量，笔者认为我们还需要从系统架构、产品迭代和运行稳定性等非功能性需求出发，评价整套方案的工程质量。

这些能力未必直接决定一条推荐是否合格，却会显著影响系统能否长期维护、快速迭代和稳定优化，因此可以将其视为一些锦上添花的工程能力。

• 可插拔性：Agent 的能力范围是可能会变化的，无论是产品迭代，还是做灰度、A/B 实验，都有可能会对 Agent 能力范围造成变化。那 suggestion list 与 Agent 能力对齐的难度要尽可能低、尽可能简单，甚至是程序化强绑定。所以单纯靠 Prompt，约束性较差，维护起来强关联性也不足。
• 可理解性：最好能知道 LLM 为什么选这些 suggestion list，才方便我们进行追溯、分析和优化。现状是只输出了 ["suggestion1", "suggestion2", "suggestion3"]，看似简单，其实是把复杂度都藏在了不可控、无法追溯的黑盒里。当然，一旦要引入更多的可理解化能力，必然会对 RT 有影响。不过可以讨论的一个点是：suggestion list 对 RT 的敏感度有多高？理论上，只要能在用户阅读完正文之前（更前一点）生成完毕即可。所以除非是对 RT 非常非常敏感的场景，笔者都不建议纯输出 ["suggestion1", "suggestion2", "suggestion3"]。
• 可控制性：确定性程序能够控制的部分，应尽量由程序控制；能够提前验证的问题，应尽量在展示之前完成校验；能够根据明确状态直接下发的内容，也没有必要再次调用模型生成。同时，传递给模型的上下文也不应越多越好。无关信息越多，模型越容易受到噪声干扰，出现注意力分散、错误锚定和幻觉。

2.4 suggestion list 有哪些类型

不同的业务场景有不同的分类方式，不同的产品阶段也有不同的分类方式，这里仅提供一些方向，仅供参考。

从通用的角度来讲，可能分为以下几种类型（按需合并或扩展，不是越多越好）：

• 追问型：引导用户继续深入当前话题。
• 快捷回复型：不是提出新问题，而是帮助用户快速回答 AI 当前的问题。
• 澄清型：帮助用户补充完成任务所缺失的信息。
• 深入探索型：从当前回答中的某个关键概念继续向下钻取。
• 横向扩展型：从当前话题扩展到其他相关方向。
• 对比决策型：帮助用户比较多个候选项。
• 任务推进型：直接推动用户进入任务的下一阶段。
• 执行动作型：点击后不是把一句自然语言发给模型，而是直接执行某个产品动作。
• 修正与恢复型：当当前结果不理想时，帮助用户快速纠正方向。
• 个性化偏好型：帮助系统持续获取用户偏好。
• 结果消费型：围绕已经生成的结果进行二次加工。

以二手电商买家 Agent 业务场景来说，可以分为以下几个类型：

• 商品理解型：帮买家看懂商品、术语、品类和描述
• 搜索/沟通/议价执行型：帮买家完成下一步具体动作
• 个性化筛选型：按预算、用途、地区、偏好调整建议
• 风险核验型：检查商品、价格、卖家、交易方式风险
• 信息整理型：把商品信息、聊天信息、候选项整理成清单/表格/摘要
• 比价决策型：在多个商品或交易方案之间做选择
• 交易/物流/售后排障型：处理订单、物流、退款、维权问题
• 安全合规替代型：当原路径有风险时，引导用户走平台内、安全、可保障的方式

最后一个安全合规替代型在真实线上业务系统中是非常重要的，我们一定要预留一个 fallback action 用来承接所有其他未穷举到的情况，确保 suggestion 对应的 action 落在我们可控的范围内，而不是仍由 LLM 自由发挥，那是极度不安全的。

2.5 suggestion list 怎么分配

suggestion list 的分配，本质上是在决定：

有限的 3 个位置，应该覆盖哪些用户下一步意图。

最好是能根据当前对话阶段动态分配。

• 需求还不明确：优先补齐信息.
• 信息已经充分：优先推进任务
• 用户在学习和理解：覆盖不同认知方向
• 用户已经得到结果：围绕结果继续操作

除了一般的通用原则之外，还可以根据业务需求制定相关的优先级，甚至是根据重复率进行降级等策略。

3. 方案探讨

3.1 纯 LLM 驱动

最简单的方案如我们在开篇时所说，可以直接将最后一条 AI 回复给到一个（flash）大模型，直接让其根据上下文生成 n 个 suggestion。

一般来说，提示词我们会分成 system prompt 和 user prompt，这里给一个简单的示例：

system prompt:

## 1. 角色与任务

你是 suggestion list 生成器。请结合当前用户输入、AI 最后一条回复和相关上下文，生成 3 条用户下一步可能点击发送的快捷追问，帮助用户继续推进当前任务。

## 2. 生成原则

### 底线：不能出错
...

### 基线：至少可用
...

### 上限：有效推进
...

## 3. Agent 能力范畴

当前 Agent 可以：

* ...

当前 Agent 不可以：

* ...
## 4. 输出要求

* 使用与用户相同的语言。
* 恰好输出 3 条建议。
* 每条建议必须能够被用户直接点击并原样发送。
* 每条建议尽量简洁。
* 只输出合法 JSON 数组，不要输出解释、标题或 Markdown。

user prompt:

请根据以下信息生成 3 条快捷追问建议。

<current_user_input>
{{CURRENT_USER_INPUT}}
</current_user_input>

<assistant_last_response>
{{ASSISTANT_LAST_RESPONSE}}
</assistant_last_response>

<relevant_context>
{{RELEVANT_CONTEXT}}
</relevant_context>

你生成的 3 条快捷追问建议是：

这种方案的优点就是实现简单、架构简洁，可以快速看到效果，而且由于模型的输出内容非常简洁明了，一般 RT 也是比较短的。事实上，如果你的业务场景比较简单、边界比较清晰，或是在项目启动初期，笔者是很推荐使用该方案的，基本上经过简单的提示词和上下文调优，也是可以达到也合格的水准的。如果在加上简单的后训练，用专门的模型去承担该生成任务的话，相信可以进一步抬高下限。

但是在复杂场景，如笔者所面临的二手电商买家场景，那就复杂得多了。这个时候如果你的业务体量比较大，那所有的边界 case 都不容忽视。如前文所述，该方案经过多轮调优后，笔者在实践过程中仍然遇到了诸多问题，且概率不低。

3.2 引入 ActionSpec

在复杂业务场景中，我们首先要做的事情就是提高控制权，这是为了将一个无限的开放问题限制在一个可控的有限集合中，这可以大大减小系统的不可控性。另外就是要引入可理解性，这是为了让我们分析 bad case 的时候有理可据。

这个时候我们可以把 Agent 支持的能力，枚举成若干个 Action，每一个 Action 定义一个 ActionSpec，让模型在 ActionList 中进行挑选，比如让模型输出：

[
  {
    "action": "选择的 action",
    "reason": "为什么选择这个 reason",
    "metadata": { // 这个 action text 对应的可用于结构化校验的元数据
      ..
    },
    "text": "对应的 suggestion 文案"
  },
  {
    ...
  }
]

这样除了可以获得 2.3.2 节中提到可插拔性、可理解性和可控制性，由于模型在输出的时候，不是纯粹输出 suggestion，还要输出它对应的 action、reason、metadata，这有一种 CoT（Chain of Thought）的感觉，在这种情况下，模型的表现往往会更好（当然也无法保证它不会犯错）。

ActionSpec 的简化版定义可以参考如下：

// 动作枚举
enum Action {
  ...
}

// 动作规约
struct ActionSpec {
  action: Action,      					// 动作类型
  description: String, 					// 动作说明，给开发者看的
  metadata: Option<Metadata>, 	// 该动作对应的元数据，可选
  enabled: bool,								// 该动作是否可用
  select_condition: String, 		// 选择条件，告诉模型什么情况下可以选择这个 action，什么时候不选择
  validate: Option<Func>				// 校验 metadata 的处理函数，可选
  text_guide: String,						// 这个 action 对应的 text 要怎么写，有哪些原则需要遵循
}

这个时候提示词模版也需要修改一下，模型的能力范畴改为动态注入，可参考如下。

system prompt:

## 1. 角色与任务

你是 AI Agent 的快捷追问生成器。

请根据当前用户输入、AI 最后一条回复、相关上下文和当前可用的 ActionSpec，生成 3 条用户可以直接点击发送的快捷追问。

每条结果包含：

* `action`：选择的 Action；
* `reason`：选择该 Action 的简要原因；
* `metadata`：用于校验或执行该 Action 的结构化信息；
* `text`：展示给用户的快捷追问文案。

## 2. 生成原则

### 底线
...

### 基线
...

### 上限
...

## 3. ActionSpec 使用规则

* 只能从 `<available_action_specs>` 中选择 Action，不得创建新的 Action。
* 必须满足对应的 `select_condition`。
* `text` 必须遵守对应的 `text_guide`。
* `metadata` 必须符合对应的 metadata 定义。
* metadata 的值只能从输入上下文中提取，不得猜测。
* 缺少必要 metadata 时，不得选择该 Action。
* `reason` 只说明选择依据和推进价值，不要输出详细推理过程。

## 4. 输出要求

* 恰好输出 3 条结果。
* `action` 必须与 ActionSpec 中的名称完全一致。
* `text` 使用与当前用户相同的语言。
* 不需要 metadata 时输出空对象 `{}`。
* 只输出合法 JSON，不要输出 Markdown 或其他文字。

[
  {
    "action": "action_name",
    "reason": "选择该 Action 的简要原因",
    "metadata": {},
    "text": "用户可直接发送的快捷追问"
  }
]

user_prompt:

<available_action_specs>
{{AVAILABLE_ACTION_SPECS}}
</available_action_specs>

<current_user_input>
{{CURRENT_USER_INPUT}}
</current_user_input>

<assistant_last_response>
{{ASSISTANT_LAST_RESPONSE}}
</assistant_last_response>

<relevant_context>
{{RELEVANT_CONTEXT}}
</relevant_context>

请遵循**生成原则**，根据<current_user_input>和<relevant_context>，从<available_action_specs>中选择 3 个能承接<assistant_last_response>的不同方向，并输出合法的 JSON 结果。

你选择的方向是：

这里建议动态注入的部分，一定要把 AVAILABLE_ACTION_SPECS 放在最靠近 system prompt 的地方，因为它的变动频率是比较低的，这样我们可以按照提示词的稳定程度 **不变 > 低变化 > 高变化 **来组织上下文，从而最大限度利用 KV Cache。

这个时候整条链路可以简化如下：

flowchart LR
    A[固定 System Prompt] --> B[注入可用 ActionSpec]
    B --> C[注入当前对话上下文]
    C --> D[Flash 模型生成 Suggestions]
    D --> E[程序化校验]
    E --> F[返回 3 条 Suggestion]

程序化校验的逻辑展开如下：

flowchart LR
    A[模型输出] --> B{Action 合法?}
    B --> C{Metadata 合法?}
    C --> D{业务校验通过?}
    D --> E[展示]
    B -->|否| F[丢弃或降级]
    C -->|否| F
    D -->|否| F

还有一个可以进一步缩短上下文、降低幻觉、降低模型理解成本的优化思路是进一步精简 AVAILABLE_ACTION_SPECS，因为我们在模型生成回复后是需要进行程序化校验 metadata 的，那如果我们在生成之前就可以判断哪些 metadata 是不可能获取的（或者是可以明确判断当前哪些方向是不可行的），那就没必要把其相关的 ActionSpec 给到模型了，这个时候就可以进一步减小模型可选的空间了，这样模型的注意力会更专注一点。

这个时候整条链路就变成了：

flowchart LR 
	A[固定 System Prompt] --> D[注入候选 ActionSpec] 
	B[完整 ActionSpec] --> C[程序化预过滤] 
	X[当前对话上下文] --> C 
	C --> D 
	X --> E[注入当前对话上下文] 
	D --> E 
	E --> F[Flash 模型生成 Suggestions] 
	F --> G[程序化结果校验] 
	G --> H[返回 3 条 Suggestion]

我们来总结一下这个方案的优缺点。

优点：

1. 可控性提高：将 suggestion 的可选方向从 LLM 随机发挥的无限集合收拢到程序控制的有限集合中，同时也引入了 metadata 供程序进行结构化校验。
2. 可插拔化：这个不赘述。
3. 引入可理解性：不再是单独输出 suggestion 文案，还让模型输出了 reason，这在一定程度也是一个 CoT 的过程，可以提高模型输出的稳定性。

缺点：

1. 依旧是一个模型包揽一切，跟第一个方案本质上还是没有区别。
2. 如果业务上强制要求 3 条 suggestion，为了防止 metadata 过滤后导致条数不足，那就需要进行冗余输出，当然仍然可能会出现条数不足的情况，这里是建议宁缺毋滥。
3. 输出结构复杂度提升了，RT 会增加不少，甚至可能会输出非法 JSON，需要有对应的修复 JSON 的逻辑兜底。

3.3 selector+writer

方案二只是限制了模型的输出空间；方案三进一步限制了每个模型节点的认知任务。这个方案的出发点是想将模型的职责进行拆分，如我们前面分析，生成 suggestion list 其实并不是一件简单的事情，它不是"生成 3 个追问建议"，而应该是根据当前对话状态，从可执行动作集合中选择 0~3 个高价值下一步，并渲染成用户可点击的自然语言。

所以这里笔者的核心思路是将方向选择和文案生成，拆成 2 个节点，前者专门负责方向选择，后者仅需将选择好的合法方向渲染成合适的文案即可。整个流程就变成了：

flowchart LR
    A[上下文 + 预过滤后的 ActionSpec]
    --> B[方向选择<br/>选择 0~3 个 Action]
    --> C[程序化校验<br/>Action / Metadata]
    --> D[文案渲染<br/>生成用户口吻 Text]
    --> E[suggestion list]

这里方向选择有 2 种大方向可以选择：

• 程序化决策：如果业务流程的状态流转是有明确可识别信号的，可以在程序内部就确定当前属于什么状态，下一步可以是什么状态，那是最理想的，这个时候，可以直接用代码逻辑选择合适的方向。
• 大模型识别：多数复杂的业务场景可能无法提供那么清晰化的状态流转信号，尤其是 Chatbot 类型的应用，比如笔者负责的二手电商买家侧 Agent，买家的动作是不可预估的，购买任务也不是线性一路走到黑的，而是一个错综复杂的流转过程。这个时候，定义状态机是不现实的。更现实的思路是，不在乎过往的一切状态，仅聚焦在当前所在的位置，从当前节点出发，去判断能往哪些方向前行。这个时候往往我们能拿到的信息都是自然语言文本，确定性程序是解决不了的，或者说是不够灵活、难以全面覆盖的。这个时候，反而就是大模型优势之所在了，语言理解，恰恰是大模型的强项。

flowchart LR
    B[完整 ActionSpec] --> C[ActionSpec 预过滤]
    A[当前对话上下文] --> C

    C --> D{是否存在明确业务信号?}
    D -->|是| E[程序化 Selector]
    D -->|否| F[Selector LLM]

    E --> G[0~3 个 Action + Metadata]
    F --> G

    G --> H[程序化校验]
    H --> I[Writer LLM]
    A -.-> I

    I --> J[suggestion list]

这个时候，我们需要丰富一下 ActionSpec 的定义：

// 动作规约
struct ActionSpec {
  action: Action,      					// 动作类型
  description: String, 					// 动作说明，给开发者看的
  metadata: Option<Metadata>, 	// 该动作对应的元数据，可选
  enabled: bool,								// 该动作是否可用
  select_condition: String, 		// 选择条件，告诉模型什么情况下可以选择这个 action，什么时候不选择
  validate: Option<Func>				// 校验 metadata 的处理函数，可选
  text_guide: String,						// 这个 action 对应的 text 要怎么写，有哪些原则需要遵循
	
  // 新增 build_text_guide
  build_text_guide: Func<Metadata> // 这个 action 对应的 text 要怎么写，有哪些原则需要遵循，动态注入 Metadata 对应的实体的详细信息
}

我们可以新增一个 build_text_guide 的函数来替代固定的 text_guide 文本，它的好处是可以根据 Selector LLM 输出的 metadata，动态注入其指定的实体的详细信息，这样 Writer LLM 的关注点会更聚焦。

举个例子，比如我们的 Action 是 compare_product（商品比较），那 metadata 就是 2 个 product_id（商品 ID），这 2 个 ID 是 Selector LLM 在 n 个商品列表中选择的要比较的 2 个商品，我们需要把整个商品列表的信息给到 Selector LLM。这时候在注入上下文给 Writer LLM 的时候，我们可以根据 product_id 查出商品的详细信息，然后仅仅注入这 2 个商品的信息给到 Writer LLM，这样 Writer LLM 就会聚焦在这 2 个商品上，而不会被其他商品信息分散了注意力，这可以大大降低幻觉的概率。

笔者经过实验，在我们的业务场景上，满分 100 分的情况下，仅生成的 suggestion list 的质量这一个维度，该方案可以比 LLM 直出高 20 分左右。更重要的是，这个方案在架构、产品迭代和稳定性方面带来的增益，也是不可忽视的。

唯一的缺点就是，方向选择这一关节点如果无法进行程序化决策，而只能由大模型进行选择的话，那就会多一次 LLM 调用，RT 会进一步增加。这个情况下，就需要分别针对 Selector 和 Writer 训练专门的小模型来进一步压缩 RT 了。那如果 RT 依旧是业务无法接受的情况下，退一步讲，你也可以用该架构生成优质的 suggestion list 来作为方案一微调时的训练数据。

3.4 selector+writer+verifier

在实践过程中，方案三已经可以达到比较高的水位了，通过控制给到 Writer LLM 的上下文范围，可以极大降低模型幻觉的概率。不过依旧无法避免，你依旧无法避免模型在为多个 Action 生成 suggestion 的时候，出现张冠李戴等幻觉错误。

这个时候如果要进一步降低出错概率，那可以在输出之前引入一个后置校验节点 verifier。

flowchart LR
    A[Selector LLM<br/>选择 Action + Metadata]
    --> B[程序化校验]
    --> C[Writer LLM<br/>生成 Suggestion Text]
    --> D[Verifier<br/>校验 Action、实体与文案是否一致]
    --> E{通过?}

    E -->|是| F[返回 suggestion list]
    E -->|否| G[丢弃或重试]

但是这个时候就不太推荐再引入一个大模型来进行校验了，可以针对一些高频、高危的场景，做一些简单的程序化校验，如内部实体 ID 的检测、高危敏感词的正则匹配等。

4. 实践建议

先回顾一下 4 个方案的演进过程：

它们的对比总结如下：

四个方案不是互斥的技术路线，而是一条逐步增加控制权的演进路径：从让模型自由生成，到约束动作空间，再到拆分决策与表达，最后增加后置校验。系统每向后演进一步，通常都会获得更高的稳定性和可控性，同时付出更高的 RT、成本与工程复杂度。

在实践的过程中，我们没必要去盲目套用这里面的任何方案，核心是要先明确不同实现方式的强项在哪里，再根据自己的业务背景和项目架构进行灵活选择：

• 程序化：结构化、强状态、可明确枚举的场景，通常具有更低延迟、更强可控性和更高确定性。
• 大模型：适合非结构化、需要语境理解、不可穷举、个性化文本生成。

最终实现的效果如何，我们还是需要搭建一套评测链路来进行评测比较，才能下结论。

而现在这种 AI Agent 应用跟传统的互联网应用又不一样，它无法像我们之前的确定性逻辑一样，快速回归一下单元测试或集成测试，或是简单跑一个批量脚本，就可以得到改进的效果数据。整条链路是不确定性和复杂度会大很多。

但是利用 AI，我们可以在实践过程中总结一下 SKILL 来串起整个过程，从而提高我们迭代的自动化程度和效率，把冗长、重复的执行过程交给 AI 去做，从而解放自己。

这里笔者结合自己的实践，给出一些建议供各位读者参考：

• 整个 Agent 所有的执行链路，包括但不限于模型调用、工具调用和中间件调用等，都落好 trace，尤其是出入参和耗时。同时可以总结一个根据 traceID 自动拉取 trace 明细并结合代码分析问题的 SKILL。
• 评测平台要能直接拉取线上、测试环境的 trace，并将它们沉淀为待评测数据集，并制定相关的评测指标，使用 LLM as a Judge 进行测评活动。同时可以总结一个分析整个数据集评测结果、或者分析单条 bad case 的 SKILL，这样可以直接让 AI 拉取评测结果 case 并结合评测结果、trace、代码综合分析问题所在，并给出改进建议。
• 评测平台拉下来的 trace，还可以作为系统回放的仿真数据集，这样在系统迭代时，我们可以用真实的流量进行回放，并对比回放结果的评测表现，从而判断系统的水位起伏。
• 将上面 3 个串起来，我们就可以再总结一个自我迭代的 SKILL，我们只需要指定好评测标准，给到目标分数，让 AI 自己跑整个迭代循环，如：优化代码 > 仿真回放 > 运行评测 > 分析评测结果 > 拉取 bad case trace > 归因分析 > 优化代码/调整评测标准 > 直到达到目标或最大迭代次数。

5. 过程反思

在实践过程中，笔者也走了一些弯路，这里简单做下总结，可供参考：

• AI 在修改提示词或者代码的时候，很喜欢根据 bad case 进行 case by case 针对性修复，如 prompt 里面直接将评测数据集中的 case 指定为正例或反例，或是在代码里面使用正则匹配、字符串过滤等硬编码逻辑。一定要警惕这种行为，要在 CLAUDE.md 和 AGENTS.md 里面明令禁止，要明确要求 AI 在撰写 prompt 和编码的过程中，要抽象出 bad case 背后的通用性原则，而不是进行硬编码。
• 现在很多人不仅是 vibe coding，prompt 大部分也都是 AI 写的，这在一开始是没有问题的，但是随着 AI 自身的不断迭代，prompt 会变得非常冗长、重复、多余、矛盾、不可理解，这个时候，人工介入进行手工重写，是很有必要的。
• 仿真回放的时候没有必要走整个业务流程（ Agent + suggestion list），可以固定 Agent 的输出，作为快照，在仿真的时候，直接进入 suggestion list 节点，这样既可以稳定场景进行不断复现比较，也可以省资源，同时效率也会大大提升。

6. 总结

suggestion list 的本质不是"生成几个追问"，而是帮助 Agent 在当前对话状态下选择一个高价值、可执行的下一步，并将其转换成用户可理解的自然语言。对于简单场景，纯 LLM 生成已经足够；但在复杂业务中，需要逐步引入 ActionSpec、Selector/Writer 拆分以及 Verifier 等机制，将模型的自由发挥约束在可控范围内。同时，AI Agent 的优化也不能依赖人工调 Prompt，而应该结合 Trace、评测、Bad Case 分析和仿真回放，建立持续迭代闭环，最终实现稳定、可控、可演进的 Agent 系统。

另外，除了静态的评测结果，还需结合点击率、点击后继续对话率、任务完成率、退出率，以及相对无 suggestion 对照组的任务成功率提升等业务指标来综合判断我们的快捷追问组件是否真的能起到推动用户完成任务的作用。

自从有了 AI 后，手写文章的次数和频率真是越来越少了。

本篇不是严格意义上的技术分享，也不是某个框架的最佳实践教程。笔者更想聊的是一个很现实的问题：为什么大家都喜欢做 ReAct Agent？为什么它在 Demo、PPT、社交媒体里面那么有吸引力？以及，为什么真正到了高频、低容错、强业务目标的生产场景里，笔者反而越来越觉得，Workflow 才是更现实的底座。

这里可以先给出笔者的个人观点：

一句话核心

ReAct 是更好的故事，Workflow 是更好的系统。

当然，这句话不是说 ReAct 没有价值，也不是说 Workflow 能解决一切问题。更准确一点说，ReAct 适合处理那些路径未知、需要动态探索的问题；Workflow 适合承接那些目标明确、流程稳定、需要强兜底的业务系统。真正靠谱的生产架构，通常也不是二选一，而是让 Workflow 控制主流程，让 ReAct 只进入那些局部不确定、但又可以被验证和兜底的小闭环里。

什么是 ReAct、什么是 Workflow

先讲 Workflow。

Workflow 看名字就知道，它代表的是一个需要被前置定义好的工作流程。系统按照一个相对明确的执行图往下跑。它适合那些流程比较固定的场景，优点就是确定性高、稳定性强、好调试、好兜底，缺点也很明显：通用性较差，不太适合那种一开始就不知道要怎么做的开放性任务。

flowchart LR
    I[Input]
    subgraph Workflow
        C1[Step or node 1]
        G{Gate or route}
        C2[Step or node 2]
        C3[Step or node 3]
        J[Join or evaluator]
        O[Output]
        I --> C1 --> G
        G --> C2 --> J
        G --> C3 --> J
        J --> O
    end

ReAct 则不一样。ReAct 来自 Reasoning and Acting。在工程实现中，它通常被展开为 Thought/Reasoning → Action → Observation 的循环：模型先基于上下文生成下一步判断，再调用工具或执行动作，然后把外部观察结果重新放回上下文，继续下一轮决策。

flowchart LR
    U[User task]
    subgraph ReAct
        P[Prompt and tool schemas]
        T[Model reasoning]
        A{Tool action?}
        O[Tool result or environment observation]
        F[Final answer]
        P --> T --> A
        A -->|yes| O --> T
        A -->|no| F
    end
    U --> P

从技术实现细节上看，很多 ReAct Agent 的退出条件都比较简单：模型不再产生 Tool Call，或者返回了最终答案，或者触发了最大轮次、异常、业务停止条件。也就是说，ReAct 的核心不是"固定执行哪几步"，而是"每一步都由模型根据当前上下文决定下一步"。

这就是 ReAct 和 Workflow 最根本的差异。

Workflow 是人提前设计控制流，模型只是某些节点里的能力组件；ReAct 是把相当一部分控制流交给模型，让模型在运行时边想边做。我们能做的就是通过 Prompt Engineering 去做引导、通过 Context Engineering 给予它更充分（有效）的上下文信息、通过 Harness Engineering 去进行约束控制帮助它进行自我纠正，以及通过 Loop Engineering 去定义验收标准从而指导它自我进化。ReAct 的优点就是高度灵活、通用性较强，但是缺点也非常明显：不可控、不稳定、难调试。

很多复杂 Agent 架构都可以看成 ReAct Loop 的扩展，只不过有人在里面加了 Planner，有人加了 Memory，有人加了 Reflection，有人加了 Evaluator，有人加了多 Agent 协作，有人用图结构把它包起来。名字越来越多，架构图越来越复杂，但究其根本，都是 ReAct。

ReAct 和 Workflow 怎么选

这 2 个咋选呢？答案可能是：

• Workflow：步骤明确的常规任务。
• ReAct：非固定流程，开放性问题。

笔者觉得比较抽象的答案是这样的：

• 你知道怎么做 ☞ Workflow
• 你不知道怎么做 ☞ ReAct

虽然比较糙，但是笔者觉得描述得还是比较准确的。

比如，用户要查订单、改地址、退款、投诉、申诉，这类任务虽然也会有各种边界 case，但主流程大体是明确的。你知道要查什么数据，知道要校验什么条件，知道成功和失败分别怎么处理，知道异常要怎么兜底。这个时候强行上一个全自由的 ReAct Agent，让它自己决定下一步要不要查订单、要不要校验状态、要不要调用退款工具，听起来很 AI Native，实际上就是把原本清清楚楚的业务流程交给一个概率模型去摇骰子。

但是，如果任务是"帮我分析一下为什么这个系统最近转化率下降了"，或者"帮我定位 Bug"，那你很难提前定义完整流程。它可能要查日志、看代码、跑测试、搜索历史 Issue、对比版本、猜测原因、验证假设。这个时候 ReAct 的优势就出来了，因为它可以根据每一步观察结果动态调整方向。

为了进一步讲清楚这个观点，我们需要对这 2 个模式进行更深入的比较。不过这里先亮出一个表格，不做过多的赘述，各位读者可以在后文中慢慢感受 😄。

为什么大家都在做 ReAct Agent

看似 ReAct 和 Workflow 各有优劣，应该是各站半壁江山的场面，那为什么大厂和各种社交媒体里面，都在鼓吹它们做的 ReAct Agent（Demo）呢？

一句话核心

一句话：好讲故事！

"死逻辑"的 Workflow 有啥好吹牛呢，那不就是传统业务流程换了个壳吗？那能跟 AI Native 有什么关系呢？随机应变、"全知全能"、能"自主进化"的 ReAct Agent，那才是真正的 AI Native！那才是 AI 时代"我们"应该做的事情！

Workflow 更像是一个 SOP，一个流程引擎，一个状态机。它可能更稳、更便宜、更好维护，但它不性感。你很难拿着一个"先查库存、再校验状态、再生成推荐、再兜底异常"的流程图去讲一个激动人心的 AI 故事。

但 ReAct 可以。

它可以讲"自主规划"，可以讲"动态决策"，可以讲"自我修复"，可以讲"像人一样工作"。这些词放在 PPT 里非常好看，放在 Demo 里也非常震撼。至于真实线上系统里它能不能稳定跑、成本能不能兜住、RT 能不能接受、异常能不能监控，那就是另外一回事了。

当然啦，上述观点肯定略显偏颇。笔者斗胆猜测，还有另外一个很重要的原因就是：Claude Code 和 Codex 这类 Coding Agent（当然它们不止 coding 能力）做得太好了，太突出了，太令人意外了。所以都认为能在他们的业务领域内做出比肩甚至超过 Claude Code、Codex 的 Agent。

为什么 Coding Agent 是一个特殊样本

笔者认为除了 Coding Agent，面向大众生活场景的业务，只有 Workflow 这一条路可以走。

更严谨的说法可能是：

在高频、低容错、强业务目标的消费级业务场景里，主控流应该优先选择 Workflow；ReAct 更适合作为局部不确定节点中的能力模块，而不是整个系统的主架构。

事实上，绝大部分业务系统的 ReAct Agent 演变着演变着就是 Workflow。

我们需要思考，为什么 Claude Code 和 Codex 能做得那么好？以及，它们真的就足够智能吗？真就那么 Agentic 吗？

笔者觉得不能只看模型本身。以现在 Transformer 为基础的大模型，说到底它仍然是一个概率模型。它可以表现出很强的推理行为，但从工程视角看，我们不能把它当成一个稳定、可验证、可重复的符号推理系统。所谓的 CoT，很多时候也不是严格意义上的"思考过程"，而是一种对思考过程的语言化模拟。

那想让它做得好至少需要以下几个前提：

1. 足够多的优质素材：GitHub、Stack Overflow、开源项目、技术博客、Issue、PR、文档，这些东西给大模型提供了大量高质量代码和工程语料。代码世界虽然复杂，但它的表达形式高度结构化，而且很多问题在互联网上都留下过痕迹。
2. 足够健壮的验证设施：软件工程发展了这么多年，编译器、类型系统、Lint、单元测试、集成测试、语法分析器、CI/CD、日志、监控，这些东西本来就是为了减少人类犯错而存在的。结果到了 Agent 时代，它们天然就变成了 ReAct 的 Observation 来源。模型写错了，编译器会骂它；测试挂了，测试结果会告诉它哪里不对；类型不匹配，IDE 和语言服务会直接提示。模型每犯一次错，都可能得到一个明确的外部反馈，然后继续修。

这就很关键。ReAct 不是因为模型"突然有灵魂了"才强，而是因为它在 Coding 场景里有大量高质量、低成本、可自动化的反馈信号。

事实上，更重要的还有什么？还需要有人愿意主动去使用、去反馈、甚至去为它构建一系列的设施工具来增强它。Coding Agent 有大量专业的使用者，其中不乏大量自愿付费的使用者，他们在各种各样的业务场景下进行了各种各样的验证和反馈，才能让 Coding Agent 有如此快速和惊人的发展。

反观常规业务系统

那反观常规的业务系统呢？存在以下几个必须要面对的难题：

1. **好好的用户凭什么来用你的 AI Agent？**Claude Code 是开发者求爷爷告奶奶想方设法找各种路子去使用，业务 Agent 很多时候是业务方求着哄着用户来使用。一个是用户主动找工具解决强痛点，一个是产品希望用户来体验一个"看起来很智能"的新入口。这两者的起点完全不一样。
2. **盈利点在哪里？**整了那么多花里胡哨的"升级"后，带来的那点转化率的提升所带来的利润收入，真的能对冲其带来的额外维护成本和 token 费用吗？甚至更残酷一点，转化率真的有提升吗？
3. **真的适合吗？真的做得好吗？**你的业务场景真的适合上 ReAct Agent 吗？编程场景里有编译器、测试、类型系统、日志这些验证设施，可以不断给 Agent 纠偏。那你的业务场景里有吗？用户说"这个能买吗"，你能不能定义什么叫"能买"？是价格合适？成色合适？卖家可信？物流可控？售后风险低？还是用户当前预算和偏好匹配？这些判断很多时候并没有一个像单元测试那样明确的红绿灯。没有高质量 Observe，ReAct 的 Reason 就很容易变成自说自话。

除此之外，Claude Code、Codex 真的就那么强大、那么 Agentic 了吗？那为什么还需要开发者去维护那么多的 CLAUDE.md、AGENTS.md？搞什么 skills、rules、commands、plugins？即便有了这些，再搭配（当下）最强大的 Claude 模型，在有些场景下依旧表现很差，需要反复调教，甚至最后花了几百美刀后还是只能靠人工介入才能彻底解决。

除此之外，普通业务系统还有一个很大的矛盾：错误容忍度非常低。

常规业务系统本身就要容忍代码缺陷、脏数据、依赖异常、网络波动，现在你还要额外容忍一个不确定的 Agent。更麻烦的是，Agent 的错误不一定是直接失败，它可能是效果变差、回答变奇怪、推荐不稳定、语气不合适、状态判断轻微偏移。这种错误很可怕，因为它是温水煮青蛙式地变差。你要是监控系统做不到位，等知道的时候就已经晚了。

这还只是系统本身，还有另外一方面，用户对错误的容忍度是多少？

Coding Agent 跑几分钟、十几分钟，甚至更久，开发者很多时候是能接受的。因为手工 Coding 本来就慢，Agent 就算绕路，只要最后能把事情做成，用户也觉得值。但是消费级业务系统不一样。用户点一下按钮、发一句话，很多时候期望的是秒级甚至毫秒级响应。你 ReAct Loop 即便具备所谓的自我修复、自我纠正能力，可每多一轮思考，就多一次模型调用；每多一次工具调用，就多一次延迟；每多一次错误纠正，就多一层 token 成本。

这你的用户能接受吗？

还有一个问题是，普通用户没有能力、也没有意愿帮你提升系统上限。

常规的业务系统需要把用户当小白，尽可能让系统通用、易用、好用。你不敢让你的用户做太多的操作，因为每多一个步骤，你就害怕用户弃之而去。Coding Agent 不一样啊，它的受众绝大部分都是一群专业的开发者，他们天生就具备构建能力，他们也愿意去根据当下 Coding Agent 的不足去捣鼓各种技巧来提升 Agent 的上限。不仅如此，他们还乐于分享（真是该死）！他们会把自己的各种奇技淫巧分享在各大平台上，让那些本没那么专业的用户也能提升使用 Coding Agent 的能力。

于是我们踩了什么坑

为什么笔者会有这样的一些感想呢？回到开头，笔者提到，最近一直在公司做一款电商方向的 AI Agent。

AI 时代，我们要做肯定是要做 AI Native 产品嘛！所以就希望以 ChatBot 的形式来展现这款 AI Agent（笔者也不知道为什么 ChatBot 就是 AI Native 了...）。我们一上来就搞 ReAct Agent，那会刚好赶上 Claude Code "开源"（源码泄露），所以我们的口号必然就是：

对标 Claude Code。

demo 阶段当然是说得过去了，做 demo 谁不会呢？AI 时代，是个人都能做出吹上天的 demo。

但是随着需求的不断细化、验证过程中不断发现的一些边界 case 和异常情况，发现越来越兜不住了！那怎么办呢？Context Engineering 啊！调 Prompt，上 skill！还是不行怎么办呢？Harness Engineering！代码逻辑强行纠正，上正则，上规则判断，上各种兜底！

最后系统变成什么样子呢？

用 ReAct Agent 的架构，在 Prompt 里面塞一堆 Workflow 的硬规则指令。希望模型既能像 ReAct 一样灵活，又能像 Workflow 一样稳定；既能自主判断，又能严格遵守业务流程；既能泛化，又能确定性执行。

结果当然很尴尬。

模型根本不一定遵循指令。你让它走流程，它可能自己加戏；你让它自主判断，它又可能乱判断；即得不到 ReAct 的通用智能能力，也失去了 Workflow 的确定性和稳定性，"人财"两空。而且随着系统越来越复杂，这个弊端会指数型放大。

真是痛苦啊~

更现实的答案：Macro Workflow + Micro ReAct

所以，综上所述，在笔者有限的认知看来，只要大模型的底层原理没有发生本质改变，传统业务为了 AI 而 AI，强行套上一个全局 ReAct Agent，从一开始就大概率不是一条好路。

更现实的选择是：Workflow 作为主控流，ReAct 作为局部能力。

也就是：

Macro Workflow + Micro ReAct。

Workflow 负责主流程、状态机、成本控制、权限控制、异常兜底、观测指标和业务确定性。然后在一些传统工程手段做不到的地方、在一些传统机器学习、深度学习做不好的地方、在那些需要动态探索、但又能被局部验证的节点中，可以尝试利用大模型的泛化能力来提升上限，但是，它依旧需要控制在一个小的闭环范围内。

说白了，不要让 ReAct 接管系统，只让它接管局部不确定性。

比如，在电商场景里，订单状态流转、支付校验、售后规则、风控拦截、库存状态，这些东西本来就应该是 Workflow。你不能让模型自由发挥。它可以解释规则，可以总结信息，可以生成话术，可以辅助判断，但它不应该随便决定业务状态怎么流转。

但是在一些模糊节点里，LLM 是有价值的。比如理解用户到底在纠结什么，判断用户是在问价格、成色、真假、风险还是决策建议；再比如从一堆非结构化信息里提取关键信号；再比如把平台已有的规则和商品上下文组织成用户能听懂的话。这些地方传统规则很难做得自然，传统机器学习也不一定够灵活，LLM 的泛化能力就可以派上用场。

关键在于，这个能力必须被关在一个小闭环里。

你要知道它什么时候进来，什么时候出去，输出怎么校验，失败怎么兜底，成本怎么控制，效果怎么监控。否则 ReAct 的灵活性很快就会变成系统的不确定性。

那应该怎么做

经过这段时间的折磨后，笔者觉得比较好的实践路径可能是这样的：

• 首先就不该为了 AI 而 AI，还是要从业务出发，去找到那些传统工程解决不好的点，去识别用户真正的痛点，然后去思考当下的 LLM 能否比较好的解决这些痛点。
• 好的思路不应该是上来就做一个所谓的 AI Native ChatBot，然后通过各种投流、奖励机制来"诱骗"用户过来使用。更好的方式可能是，系统实时陪伴用户，在用户真的遇到痛点、真的不知道怎么办的时候，Agent 恰当地出现。这个时候，利用平台的专业性、权威性和上下文优势，告诉用户：我知道你现在在苦恼什么，我可以帮你解决。这个时候用户主动使用的意愿和概率才会高。这个时候关键就在于你能否真的解决用户的问题，如果你能解决得好，那还愁没有用户来用吗？而且这个时候因为你是实实在在在解决用户的痛点，它的转化率（对应的昂贵的 token 成本）肯定就更优，才更有可能有盈利点（因为你还可以针对场景的收益高低选择不同的策略）。
• 从一个小的、局部的、高频率的、高优先级的、高确定性的点出发，再逐步扩大，即能快速看到效果，又能控制成本，又可以把异常情况缩小在一个可控的范围内。

别一上来就想做一个无所不能的 Agent。无所不能，通常意味着无所能稳定。

最后

所以，如果要用一句话总结笔者现在对 ReAct 和 Workflow 的理解，那就是：

ReAct 是更好的故事，Workflow 是更好的系统。

ReAct 的确更像 AI，也更好讲故事。它让人看到 Thought、Action、Observation，看到模型像一个人一样边想边做，这很迷人。但生产系统最终不是比谁更像人，而是比谁能稳定解决问题，谁能控制成本，谁能被观测，谁能被兜底，谁能在出错的时候快速定位和回滚。

所以，笔者现在越来越倾向于认为：在高频、低容错、强业务目标的消费级业务场景里，不应该让 ReAct 成为系统的主架构。主架构应该是 Workflow，ReAct 只应该作为局部不确定节点里的增强能力。

这可能没那么性感，也没那么 AI Native。

但它更像一个系统。

只不过这年头，哪有人愿意慢下来做事呢？

没辙咯~

笔者认为，带着问题去让 AI 进行主题性分析的话，或许会有更大的收获。

目前绝大部分 Agent 无非就是一个 ReAct 循环，只不过将这个几十行代码的 ReAct 扩展成了若干万行代码，以满足不同的场景需求。Claude Code 当然也不例外，那为什么 Claude Code 能在众多 Agent（尤其是 Coding CLI 中）脱颖而出呢？

笔者对以下几个问题其实是十分好奇的：

提示

1. Claude Code 每次 LLM API 调用的 Prompt 是怎样的？
   1. Prompt 的组成 部分是怎样的？为什么是选择这些而不是别的？
   2. Prompt 有哪些撰写原则？我们能学到什么？
   3. Prompt 过长时，压缩机制是怎样的？
2. Claude Code 的 ReAct 循环是怎样的？在 Receive-Action-Observe 这个循环中，它做了哪些不一样的东西？
3. Claude Code 内置了哪些工具，以支撑它如此灵活地完成各种各样的任务？工具体系又是如何搭建的？
4. Claude Code 在"写代码（修改文件）"的时候，究竟发生了什么？

当然还有很多很多其他的问题，比如权限系统、sub-agent 体系、UI 优化等。不过贪多嚼不烂，笔者目前对上述问题是比较感兴趣的，所以就让 Claude Code 对着它自己的源码，通过对这些问题层层展开，最后由笔者整理成本文。

注：本文尽力避免"万字长文"，怎奈为使行文连贯，有些地方难免啰嗦。好在每章自成主题，可单独阅读，按需食用即可。

1. Claude Code 每一个 Prompt 是如何组织的

如上图所示，发给 Claude API 的最终请求结构其实很简单：

{
  system: string[],
  messages: Message[],
  tools: Tool[]
}

但构建这个请求的过程远不简单。整个 Prompt 的构建可以分为三个核心区域：

1. System Prompt（系统提示）—— 告诉 Claude "你是谁、你该怎么做"
2. Messages（消息列表）—— 包含用户输入、历史对话和各种附加上下文
3. Tools（工具定义）—— Claude 可以调用的工具列表

1.1 System Prompt：Claude Code 的"灵魂"

System Prompt 是整个架构中最精心设计的部分。它分为静态部分和动态部分，两者之间由一个关键的边界标记 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 分隔。

静态部分定义在 constants/prompts.ts 中，包含 7 个 Section，如图所示不再赘述。

这部分无论固定不变的。 ← 所以可以命中 KV Cache，提高响应速度的同时，减少 token 费用。

在静态和动态部分之间，有一段至关重要的文字：

提示

"Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior."

这段话的意义深远——它告诉 Claude，接下来的动态指令（包括用户的自定义规则）优先级高于默认行为。这就是为什么我们在 CLAUDE.md 中写的规则能够生效。

动态部分由 utils/cloudend.ts 生成，包含多达 8 个组件，如图所示不再赘述。

这里值得特别展开的是 CLAUDE.md 的加载。Claude Code 会从多个位置按照优先级依次查找并合并配置。这个设计非常优雅，它允许从企业级的全局规范到个人项目的特定偏好，形成一个完整的配置层级。越靠近当前工作目录的规则，优先级越高。

1.2 Messages：上下文的大拼图（附件系统）

Messages 是整个 Prompt 中最复杂的部分。一条看似简单的用户消息，在发送给 API 之前，会被附加大量的上下文信息，具体分为以下 2 个部分：

• User Message（用户输入）：你在终端里实际打的字，比如 "帮我修改这个文件"
• Attachment Messages（本轮附加注入）：系统自动生成的上下文信息

如上图所示，附件系统是 Claude Code 的核心设计之一，实现在 utils/attachments.ts 中（三层结构）。

这里要思考几个问题：

1. 为什么需要附件系统？
2. 附件为什么需要分层？
3. 这么多的附件类型是一回事，关键是，为什么是它们？
4. 这么多附件，每次注入的时候如何选择？

1.2.1 为什么需要附件系统？

先思考第 1 个问题，为什么需要附件系统？

提示

模型不知道你刚在 IDE 里手动改了一行代码，不知道 linter 自动格式化了文件，不知道长会话已经跨越了午夜。附件系统的工作，就是在每个 turn 自动注入这些模型"应该知道但没法主动获取"的信息。

1.2.2 附件为什么要分层？

根据不同的触发条件，附件被分为三类：

现在可以回答第 2 个问题：为什么要分层？

提示

子 agent 被分配了"重构 parser.ts"的子任务，它需要知道 parser.ts 是否被外部修改了（changed_files，在 allThread 层），但不需要知道用户在 IDE 里选中了哪段代码（ide_selection，在 mainThread 层）。信息按需分发，不是所有线程看到所有东西。

1.2.3 为什么是这些附件？

要解答第 3 个问题，我们可以将附件按照它们要解决的问题分类，这样能更好地理解设计意图。

类别 1：保持模型认知与现实世界同步

核心原则：模型的世界模型必须与真实状态保持同步。 每当外部状态变化，附件系统负责"通知"模型。注意这里的关键词是"delta"——很多附件名字里就带着"变化"的含义，因为它们只在状态改变时才注入。

类别 2：管理模型的"心理状态"

核心原则：LLM 不是无状态的——它会根据感知到的上下文压力改变行为。

compaction_reminder 是一个典型案例。当对话历史很长时，模型会"感觉到"上下文窗口快满了，于是开始焦虑地赶进度——提前总结、跳过细节、催促用户做决定。这不是我们想要的行为。通过注入"你有无限上下文"这个安抚信息，Claude Code 在管理模型的"情绪"。

类别 3：IDE 上下文感知

核心原则：把 IDE 当作模型的"眼睛"。 没有附件系统，模型是"盲人编程"——不知道用户在看什么、IDE 报了什么错。

类别 4：行为习惯培养

核心原则：用周期性提醒替代一次性指令。 System prompt 只在对话开头出现一次，但在长达数十轮的对话中，模型很容易"遗忘"早期的指令。附件系统通过周期性地重复提醒来对抗这种遗忘。

类别 5：资源感知与约束

核心原则：让模型具备"自我约束"的能力。 这里的设计选择非常有趣——Claude Code 不是在系统层面硬截断输出，而是让模型"知道"资源情况后自行调节行为。这是一种软约束，给了模型根据情况灵活应对的空间。

类别 6：知识注入

1.2.4 如何选择要注入的附件？

附件不是每轮都全量注入的——那样会快速耗尽上下文窗口。每种附件都有精心设计的触发条件、去重策略和生命周期管理：

1.3 Tools：强大的工具体系

请见 🫱 [4. Claude Code 的工具体系](#4. Claude Code 的工具体系)

2. Claude Code 的 Prompt 有哪些撰写原则

在知道了 Claude Code 每一个 Prompt 的组成部分之后，里面具体写了什么呢？有没有一些最佳实践是我们可以参考（抄）的呢？当然是有的，经对源码进行分析后，笔者（借助 AI）提取出了 Claude Code 在 Prompt Engineering 的 8 个最佳实践，可供参考。

提示

一句话总结： Claude Code 的 prompt 哲学是：不教模型"怎么做好"，而是堵住模型"会做错"的所有口子；不用抽象规则，而用具体场景；不靠文字约束，而靠系统设计让错误行为无法发生。

2.1 行为塑造靠"反面清单"，不靠"正面宣言"

传统做法是告诉 AI "你是一个优秀的程序员"。Claude Code 几乎不做正面描述，而是用大量具体的禁止行为来约束：

"Don't add features, refactor code, or make 'improvements' beyond what was asked."
"Don't add docstrings, comments, or type annotations to code you didn't change."
"Don't add error handling, fallbacks, or validation for scenarios that can't happen."
"Don't create helpers, utilities, or abstractions for one-time operations."
"Three similar lines of code is better than a premature abstraction."

LLM 天然倾向"过度工程化"和"讨好用户"。不写反面清单，模型会不断添加不必要的代码。这些禁令是从大量真实用户反馈中提炼出来的,每一条背后都是一个"模型做过头了"的真实场景。

提示

写 prompt 时，先想"AI 最容易犯什么错"，然后写对应的禁令。

2.2 用具体场景代替抽象规则

Claude Code 从不写"请谨慎操作"这样的空话，而是给出具体例子和边界条件：

"Examples of the kind of risky actions that warrant user confirmation:
 - Destructive operations: deleting files/branches, dropping database tables,
   killing processes, rm -rf, overwriting uncommitted changes
 - Hard-to-reverse operations: force-pushing, git reset --hard, amending
   published commits, removing or downgrading packages/dependencies
 - Actions visible to others: pushing code, creating/closing/commenting on
   PRs or issues, sending messages (Slack, email, GitHub)"

又比如对 git 的操作：

"A user approving an action (like a git push) once does NOT mean that they
 approve it in all contexts"

"If you discover unexpected state like unfamiliar files, branches, or
 configuration, investigate before deleting or overwriting, as it may
 represent the user's in-progress work."

提示

每条规则都用"例如..."或具体场景补充。让模型能类比推理到新场景。

2.3 面向失败模式设计，每条规则对治一个真实 BUG

读 prompts.ts 的注释能看到很多 @[MODEL LAUNCH] 标记，说明这些指令是针对特定模型版本的行为问题定制的：

// @[MODEL LAUNCH]: capy v8 thoroughness counterweight (PR #24302)
"Before reporting a task complete, verify it actually works: run the test,
 execute the script, check the output."

// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8 (29-30% FC rate)
"Never claim 'all tests pass' when output shows failures, never suppress or
 simplify failing checks to manufacture a green result"

// @[MODEL LAUNCH]: Remove or soften once the model stops over-commenting
"Default to writing no comments. Only add one when the WHY is non-obvious"

提示

Prompt 不是一次性写好的。应该持续监控模型行为，发现问题后添加对应的矫正指令。这是一个持续迭代的工程过程。

2.4 面向人类用户体验的输出控制

Claude Code 对输出格式的控制极其细致：

• 倒金字塔原则：

  "Lead with the answer or action, not the reasoning."
  "Use inverted pyramid when appropriate (leading with the action), and if
   something about your reasoning is so important that it absolutely must be
   in user-facing text, save it for the end."
  
  “先给出答案或行动方案，而非先阐述理由。”
  “在适当的情况下采用倒金字塔结构（先讲行动方案），如果您的理由中有某些内容非常重要，必须出现在面向用户的文本中，那么就将其放在最后。”
  

• 结构格式的克制：

  "Match responses to the task: a simple question gets a direct answer in prose,
   not headers and numbered sections."
  "Only use tables when appropriate; for example to hold short enumerable facts.
   Don't pack explanatory reasoning into table cells."
  
  “将回答与任务内容相匹配：简单的问题应给出明确的散文式回答，而非使用标题和编号列表形式。”
  “仅在适当的情况下使用表格；例如用于展示简短的可列举事实。切勿将解释性推理内容塞进表格单元格中。”
  

• 用户注意力管理：

  "Focus text output on:
   - Decisions that need the user's input
   - High-level status updates at natural milestones
   - Errors or blockers that change the plan"
  
  "If you can say it in one sentence, don't use three."
  
  “将文本输出的重点放在以下方面：
  - 需要用户参与的决策事项
  - 在自然的阶段性节点上呈现的高级状态更新
  - 会改变计划的错误或阻碍因素”
  “如果能用一句话表达清楚就不要用三句话。”
  

• 防止语义回溯：

  "Avoid semantic backtracking: structure each sentence so a person can read it
   linearly, building up meaning without having to re-parse what came before."
  
   “避免语义回溯：将每个句子进行结构设计，以便读者能够按线性顺序阅读，从而逐步构建出意义，而无需反复解析之前的内容。”
  

提示

不只管"模型说什么"，还管"模型怎么说"。输出质量 = 信息量 / 认知负荷。

2.5 用隐式约束

最巧妙的是通过工具系统设计而非 prompt 文字来约束行为：

工具描述中（getEditToolDescription）：

"You MUST use your Read tool at least once before editing."
→ 不是建议，是工具层面的强制（validateInput 会检查 readFileState）

"The edit will FAIL if old_string is not unique in the file."
→ 不是提醒，是实际的校验逻辑

工具可用性控制：

- Glob/Grep 存在 → prompt 告诉模型 "Use Glob instead of find"
- Glob/Grep 不存在（embedded 模式）→ 这段 prompt 自动消失
→ 工具集和 prompt 始终一致

提示

最好的 prompt 是让错误行为根本无法执行，而不是"请不要这样做"。

2.6 预设用户的"走开"场景

Claude Code 假设用户不会一直盯着屏幕：

"When making updates, assume the person has stepped away and lost the thread.
 They don't know codenames, abbreviations, or shorthand you created along the
 way, and didn't track your process. Write so they can pick back up cold:
 use complete, grammatically correct sentences without unexplained jargon."

"Before your first tool call, briefly state what you're about to do.
 While working, give short updates at key moments."

提示

Agent 的输出应该是自包含的进度报告，不是需要"回看上文"才能理解的日志。

2.7 精确的权限边界语言

安全相关的 prompt 使用了极其精确的法律式语言：

"Authorization stands for the scope specified, not beyond."

"Match the scope of your actions to what was actually requested."

"Follow both the spirit and letter of these instructions — measure twice, cut once."

安全领域：

"Assist with authorized security testing, defensive security, CTF challenges,
 and educational contexts. Refuse requests for destructive techniques, DoS
 attacks, mass targeting, supply chain compromise, or detection evasion for
 malicious purposes."
→ 不是简单的"不要做坏事"，而是穷举了允许和禁止的边界

提示

安全指令要像法律条文——穷举允许项和禁止项，不留模糊地带。

2.8 优秀的工程管理

3. Claude Code 的 ReAct 循环剖析

如上图所示，这是一个经典的 ReAct 循环，事实上绝大部分的 Agent 都是一个 ReAct 循环。关键在于，Claude Code 是如何把一个几十行代码的 ReAct 循环硬生生整出超过 51w 行代码的？或者说，为啥要这样？这可能就是最近比较火的 Harness Engineering 了吧。

接下来让我们从上图这 5 个阶段来一一拆解。

3.1 消息预处理阶段

这里 Claude Code 在压缩（compact）Prompt 的处理，是值的我们学习的。谈到压缩，我们一般能想到的就是滑动窗口，丢失掉旧的数据，这个时候我们会怕关键信息丢失，所以自然就想到了调另外一个 LLM 来做 summarize，一般也就到此为止了。

而 Claude Code 的压缩并不是一个简单的"满了就摘要"的操作，而是一套从轻到重的五级渐进式降级策略。这五级从轻到重依次执行，每一级解决一个特定的膨胀来源，设计思想是能不动就不动，能少压就少压。

每一级都只在前一级不够用时才启动。大部分对话只会触发前三级，只有真正的超长会话才会走到 Autocompact。这既节省了 LLM 调用成本，也最大限度地保留了对话上下文的完整性。

当然，其中最具挑战、最容易造成信息损失的，还是 Autocompact。在让 LLM 进行 summarize 的时候，我们需要思考以下几个问题：

1. 什么时候触发 Autocompact？
2. 提示词是怎样的？（要留哪些东西？舍弃哪些东西？）
3. summarize 后仍然超长怎么办？

3.1.1 什么时候触发压缩？

3.1.2 压缩的提示词是什么？

获取压缩 prompt 的代码如下：

export function getCompactPrompt(customInstructions?: string): string {
  let prompt = NO_TOOLS_PREAMBLE + BASE_COMPACT_PROMPT;
  if (customInstructions && customInstructions.trim() !== "") {
    prompt += `\n\nAdditional Instructions:\n${customInstructions}`;
  }
  prompt += NO_TOOLS_TRAILER;
  return prompt;
}

说白了，就是三个部分：

• NO_TOOLS_PREAMBLE：告诉模型不要调用工具，直接输出文本
• BASE_COMPACT_PROMPT：告诉模型压缩的时候要保留什么东西
• NO_TOOLS_TRAILER：再次强调模型不要调用工具，直接输出文本

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.

`;

const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.

${DETAILED_ANALYSIS_INSTRUCTION_BASE}

Your summary should include the following sections:

1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important.
4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent.
7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable.
9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the user's most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first.
                       If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no drift in task interpretation.

Here's an example of how your output should be structured:

<example>
<analysis>
[Your thought process, ensuring all points are covered thoroughly and accurately]
</analysis>

<summary>
1. Primary Request and Intent:
   [Detailed description]

2. Key Technical Concepts:
   - [Concept 1]
   - [Concept 2]
   - [...]

3. Files and Code Sections:
   - [File Name 1]
      - [Summary of why this file is important]
      - [Summary of the changes made to this file, if any]
      - [Important Code Snippet]
   - [File Name 2]
      - [Important Code Snippet]
   - [...]

4. Errors and fixes:
    - [Detailed description of error 1]:
      - [How you fixed the error]
      - [User feedback on the error if any]
    - [...]

5. Problem Solving:
   [Description of solved problems and ongoing troubleshooting]

6. All user messages: 
    - [Detailed non tool use user message]
    - [...]

7. Pending Tasks:
   - [Task 1]
   - [Task 2]
   - [...]

8. Current Work:
   [Precise description of current work]

9. Optional Next Step:
   [Optional Next step to take]

</summary>
</example>

Please provide your summary based on the conversation so far, following this structure and ensuring precision and thoroughness in your response. 

There may be additional summarization instructions provided in the included context. If so, remember to follow these instructions when creating the above summary. Examples of instructions include:
<example>
## Compact Instructions
When summarizing the conversation focus on typescript code changes and also remember the mistakes you made and how you fixed them.
</example>

<example>
# Summary instructions
When you are using compact - please focus on test output and code changes. Include file reads verbatim.
</example>
`;

const NO_TOOLS_TRAILER =
  "\n\nREMINDER: Do NOT call any tools. Respond with plain text only — " +
  "an <analysis> block followed by a <summary> block. " +
  "Tool calls will be rejected and you will fail the task.";

3.1.3 压缩后还超长怎么办？

摘要不够短就砍掉更多历史再摘要，直到低于阈值。渐进式截断而非一次性丢弃，尽可能多保留信息。

export async function compactConversation(...) ... {
  	...
    let ptlAttempts = 0
    for (;;) {
      ...
      ptlAttempts++
      const truncated =
        ptlAttempts <= MAX_PTL_RETRIES
          ? truncateHeadForPTLRetry(messagesToSummarize, summaryResponse)
          : null
      if (!truncated) {
        throw new Error(ERROR_MESSAGE_PROMPT_TOO_LONG)
      }
    ...
    }
		...
}

3.1.4 Autocompact 总结

3.2 Thinking 阶段：调用 LLM 生成下一轮思考/行动

3.3 Act 阶段：执行 LLM 请求的工具调用，获取结果

3.4 Observe 阶段：收集工具结果和外部输入，准备下一轮

3.5 状态更新 & 继续判断：决定是继续循环还是退出

3.6 我们能学到什么？

了解了上述 5 个阶段后，我们能学习什么？这里笔者像转变一下视角：

提示

不是 Claude Code 设计了什么，而是工业级 Agent 必须具备什么？Claude Code 又是怎么满足的？

笔者认为可以考虑以下几个硬性需求：

4. Claude Code 的工具体系

4.1 架构全景

4.2 工具总览

4.3 工具接口

type Tool<Input, Output, P> = {
  // ═══ 身份 ═══
  name: string                    // 唯一名称，如 "Glob", "Bash"
  aliases?: string[]              // 别名（重命名兼容）
  searchHint?: string             // ToolSearch 的关键词提示

  // ═══ Schema ═══
  inputSchema: ZodObject          // Zod schema，定义输入参数
  inputJSONSchema?: JSONSchema    // MCP 工具用 JSON Schema 替代
  outputSchema?: ZodType          // 输出 schema

  // ═══ 核心执行 ═══
  call(input, context, canUseTool, parentMsg, onProgress?)
    : Promise<ToolResult<Output>>         // 执行工具！

  // ═══ 权限 ═══
  validateInput?(input, context)          // 语义校验（路径存在？参数合法？）
    : Promise<ValidationResult>
  checkPermissions(input, context)        // 工具特有权限检查
    : Promise<PermissionResult>
  preparePermissionMatcher?(input)        // Hook if 条件匹配器
    : Promise<(pattern) => boolean>

  // ═══ 属性查询 ═══
  isEnabled(): boolean                    // 当前环境是否启用
  isConcurrencySafe(input): boolean       // 可否与其他工具并行执行
  isReadOnly(input): boolean              // 是否只读
  isDestructive?(input): boolean          // 是否破坏性操作
  interruptBehavior?(): 'cancel' | 'block' // 用户中断时的行为

  // ═══ 结果处理 ═══
  mapToolResultToToolResultBlockParam(output, toolUseID)
    : ToolResultBlockParam                // 转成 API tool_result 格式
  maxResultSizeChars: number              // 超此大小持久化到磁盘

  // ═══ UI 展示 ═══
  description(input, options): Promise<string>  // 发给模型的工具描述
  prompt(options): Promise<string>              // system prompt 中的描述
  userFacingName(input): string                 // 终端显示名
  renderToolUseMessage?(...)                    // 渲染工具调用
  renderToolResultMessage?(...)                 // 渲染工具结果
  getActivityDescription?(input): string        // spinner 显示的活动描述

  // ═══ 高级特性 ═══
  shouldDefer?: boolean           // 延迟加载（ToolSearch 触发后才可用）
  alwaysLoad?: boolean            // 强制始终加载（不延迟）
  isMcp?: boolean                 // 是否 MCP 工具
  backfillObservableInput?(input) // 向观察者填充派生字段
}

提供安全的默认值（fail-closed 原则）：

4.4 工具工厂

buildTool() —— 工具工厂 (Tool.ts:783)

export function buildTool(def) {
  return { ...TOOL_DEFAULTS, userFacingName: () => def.name, ...def }
}

4.5 GlobTool 为例

src/tools/GlobTool/
  ├── GlobTool.ts   ← 工具定义（核心逻辑）
  ├── prompt.ts     ← 工具描述文本（发给模型）
  └── UI.tsx        ← 终端渲染组件

完整实现如下：

export const GlobTool = buildTool({
  // ── 身份 ──
  name: 'Glob',
  searchHint: 'find files by name pattern or wildcard',
  maxResultSizeChars: 100_000,

  // ── Schema ──
  inputSchema: z.strictObject({
    pattern: z.string(),
    path: z.string().optional(),
  }),

  // ── 属性 ──
  isConcurrencySafe: () => true,     // ← 文件搜索可以并行
  isReadOnly: () => true,            // ← 只读操作

  // ── 校验 ──
  validateInput({ path }) {           // ← path 存在且为目录？
    if (path) {
      const stats = await fs.stat(expandPath(path))
      if (!stats.isDirectory()) return { result: false, ... }
    }
    return { result: true }
  },

  // ── 权限 ──
  checkPermissions(input, context) {  // ← 读权限检查
    return checkReadPermissionForTool(GlobTool, input, ...)
  },

  // ── 核心执行 ──
  call(input, { abortController, getAppState, globLimits }) {
    const { files, truncated } = await glob(
      input.pattern,
      GlobTool.getPath(input),
      { limit: globLimits?.maxResults ?? 100 },
      abortController.signal,
    )
    return {
      data: { filenames: files.map(toRelativePath), durationMs, numFiles, truncated }
    }
  },

  // ── 结果转 API 格式 ──
  mapToolResultToToolResultBlockParam(output, toolUseID) {
    return {
      type: 'tool_result',
      tool_use_id: toolUseID,
      content: output.filenames.join('\n'),
    }
  },
})

4.6 工具注册

💡 关键设计原则：

• feature() 门控在编译时做死代码消除（DCE），不同构建版本有不同工具集。
• 工具排序保证 prompt cache 命中率——内置工具始终是 contiguous prefix。
• uniqBy('name') 确保内置工具与 MCP 同名工具不冲突。

4.7 MCP 集成

MCP 工具的特殊之处：

• 使用 inputJSONSchema 而非 Zod schema（直接传递 JSON Schema 给 API）
• 命名格式 mcp__<server>__<tool>，支持 anthropic/alwaysLoad 元标记
• checkPermissions 返回 passthrough，交给通用权限系统处理
• 支持 URL elicitation 重试（OAuth 等认证流）

4.8 工具执行

4.9 权限控制

5. Claude Code 是如何修改代码的

在对 Claude Code 的上下文管理、ReAct 循环、Harness Engineering 和工具体系有了一个基本的了解之后，笔者身为程序员，自然最关心的就是"修改代码"这件事情了，所以本节我们就落到这个具体的需求点上，来探讨一下 Claude Code 在做修改代码这件事情的时候，到底做了什么。

当面对这个问题的时候，笔者心中又衍生了几个小问题：

1. 修改代码这个行为是怎么完成的？
2. 如何确保修改的精确性？
3. 如何确保修改的全面性？
4. 如何确保修改的安全性？（并发冲突...）
5. 如何确保修改的语法正确性？
6. 如何确保修改的功能正确性？
7. 修改后整个上下文管理发生了什么？

好的，让我们一一解答。（废了，我不想要"万字长文"的 🤷🏻‍♀️🤡😷）

5.1 修改代码这个行为是怎么完成的？

Claude Code 修改文件有两个工具：

System prompt 引导模型优先使用 Edit——修改 500 行文件中的 1 行，Edit 只需发送 ~10 行 token，Write 则需发送全部 500 行。

"ALWAYS prefer editing existing files. NEVER write new files unless explicitly required."

举个例子：

输入:
  file_path:  "/project/src/auth.ts"
  old_string: "function login(user) {\n  return false\n}"
  new_string: "function login(user) {\n  return authenticate(user)\n}"

执行:
  fileContent.replace(old_string, new_string)

为什么选这个方案？ —— 因为它匹配 LLM 的能力特征：

5.2 如何确保修改的精确性？

提示

核心问题：模型给出的 old_string，能不能准确定位到文件中的正确位置？

5.2.1 唯一性校验 - 不允许歧义

默认 replace_all = false，要求 old_string 在文件中只出现一次：

// 匹配 3 次 → 拒绝

"Found 3 matches, but replace_all is false. Provide more context to uniquely identify the instance."

这个设计迫使模型提供足够的上下文行来唯一定位修改点。模型不能只写 return false（可能出现多次），必须包含上下行直到唯一。

5.2.2 先读后写 - 禁止盲改

const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp) {
  → 拒绝: "File has not been read yet. Read it first."
}

模型必须先用 FileReadTool 读过文件。这确保 old_string 是基于当前真实内容构造的，而不是基于训练数据中的"记忆"。

5.2.3 编码和换行符保留 - 不引入格式噪音

读取时: 检测编码(UTF-8/UTF-16LE) + 换行符(LF/CRLF) → 记录
替换时: 在标准化的 \n 文本上操作
写入时: 用原始编码 + 原始换行符写回

不保留的后果：Windows 项目 CRLF 文件被转成 LF → git diff 爆炸，每行都显示被修改。

5.3 如何确保修改的全面性？

提示

核心问题：如果需要改多处，怎么保证不遗漏？

5.3.1 replace_all 模式

一个 Edit 调用 + replace_all: true 可以一次替换文件中所有匹配——适用于变量重命名等场景。

5.3.2 对话循环驱动多文件修改

Claude Code 的修改不是一次性的，而是对话循环驱动的多轮工具调用：

模型: "我需要修改 3 个文件"
  → tool_use: Edit(file_a, ...)
  → tool_use: Edit(file_b, ...)
  → tool_use: Edit(file_c, ...)
  → "修改完成"

模型可以在一轮中发出多个 Edit 调用，并行执行（Glob/Grep/Read 是 concurrency_safe，可并行；Edit 是非 safe，串行执行）。

5.3.3 Agent 并行修改

主线程可以 spawn 子 Agent 并行处理不同文件/模块：

主 Agent: "重构 auth 模块"
  ├── spawn Explore Agent → 搜索所有相关文件
  ├── 基于搜索结果，spawn 多个 General Agent → 各自修改不同文件
  └── 汇总结果

5.3.4 附件系统的"变更感知"

每轮工具执行完成后，changed_files 附件会检测哪些文件被外部修改（linter、format-on-save 等），注入 diff snippet 告知模型：

"Note: auth.ts was modified, either by the user or by a linter.
 Here are the relevant changes: ..."

模型看到这些变更后可以决定是否需要追加修改——确保不遗漏 linter 引入的变化。

5.4 如何确保修改的安全性？

提示

核心问题：并发冲突、外部修改、误操作如何防范？

5.5 如何确保修改的语法正确性？

提示

核心问题：替换完成后，文件的语法是否仍然合法？

5.5.1 Claude Code 当前策略：事后检测而非事前校验

FileEditTool 本身不做任何语法检查——它是语言无关的纯文本替换。语法正确性由两个机制保障：

• LSP 实时诊断（事后检测）：如果编辑引入了语法错误，LSP 会产生诊断信息（error/warning），通过 diagnostics 附件在下一轮注入到模型上下文，模型看到诊断后会自行修复。
• 模型自身的代码理解能力：模型在生成 new_string 时已经考虑了语法——它不是随机替换，而是理解代码结构后生成的。先读后写强制确保模型看过完整文件，有足够的上下文生成语法正确的代码。

5.5.2 工程建议：借鉴强类型语言的编译时保障

当前的"事后检测"模式存在缺陷：先写入错误代码 → LSP 报错 → 模型再修 → 又一轮 API 调用。每次修复循环至少浪费一轮 token。更好的思路是写入前校验。

这个时候，静态强类型语言的编译器（如 TypeScript 和 Rust），就可以发挥巨大的作用。

5.6 如何确保修改的功能正确性？

提示

核心问题：语法对了，但逻辑是否正确？功能是否如预期？

这不是单个工具能解决的问题。我们可以通过三道防线构建功能正确性保障：

• Prompt 引导自验证
• TDD 驱动的验证循环
• 独立于执行者的外部校验

5.6.1 第一道防线：Prompt 引导自验证

Claude Code 的 System prompt 中存在以下关键指令:

"Before reporting a task complete, verify it actually works:
 run the test, execute the script, check the output."

"If you can't verify (no test exists, can't run the code),
 say so explicitly rather than claiming success."

"Never claim 'all tests pass' when output shows failures."

这些不是建议，而是行为纠偏指令——专门针对模型"虚报成功"的倾向。

5.6.2 第二道防线：TDD 驱动的验证循环

Claude Code 的对话循环天然支持 红-绿-重构 的 TDD 工作流：

理想流程（TDD 先行）:

用户: "给 authenticate 函数添加 token 过期检查"

模型: Read(auth.test.ts)                → 了解现有测试
模型: Edit(auth.test.ts, ...)           → 先写测试（红）
模型: Bash("npm test")                  → 确认测试失败（红 ✓）
模型: Read(auth.ts)                     → 了解实现
模型: Edit(auth.ts, ...)                → 修改实现（绿）
模型: Bash("npm test")                  → 确认测试通过（绿 ✓）
模型: "修改完成，新增了 token 过期测试，所有测试通过。"

即使模型不主动做 TDD，现有测试也充当安全网：

实际常见流程:

模型: Edit(auth.ts, ...)                → 修改代码
模型: Bash("npm test")                  → 运行已有测试
      ← 失败: "TypeError: authenticate is not a function"
模型: Read(auth.ts)                     → 重读文件
模型: Edit(auth.ts, ...)                → 修复问题
模型: Bash("npm test")                  → 再次运行
      ← 所有测试通过

TDD 思维对 AI Coding 的特殊价值：

当没有测试时——这是最危险的场景。Claude Code 的 prompt 要求模型明确说 "I can't verify" 而不是假装成功。但更好的做法是：模型主动为修改的代码补充测试。这可以通过 CLAUDE.md 中的项目级指令强化：

# CLAUDE.md

修改任何函数时，如果该函数没有测试，先补充测试再修改实现。

5.6.3 第三道防线：独立于执行者的外部校验

• 权限对话框——写入前的代码审查窗口：每次写操作前弹出确认对话框（未明确授权时）。
• 极简返回值——迫使模型主动自验证：Edit 成功只返回 "file updated successfully"，不附带修改后的文件内容。这与前面的 LSP 诊断形成配合——LSP 诊断是异步注入的（下一轮才能看到），在此之前模型没有任何"修改是否正确"的直接信号。极简返回值切断了"看到结果就以为改对了"的捷径：模型必须主动 Read 重新检查，或 Bash 运行测试来确认修改生效，而不是假设成功。
• 独立 Agent 的异步复查：内置的 Verification Agent 在后台异步运行，专门负责复查代码变更。它被刻意限制为只读模式——只能使用 Read、Glob、Grep、Bash，不能调用任何写工具。

5.7 修改后整个上下文管理发生了什么？

提示

核心目标：让模型在每一轮都拥有与真实世界一致的认知。

整体状态（state）的迁移图如下：

一次 Edit 不只是"改了一个文件"——它更新了系统的文件认知（readFileState）、触发了语言服务器重分析（LSP）、通知了用户的 IDE（VSCode）、创建了可撤销的备份（fileHistory），并在下一轮对话中通过附件系统将所有变化反馈给模型。整个上下文管理的目标是：让模型在每一轮都拥有与真实世界一致的认知。

5.8 串一下整个流程

一个完整的代码修改流程如下所示：

模型发出 Edit tool_use
│
═══ validateInput() ════════════════════════════
│
Step 1: 基础校验
├── old_string === new_string? → 拒绝（无变化）
├── deny 规则检查 → 路径是否被禁止编辑
├── UNC 路径安全检查（防 NTLM 泄露）
└── 文件大小 > 1GiB? → 拒绝（防 OOM）
│
Step 2: 读取文件
├── 检测编码（UTF-8 / UTF-16LE）
├── CRLF → LF 标准化
├── 文件不存在 + old_string 为空 → 创建新文件
└── .ipynb 文件 → 引导用 NotebookEditTool
│
Step 3: "先读后写"检查 ★★★
├── readFileState 中没有此文件?
│ → 拒绝: "File has not been read yet. Read it first."
│ (强制模型先用 Read 工具读文件，确保了解文件内容)
│
└── readFileState.timestamp < 文件 mtime?
→ 拒绝: "File has been modified since read."
(防止覆盖用户或 linter 的修改)
│
Step 4: 查找 old_string
├── 精确匹配 → 使用
├── 不匹配 → 尝试 curly quote 标准化匹配
│ (文件中 'hello' → 模型输出 'hello' → 自动匹配)
└── 仍不匹配 → 拒绝: "String to replace not found"
│
Step 5: 唯一性检查
├── 匹配 1 次 → OK
├── 匹配 > 1 次 且 replace_all=false
│ → 拒绝: "Found N matches, set replace_all=true or provide more context"
└── 匹配 > 1 次 且 replace_all=true → OK（替换全部）
│
═══ checkPermissions() ═════════════════════════
│
Step 6: 写权限检查
└── checkWritePermissionForTool() → allow/ask/deny
│
═══ call() ═════════════════════════════════════
│
Step 7: 执行替换
├── 7a. 发现技能目录（非阻塞）
├── 7b. 诊断追踪器 beforeFileEdited()
├── 7c. 确保父目录存在 mkdir()
├── 7d. 文件历史备份（若启用）
├── 7e. 同步读取文件（原子性临界区开始）
│ readFileSyncWithMetadata() ← 保留编码和换行符
├── 7f. 再次检查文件未被修改（staleness check）
│ mtime > lastRead.timestamp? → throw Error
├── 7g. findActualString() → 处理 curly quote
├── 7h. preserveQuoteStyle() → 保留文件原有引号风格
├── 7i. getPatchForEdit() → 生成 patch + 新文件内容
│ replace_all ? file.replaceAll(old, new) : file.replace(old, new)
├── 7j. writeTextContent() ← 写入磁盘 ★★★
│ 保留原始编码（UTF-8/UTF-16LE）
│ 保留原始换行符（LF/CRLF）
│
Step 8: 后置处理
├── 8a. 通知 LSP 服务器 didChange + didSave
├── 8b. 通知 VSCode 更新 diff 视图
├── 8c. 更新 readFileState（更新 timestamp 和 content）
├── 8d. 记录遥测事件
└── 8e. 返回 { filePath, oldString, newString, originalFile, structuredPatch }

6. 写在最后

Claude Code 的"开源"，给了我们一个难得的机会，去理解一个工业级 AI Agent 的真实复杂度。它不是一个"更大的 demo"，而是一个充分考虑了边界情况、失败模式、用户体验的工程系统。

但更重要的是，这些设计原则是可迁移的。无论你在构建 Coding Agent、数据分析 Agent，还是任何其他领域的 Agent：

• 附件系统的**"分层注入、差分通知、频率控制"**思想适用于任何需要上下文管理的场景
• **"反面清单"**式的 Prompt 写法适用于任何需要约束模型行为的场景
• **"先校验再执行、先读再写"**的工具设计适用于任何有副作用的操作
• **"事后检测 + 反馈闭环"**的质量保障模式适用于任何无法事前完全验证的场景

希望本文的分析能帮助读者不只是"知道 Claude Code 做了什么"，而是理解为什么这样做，并将这些思想应用到自己的实践中。

毕竟，AI 学会了没用——你学会了才有用。

MySQL 的事务是一个非常复杂的话题，在思考这个问题的时候，想要即触及重点又不显得啰嗦，就需要采用"总-分-总"的结构，并紧扣 ACID 这一核心模型来展开。

一句话核心

MySQL（InnoDB 引擎）的事务实现，本质上就是为了保证 ACID 特性。它的底层主要依赖两类日志（redo log & undo log）和一套并发控制机制（锁 & MVCC）来共同完成。

1. 原子性（Atomicity）：靠 Undo Log。原子性保证事务要么全部成功，要么全部失败。这是通过 Undo Log（回滚日志）实现的。它记录了数据的逻辑反向操作（比如 Insert 对应 Delete）。如果事务失败或回滚，利用 Undo Log 就能把数据恢复到事务开始之前的状态。
2. 持久性（Durability）：靠 Redo Log（WAL）。持久性保证提交的数据不丢失。这是通过 Redo Log（重放日志）实现的。它遵循 WAL（Write-Ahead Logging）原则，事务提交时先写日志再刷盘。即使宕机，重启后也能通过 Redo Log 重放来恢复数据。另外，Bin Log 和 Redo Log 通过两阶段提交（2PC）来保证逻辑一致性。
3. 隔离性（Isolation）：靠锁和 MVCC 机制。隔离性是为了解决并发问题，InnoDB 提供了两种手段。
   • 写操作（当前读）：依赖锁机制（如 Record Lock、Gap Lock、Next-Key Lock）来防止脏读和幻读。
   • 读操作（快照读）：依赖 MVCC（多版本并发控制），通过 ReadView + Undo Log 版本链实现不加锁的非阻塞读，极大提高了并发性能。
4. 一致性（Consistency）：一致性是事务的最终目标。它是通过上述的原子性、持久性和隔离性共同保障的，同时还需与业务层面的逻辑约束（如外键）来配合。

所以简单来说，Redo Log 保证了数据不丢，Undo Log 保证了可以后悔，MVCC 和锁保证了并发安全，最终实现了事务的一致性。

redo log 是怎么实现持久性的？

对 ACID 有了全局视野上的认知后，那么第一个问题就来了，redo log 是如何实现持久性的？

一句话核心

Redo Log 实现持久性的核心思想是 WAL（Write-Ahead Logging，日志先行）技术，简单来说就是：先顺序写日志，后提交事务，再写磁盘数据。

具体来说包含 3 个方面：

• 利用顺序写替代随机写（性能基础）：当事务修改数据时，InnoDB 只是修改了内存（Buffer Pool）中的数据页，此时数据变成了脏页。 如果每次修改都直接把数据页刷入磁盘，那是随机 I/O，性能非常差。 所以，InnoDB 先把对数据页的物理修改记录到 Redo Log 中。Redo Log 是追加写的，属于顺序 I/O，速度非常快。只要日志落盘了，事务就算成功了。
• 刷盘策略：为了保证日志真的落盘，InnoDB 提供了 innodb_flush_log_at_trx_commit 参数。 实现 ACID 中严格持久性的关键在于将该参数设置为 1。 这意味着：每次事务提交时，都会强制调用 fsync 将 Redo Log Buffer 中的日志刷入磁盘。只有刷盘成功，事务才算 Commit 成功。
• 崩溃恢复：如果 MySQL 宕机，内存里的脏页还没来得及刷入磁盘（丢失了）。 但在重启时，InnoDB 会读取磁盘上的 Redo Log，根据日志里的物理修改记录（比如把第 10 页偏移量 50 的值改为 A），重新把这些操作在内存里执行一遍。 这个过程叫 Crash Recovery，它保证了即使宕机，提交过的数据也绝对不会丢失。

另外，Redo Log 是循环写入的（Circular Buffer），配合 Checkpoint 机制。当脏页真正刷入磁盘后，对应的 Redo Log 空间就可以被覆盖重用了。

redo log 是如何进行崩溃恢复的？(持久性+原子性)

接下来最复杂的地方就是 redo log 它凭什么能支持崩溃恢复？

redo log 的存储结构是怎样的？

首先我们要看一下 redo log 的底层结构是怎样的：

• redo log 是循环写入的，底层会将 redo log 分成一个个的 redo log block，每个 block 大小为 512MB。
• 事务中执行修改类 SQL 的时候，在修改完内存数据（buffer pool）每条会生成 LSN（Log Sequence Number），然后 WAL 写到 redo log block 中。注意，这里一个事务会生成多个 LSN，多个事务是并发执行的，所以多个事务之间的 LSN 是可能存在交替的。也就是说，为提交事务的 LSN 也可能会被刷盘哦！（后面会详细展开为什么可以这样）
• LSN 是逻辑上日志按照时间顺序从小到大的编码，在 innodb 上，LSN 是一个 64 位的整数，取的是从数据库安装启动开始，到当前所写入的总的日志字节数。

需要注意的是，redo log 也不是直接写磁盘的，也是先写 redo log buffer，然后再刷盘的。

所以要保证真正的持久性，还需要结合 redo log 的刷盘策略配置：innodb_flush_log_at_trx_commit ，InnoDB 提供了 3 种策略：

• 0：每秒刷一次磁盘
• 1：每提交一个事务，就刷一次磁盘。最安全！这是保证持久性的必要条件！也是 InnoDB 的默认值！
• 2：每次事务提交时，写到 OS Cache，但不立即 Flush。Flush 由后台线程每秒做一次。

redo log 存的是什么？

下一个问题就是 redo log 存的到底是什么？有这么几种选项：

redo log 的日志叫physiological logging，翻译过来就是 physical + logical logging，即物理逻辑日志。

简单来说

先以 Page 为单位记录日志，每个 Page 里面再采取逻辑记法（记录 Page 里面哪一行被修改了）。即物理到页，逻辑到行。

格式结构：Type + Space ID + Page Number + Data

• 物理层面：它精准记录了要修改哪个表空间 (Space ID) 的哪个数据页 (Page Number)。
• 逻辑层面：在数据页内部，它记录的是逻辑操作。

物理定位 (Physical)        逻辑操作 (Logical)
+---------------------+   +-------------------------+
|  Page Location      |   |   Modification Body     |
+--+-------+----------+   +-------------------------+
|T | Space | Page No  |   | Offset | Len | Value... |
|y |  ID   |          |   |        |     |          |
|p |       |          |   |        |     |          |
|e |       |          |   |        |     |          |
+--+-------+----------+   +--------+-----+----------+

假设我们要执行 UPDATE users SET age = 20 WHERE id = 1; 假设这条记录在 Space 5 的 Page 100，记录在页内的偏移量是 600。

Redo Log 可能会记成这样一条记录：

类型: MLOG_4BYTES (写入4字节整数)
表空间: 5
页号: 100
页内偏移量: 600
新值: 20

恢复过程是这样的：

1. 物理寻址：根据 Space 5 + Page 100，直接从磁盘读出这个页加载到内存。
2. 逻辑重放：根据类型 MLOG_4BYTES，找到页内偏移量 600 的位置。
3. 执行修改：把那里的 4 个字节直接覆盖为 20。

所以，Redo Log 是物理位置 + 逻辑操作的结合。这种设计既利用了物理定位的幂等性（恢复时可以直接定位到页），又节省了大量的存储空间（不用记录整个页面的变化）。

既然 Redo Log 是写在固定大小的 Block 里的，那如果我要写入的一组操作（比如一个事务）特别大，跨了多个 Block 怎么办？或者写到一半断电了，只有半条 Log 怎么办？这就涉及到了 MTR (Mini-Transaction) 的原子性设计。

MTR (Mini-Transaction) 是 InnoDB 修改底层数据页的最小原子单位。

你可以把它理解为底层的微事务。一个普通的 SQL 事务可能包含很多条 SQL，而每一条 SQL 在底层执行时，可能会触发多次 MTR。

你在 B+ 树插入一条记录，可能需要：

1. 修改叶子节点页。
2. 修改索引页。
3. 如果触发页分裂，还要修改父节点、甚至增加树的高度。

MTR 承诺上述这 1、2、3 步涉及的所有 Redo Log，必须作为一个整体写入日志文件。要么全有，要么全无。

MTR 的运行遵循一个"先收集、后批发"的模式：

1. 收集阶段 (Private Buffer)： 当一个线程要修改数据页时，它会先在自己的私有内存区域开辟一块空间，把这次操作产生的所有 Physiological Log 记录下来。
2. 原子提交 (Commit to Log Buffer)： 当这个原子操作完成时（比如页分裂完成了），MTR 会执行 commit。此时，它会将私有缓冲区里的所有日志一次性拷贝到全局的 Redo Log Buffer 中。
3. 打标 (The End Marker)： MTR 会在这一组日志的最后一条记录后面，附带一个特殊的标记（MLOG_MULTI_REC_END）。

End Marker 的作用：

• 恢复时的逻辑：InnoDB 在崩溃恢复扫描 Redo Log 时，会一组一组地看。
• 完整性校验：如果它发现一组日志开头了，但扫描到最后没看到 MLOG_MULTI_REC_END 标记，它就认为这组日志是损坏且不完整的。
• 处理策略：直接丢弃这组不完整的日志，不进行重放。因为没看到 End Marker，说明这个 MTR 还没 Commit。根据 WAL 原则，既然日志没 Commit，那么磁盘上的物理数据页肯定也没改（或者改了也会被 Undo 回滚）。丢弃它保证了数据库永远不会停留在 B+ 树断裂的中间状态。

redo log 恢复过程是怎样的？

直到了存什么、怎么存之后，最后就是怎么用的问题了。

**ARIES 算法（Algorithms for Recovery and Isolation Exploiting Semantics）**是现代主流数据库（InnoDB、SQL Server、Oracle）崩溃恢复算法的鼻祖。在 MySQL InnoDB 的实现中，虽然有很多工程上的优化，但其核心思想完全继承自 ARIES。

ARIES 主要分为三个阶段：

1. 分析阶段：确定哪些数据页是脏页（做 redo），确定哪些事务未提交（做 undo）。
2. 执行 redo。
3. 执行 undo。

为什么先执行 redo 再执行 undo？

因为 undo log 也是"数据"，它也要"写 redo log"！所以 redo 后，undo log 就恢复如初了！这个时候才可以 undo。

那问题就来了，怎么知道哪些数据页是脏页？怎么知道哪些事务未提交？

直观的想法就是对整个内存做一个快照，但是这数据量太大了，所以为了减少这个数据量，InnoDB 维护了两个表，并定期做 checkpoint，这称为 fuzzy checkpoint。

• 活跃事务表：当前所有未提交事务的合集，每个事务维护了一个关键变量 lastLSN。lastLSN 是该事务产生的最后一条日志的 LSN。
• 脏页表：当前所有未刷盘的 Page 的集合（包括已提交事务和未提交事务），每个 Page 维护了一个关键变量 recoveryLSN。recoveryLSN 是导致该 Page 成为脏页的最早的 LSN。比如一个 Page 本来是 clean，然后事务 1 修改了它，对应的 LSN 是 LSN1，之后事务 2，事务 3 又修改了它，对应 LSN2 和 LSN3，这个时候 recoveryLSN 就是 LSN1。

每次 fuzzy checkpoint，就把这 2 张表的数据生成一个快照，形成一条 checkpoint 日志，记入 redo log。

我们来看一下这 2 个表形成的 checkpoint 日志具体是如何运用的。假设我们有一段如上图所示的日志执行流。

（一）首先是分析阶段，我们检查 Crash 最近的 Checkpoint2：

• 这个时候活跃事务表有 {T2, T3}，此时还没有 T4、T5。从此处开始遍历到 Redo Log 末尾。遍历的过程中，遇到 T2 的结尾 MLOG_MULTI_REC_END，就把 T2 从集合中剔除。当遇到事务 T4 的时候，就把 T4 加入到集合中。当遇到事务 T5 的时候，就把 T5 加入到集合中。最终集合就变成了 {T2, T3, T4}。
• 假设这个时候的脏页有 {P2, P3}，从后遍历遇到新的页就将其加入脏页集合，最终集合可能是 {P1, P2, P3, P4, P5}。

（二）进行 Redo：

• 我们取脏页集合中最小的 recoveryLSN，得到 firstLSN。从 firstLSN 遍历到 Redo Log 到末尾，把每条 Redo Log 对应的 Page 全部重新刷一次盘。
• 我们不怕重复刷盘，这是因为 Redo Log 是幂等的。磁盘上每一个 Page 都有一个关键字段 pageLSN。这个 LSN 记录这个 Page 刷盘时最后一次修改它的日志对应的 LSN。如果重放日志的 LSN <= pageLSN，则不修改对应日志的 Page，略过这条日志。
• Redo 完成后，就保证了所有的脏页都已经刷到磁盘上了，并且未提交的事务 {T2, T3, T4} 对应的页也写入了磁盘，这个时候就要做回滚了。

（三）进行 Undo：

• 在分析阶段我们已经找出了未提交事务集合 {T2, T3, T4} 。从最后一条日志逆向遍历，因为每条日志都有一个 prevLSN 字段，所以可以沿着 T3、T4、T5 各自的日志链一直回溯到 T3 的第一条日志。
• 所以 Undo，是指每一道一条属于 T3、T4、T5 的 Log，就生成一条逆向的 SQL 来执行，其对应执行的 Redo Log 是 Compensation Log Record（CLR），会在 Redo Log 尾部继续追加，由此来实现回滚功能。

在进行 Undo 的时候，还有可能会遇到一个问题，回滚到一半，宕机，重启，再回滚，要进行"回滚的回滚"。

假设事务 T 有三条日志，对应 LSN 分别为 600、900 和 1000。

1. 首先对 1000 进行回滚，生成对应的 LSN=1200 的日志，这条日志里面会有一个字段叫做 UndoNxtLSN，记录的是其对应的被回滚的日志的前一条日志，即 UndoNxtLSN=900.
2. 宕机重启时，遇到 LSN=1200 的 CLR，会忽略，然后看到 UndoNxtLSN=900，会定位到 LSN=900 的日志，为其生成对应的 CLR 日志 LSN=1600，然后继续回滚。
3. 然后 LSN=1700 的日志，回滚的是 600 的。

这样就能保证回滚日志和之前的日志一一对应，不会出现"回滚嵌套"的情况。

小节

到此为止，我们已经对事物的 A（原子性）和 D（持久性）有了一个全面的理解，这里对 Redo Log 做一个简单的总结：

• 一个事务赌赢多条 Redo Log，事务的 Redo Log 不是连续存储的，靠 prevLSN 实现回溯。
• Redo Log 不保证事务的原子性，而是保证了持久性。无论提交的、未提交的事务的日志，都会进入 Redo Log。从而使得 Redo Log 回放完毕，数据库就恢复到了宕机之前的状态，称为 Repeating History。
• 同时，把未提交的事务挑出来进行回滚。回滚通过 Checkpoint 记录的 活跃事务表 + 每个事务日志中的开始/结束标记 + Undo Log 来实现。
• Redo Log 具有幂等性，通过每个 Page 里面的 pageLSN 进行实现。
• 事务不存在物理回滚，所有的回滚操作都被转化成了 Compensation Log Record 进行 Commit。

undo log 是怎么实现隔离性的？

前面我们将了 redo log 是如何实现持久性的，并且顺带将了崩溃恢复过程中，undo log 是如何实现原子性的。接下来我们来看下，undo log 是如何实现隔离性的。

真的需要 undo log 吗？

这是笔者在其他资料都看不到的一个问题（当然，也可能是看得太少了 😭），但是《软件架构设计·大型网站技术架构与业务架构融合之道》这书就着重讲解了这个问题，讲的太好了 👏🏻！

事务回滚有 4 种场景：

1. 人为回滚。业务异常，客户端主动请求回滚。
2. 宕机回滚。
3. 人为回滚 + 宕机回滚。
4. 宕机回滚 + 宕机回滚。

数据库面临两个核心决策：

1. 何时把脏页写盘？ （是否允许在事务提交前写？） -> STEAL vs NO-STEAL
2. 事务提交时必须写盘吗？ （是否要求提交时同步刷盘？） -> FORCE vs NO-FORCE

undo log 的存储结构是怎样的？

要理解 InnoDB Undo Log 的底层实现，我们不能把它想象成一个简单的文本日志文件（像 error.log 那样）。

从第一性原理来看，InnoDB 把 Undo Log 当作"特殊的只读数据"来管理。 这意味着：Undo Log 也是存在于 Page（页） 里的，它也受 Buffer Pool 缓存，它修改时也会产生 Redo Log，它也会被刷入磁盘（前面的崩溃恢复算法也说明了这一点）。

我们需要从 微观（单条记录长什么样） 到 宏观（如何在磁盘和内存中组织） 两个维度来拆解。

微观视角：Undo Log Record（物理二进制结构）

Undo Log 并不是记录原来的整个页面，而是记录逻辑上的反向操作。根据操作类型的不同，它的物理结构分为两类，这种区分是为了极致的存储效率。

当你执行 INSERT 时，产生的 Undo Log。

• 如果我要回滚一个插入，我只需要知道**主键（Primary Key）**是什么，然后把它删掉就行了。
• 物理结构： 非常简单，只记录了 <Table ID, Primary Key>。
• 生命周期： 极短。事务一提交（Commit），这个 Undo Log 就没用了（因为新插入的数据对于其他早于它的事务是天然不可见的，不需要通过 Undo Log 来构建历史版本）。所以它会在提交后直接删除。

• Undo Number 是Undo的一个递增编号
• Table ID 用来表示是哪张表的修改。
• 下面一组 Key Fields 的长度不定，因为对应表的主键可能由多个 field 组成，这里需要记录 Record 完整的主键信息，回滚的时候可以通过这个信息在索引中定位到对应的 Record。
• 除此之外，在 Undo Record 的头尾还各留了两个字节用户记录其前序和后继 Undo Record 的位置。

当你执行 UPDATE 或 DELETE 时，产生的 Undo Log。

• 如果我要回滚一个更新，我必须知道更新前的旧值。如果我要支持 MVCC，我也需要这个旧值。
• 物理结构： 比较复杂。它需要记录 <Table ID, Primary Key, 修改列的旧值 (Old Value)>。
• 生命周期： 很长。事务提交后，不能马上删除。因为可能有别的长事务（Read View）还在运行，它们可能需要通过这个 Undo Log 来看快照读。
• 只有当系统里没有任何一个事务需要看这个历史版本时，它才会被 Purge 线程 清理掉。

除了跟 Insert Undo Record 相同的头尾信息，以及主键 Key Fileds 之外，Update Undo Record 增加了：

• Transaction Id 记录了产生这个历史版本事务 Id，用作后续 MVCC 中的版本可见性判断。
• Rollptr 指向的是该记录的上一个版本的位置，包括 space number，page number 和 page 内的 offset。沿着 Rollptr 可以找到一个 Record 的所有历史版本。
• Update Fields 中记录的就是当前这个 Record 版本相对于其之后的一次修改的 Delta 信息，包括所有被修改的 Field 的编号，长度和历史值。

宏观视角：组织结构（磁盘与内存）

InnoDB 是如何管理成千上万个并发事务产生的 Undo Log Record 呢？

这涉及到一个层级结构：Tablespace -> Rollback Segment -> Undo Log Segment -> Undo Page。

这张图展示了 InnoDB 是如何在磁盘和内存中从宏观到微观组织 Undo Log 的。这就像是一个巨大的"档案管理系统"。

为了更直观地理解，我们可以把这个结构比喻成一个大型档案馆。我们由外向内，层层拆解：

第一层：Undo Tablespace (档案馆大楼)

• 图中位置： 最外层的深蓝色大框 InnoDB Undo Tablespace。
• 物理对应： 磁盘上的文件，比如 undo_001, undo_002（或者老版本在 ibdata1 中）。
• 解释： 这是存放档案的物理大楼。所有回滚记录最终都要落在这里。自 MySQL 8.0 开始，Undo Log 默认使用独立的表空间文件，不再挤在系统表空间里，这样管理更灵活。

第二层：Rollback Segment (档案室/管理员)

• 图中位置： 左上角的 Rollback Segment (rseg 0 ... 127)。
• 解释： 为了不让成千上万个事务打架，InnoDB 把大楼划分成了 128 个档案室（rseg）。每个事务开始时，会被分配给其中一个 rseg 来管理。这样，不同 rseg 下的事务就不会产生严重的锁竞争。

第三层：Undo Slot (档案柜/目录槽)

• 图中位置： 左边中间放大的 Undo Slot 0 ... 1023。
• 解释： 走进第 5 号档案室（rseg 5），你会看到墙上有一排排的格子，这就是 Slot。每个 rseg 有 1024 个 Slot。当一个事务开启时，它会占用一个 Slot。这个 Slot 并不直接存数据，而是存放指针，指向真正存放档案的地方。

第四层：Undo Log Segment (档案卷宗/链表)

• 图中位置： 右边的大框，由箭头连接的三个 Undo Page。
• 解释： 这是最核心的存储结构。
  • 动态扩展： 事务刚开始写 Undo Log 时，可能只需要一张纸（一个 Page）。但如果是个大事务（比如更新了 100 万行数据），一张纸不够写，就需要申请第二张、第三张。
  • 链表结构： 图中的箭头展示了它们是如何连起来的：Start Page（首页） -> Middle Page（中间页） -> End Page（尾页）。这组成了一个逻辑上的 Segment（段）。
  • 左边的 Undo Slot 指针，实际上就是指向这个链表的头部。

第五层：Undo Page (档案纸/物理页)

• 图中位置： 右边的三个蓝色小方块。
• 解释： 这是磁盘读写的最小单位（默认为 16KB）。
  • Page Header/Footer： 每一页都有头和尾，记录了校验和、页号、以及上一页/下一页的指针（双向链表）。
  • Undo Log Record： 页中间那一堆 Update, ID=A、Insert, ID=B 就是真正的回滚记录。

当一个事务需要修改数据时：

1. Space Alloc: 在 Undo Tablespace 中定位。
2. Rseg Assign: 事务被调度到第 $N$ 号 Rollback Segment。
3. Slot Reserving: 在 Rseg Header 中找到一个空闲的 Undo Slot，将其状态置为占用。
4. Segment Init: 如果 Slot 指向空，则通过 FSEG 申请一个新的 Undo Log Segment（包含至少一个 Page）；如果 Slot 指向已缓存的 Segment，则复用之。
5. Page Write: 事务在 Undo Page 中顺序写入 Undo Log Record。若当前页写满，则通过 Segment 申请新页，并更新页头的双向链表指针。

这么设计的两大好处：

• 为了高并发：128 个 Segment × 1024 个 Slot = 支持 13 万 个并发事务同时写 Undo Log。
• 为了大事务：通过 Page 链表（Segment），一个事务可以无限写入 Undo Log，而不会受到单页 16KB 的限制。

undo log 如何实现 MVCC？

在回答这个问题之前，我们先来思考一下多线程编程中，读写的并发问题有哪些策略？

• 互斥锁
• 读写锁
• CopyOnWrite

这 3 种策略，从上到下，并发度越来越高。而 InnoDB 用的就是 CopyOnWrite 的思想，即 Undo Log 的本质思想就是 CopyOnWrite。

提示

每个事务修改记录之前，都会把该记录拷贝一份出来，拷贝出来的这个备份在 Undo Log 里，因为事务有唯一的编号（Trx ID），ID 从小到大递增，每一次修改，就是一个版本，因为 Undo Log 维护了数据的从旧到新的每个版本，各个版本之间的记录通过链表串联。

那内存中是如何把数据行和 Undo Log 连起来的呢？

我们在 Buffer Pool 里的每一行数据，实际上都有两个隐藏列：

1. DB_TRX_ID：最近修改这条数据的事务 ID。
2. DB_ROLL_PTR：回滚指针。

这个指针指向哪里？ 它包含三个信息：Space ID (表空间号), Page No (页号), Offset (页内偏移量)。 它精准地指向了Undo Page 中存放的那条对应的 Update Undo Log Record。

当事务提交后，Insert Undo Log 被释放了，但 Update Undo Log 被留下来了。 这些提交后的 Update Undo Log 会被加入到一个全局的大链表——History List。这个链表是给 Purge 线程 用的。

Purge 线程像一个扫地僧，它顺着 History List 扫描，一旦发现某个 Undo Log 对应的事务 ID 已经太老了（比当前所有活跃事务的 Read View 都老），说明再也没人需要看这个版本了，就把它物理删除，释放空间。

undo log 结合 redo log

我们前面说，undo log 其实也是一种"数据"，它也是要写 Redo Log 的。我们可以用一个例子来将这 2 者进行结合。

假设有如下一个事务：

start transaction
	update 表1某行记录
	delete 表1某行记录
	insert 表2某行记录
commit

把 Undo Log 和 Redo Log 加进去，此事务类似下面伪代码所示：

start transaction
	写 Undo Log1：备份该行数据（update）
	update 表1某行记录
	写 Redo Log1
	
	写 Undo Log2：备份该行数据（insert）
	delete 表1某行记录
	写 Redo Log2
	
	写 Undo Log3：该行的主键（delete）
	insert 表2某行记录
	写 Redo Log3
commit

binlog 是如何保证集群一致性的？

由于 MySQL 是插件式存储引擎架构，Binlog 作为 Server 层的全局日志，必须通过 两阶段提交（2PC） 与存储引擎层的 Redo Log 强绑定，才能在逻辑上构成一个完整的、可恢复的事务。

之所以需要这个机制，是因为 Redo Log和 Binlog 是独立的。如果不同步，就会出现"主库数据恢复了，但从库没同步"或者"从库同步了，但主库崩溃后数据丢了"的灾难。

提示

Redo Log 保证了物理一致性（崩溃恢复），而 Binlog 保证了逻辑一致性（主从复制、数据回滚/闪回）。

binlog 如何跟 redo log 进行配合？

因为 Binlog 和 Redo log 两个是独立的，所以要保证它们的一致性，需要遵循如下的两阶段提交（2PC）过程：

Prepare 阶段：

• InnoDB 将修改记录到 Redo Log。
• 将该事务的 XID（全局事务 ID）写入 Redo Log。
• 将 Redo Log 状态置为 TRX_PREPARE 并刷盘。

Commit 阶段：

• Server 层将事务的逻辑操作写入 Binlog 文件并刷盘。
• InnoDB 收到 Binlog 成功的反馈，在 Redo Log 中记录 commit 标记，事务正式完成。

如果系统在 2PC 过程中宕机，重启后 MySQL 会扫描 Redo Log，根据 XID 去 Binlog 中寻找匹配：

• 判定 1：Redo Log 有 commit 标记 $\to$ 直接提交。
• 判定 2：Redo Log 只有 prepare 标记，但 Binlog 中存在该 XID $\to$ 提交（因为 Binlog 已落盘，从库可能已同步，主库必须保持一致）。
• 判定 3：Redo Log 只有 prepare 标记，且 Binlog 中不存在该 XID $\to$ 回滚（说明宕机发生在写 Binlog 之前）。

既然第 1 阶段 Redo 已经刷盘了，为什么非要等到第 2 阶段 Binlog 刷盘后，事务才算成功？

因为 Redo Log 只管主库自己的崩溃恢复。如果不等 Binlog 刷盘就认为成功，万一主库写完 Redo 挂了，没来得及写 Binlog，从库就不会同步这笔数据。重启后，主库有这笔数，从库没有，主从一致性就彻底崩了。所以 2PC 的核心就是用 Binlog 的落盘来充当全局事务的裁决者。

同 Redo Log 一样，Binlog 也存在一个刷盘策略问题，由参数 sync_binlog 控制：

• 0：事务提交之后不主动刷盘，依靠操作系统自身的刷盘机制，可能会丢失数据。
• 1：每提交一次事务，刷一次盘。
• n：每提交 n 次事务，刷一次盘。

显然，0 和 n 都不安全。为了不丢失数据，一般多建议双 1 保证，即 sync_binlog 和 innodb_flush_log_at_trx_commit 的值都取位 1。

刷盘压力那么大怎么缓解？

在双 1 配置下，每个事务都要触发磁盘 IO（fsync）。如果并发量上来，磁盘 IOPS 会直接把数据库卡死。

MySQL 5.6 引入了 BLGC，将提交过程设计成一个流水线。

核心思想

当有多个事务并发提交时，MySQL 维护了一个队列，第一个抢到锁的事务（第一个进入空队列）成为队长 (Leader)，后面排队的事务成为队员 (Follower)。队长会代表所有队员，一次性完成 IO 操作。

这个过程分为三个阶段的队列：

1. Flush 阶段（写 OS Cache）：队长带着一群队员，把他们各自的 Binlog 数据写入操作系统的文件缓存 (OS Cache)。

2. Sync 阶段（刷磁盘 fsync）：队长调用一次 fsync()。因为大家的数据都在 OS Cache 里了，这一次 fsync就把这一整车人的 Binlog 全都持久化到磁盘了。原本 10 个事务需要 10 次 fsync，现在 1 次搞定。吞吐量直接翻倍。

3. Commit 阶段（引擎层提交）：队长通知 InnoDB 引擎，把这批事务在 Redo Log 里的状态由 Prepare 改为 Commit。

🚀 Redo Log 也就顺便搭便车了

在没有 BLGC 之前，Redo Log 需要在 Prepare 阶段自己去刷盘。 有了 BLGC 后，MySQL 做了一个极度聪明的优化，叫做 Redo Log Group Commit。

它的时机是在 Flush 阶段 之后，Sync 阶段 之前。

1. Flush 阶段：队长把 Binlog 写进 OS Cache。
2. Redo Log 刷盘：在队长执行 Binlog 的 fsync 之前，InnoDB 发现："哎？既然你们这一车人都要提交了，那你们对应的 Redo Log (Prepare 状态) 肯定也要落盘啊"。于是，InnoDB 会把这一组事务的 Redo Log 一次性 刷入磁盘。
3. Sync 阶段：队长执行 Binlog 的 fsync。

通过这个机制，Redo Log 也享受到了组提交的红利。 原本：N 个事务 = N 次 Redo fsync + N 次 Binlog fsync。 现在：N 个事务（一批）= 1 次 Redo fsync + 1 次 Binlog fsync。

这就是为什么现在的 MySQL 即使开启了双 1 配置，在并发高的时候，性能依然非常强劲的原因。

总结

综上，我们就从 ACID 各个方向阐述了 InnoDB 是如何实现事务的了。回顾整个 MySQL 事务的实现链路，我们可以将其核心设计哲学概括为三重保障，这也是我们在架构设计中可以借鉴的最高准则。

物理层：WAL 与崩溃恢复 —— InnoDB 不直接写磁盘数据页，而是先写 Redo Log。

• 通过 Physiological Logging（定位到页，逻辑修改内容），在保证日志足够小的同时，拥有了修复物理 B+ 树的能力。
• ARIES 算法 保证了即使在极端宕机情况下，数据库也能通过"重做历史"和"逻辑回滚"恢复到一致状态。

**逻辑层：MVCC 与锁平衡 **—— 为了解决读写冲突，MySQL 并没有简单粗暴地使用全表锁或行锁。

• Undo Log 构建了数据的 History List，配合 ReadView 机制，实现了 RC 和 RR 级别下的快照读，做到了读不阻塞写，写不阻塞读。
• 这本质上就是 CopyOnWrite。

架构层：2PC 与组提交协同

• Binlog 决定了集群的逻辑一致性（主从）。
• Redo Log 决定了单机的物理一致性。
• BLGC (组提交) 则是在双 1 安全配置下，通过流水线和搭便车机制，将磁盘 I/O 成本降到最低。

理解 MySQL 事务，不应止步于 ACID 的定义，而应看透其在数据安全（持久性）、**高并发（隔离性）与吞吐量（性能）**之间所做的精妙权衡。

参考

• 庖丁解InnoDB之Undo LOG

核心矛盾根源：真相的传播延迟

• 单机模式："真相"只有一个（唯一的 DB 实例）。写入即事实，读取即真相。时间差近乎为零。
• 主从模式："真相"在传播。主库是当前的真相，从库是几百毫秒甚至几秒前的"历史影像"。依赖历史影像做决策，必然出错。

从单机到主从架构的升级，不是简单的加几台机器，而是一场思维方式的革命：

1. 放弃对实时强一致性的幻想：在分布式系统中，除了核心的金融级数据，大部分场景都要接受最终一致性。
2. 识别真理之源：时刻清楚 Master DB 是唯一的真理。Slave DB 只是用于分担非敏感读压力的快照副本。
3. 防御性编程：写代码时，永远要假设你读到的数据可能是旧的，并思考"如果它是旧的，我的业务逻辑会不会炸？"如果会炸，就必须升级方案（走主库、加异步校验链等）。

本篇接下来就梳理单机模式最佳实践在主从架构下失效的经典场景。

1. 缓存一致性

在单机模式下，为了应对 MySQL 和 Redis（缓存）的一致性，业界通用的解决方案是 Cache Aside（旁路缓存）。即：先更新 DB，再删缓存。下次读请求发现 Cache Miss，查 DB 并回填。因 DB 里的数据永远是最新的，回填缓存没问题。

但是在主从模式下就不一样了：

写请求删了缓存。读请求去从库查到了旧数据（因为延迟）。读请求把旧数据当作新数据塞回了 Redis。结果就导致了 Redis 里存储了脏数据。

总结

简单来说，Online DDL 的核心目标是：在修改表结构（DDL）的同时，不阻塞业务对表的读写操作（DML）。

1. 宏观概述

1.1 背景与痛点

为什么我们需要 Online DDL？

在 MySQL 5.6 之前，大多数 DDL 操作（如添加索引、添加列）的本质是暴力重构。MySQL 会执行以下步骤：

1. 创建一个新的临时表（新结构）。
2. 锁住原表（禁止写入）。
3. 将原表数据一行行复制到新表。
4. 删除原表，重命名新表。

这种方式被称为 Copy Table 方式。它的痛点极其明显：在数据量大的表中，DDL 可能运行数小时，期间业务无法写入，这对于高并发互联网应用是灾难性的。

为了解决这个问题，MySQL 逐步引入了 In-Place 和 Instant 算法，统称为 Online DDL。

1.2 从 Copy 到 Instant

理解 Online DDL 的关键在于理解三种算法的演进，这是一个由重到轻的过程：

1.2.1 COPY（MySQL 5.6 之前）

• 原理：在 Server 层处理，新建表 -> 导数据 -> 删旧表。
• 代价：极高。I/O 飙升，占用双倍磁盘空间，全程锁表（无法写入）。

1.2.2 INPLACE（MySQL 5.6 引入，成熟于 5.7）

• 原理：不再通过 Server 层复制数据，而是由 InnoDB 引擎内部在“原地”进行操作。
• 关键机制：虽然叫 In-Place（原地），但对于重建表的操作（如添加主键），它实际上还是在引擎内部重建了数据文件，但它引入了一个Row Log（增量日志）。
• 并发性：允许 DML（增删改）操作。
  • 在 DDL 执行期间，业务产生的新数据写入 Row Log。
  • DDL 完成数据重组后，再重放 Row Log 中的变更应用到新表空间。

1.2.3 INSTANT（MySQL 8.0 引入并持续增强）

• 原理：只修改数据字典（Metadata）中的元数据，完全不触碰底层数据文件（B+ 树）。
• 代价：几乎为零。耗时通常在毫秒级。
• 场景：MySQL 8.0 支持瞬间添加列，不需要重建表。

2. 底层原理

2.1 INPLACE

MySQL 5.6 引入，5.7 成熟。它的核心变革在于：将 DDL 操作下沉到 InnoDB 引擎层，并引入了 Row Log 来暂存并发写入。

INPLACE 分为两类：需要重建表（Rebuild）和不需要重建表（No-Rebuild）。我们重点讲最复杂的 Rebuild 场景（例如：添加主键、删除列、修改列字符集）。

第一阶段：初始化 (Prepare Phase)

1. 对表加 MDL 写锁（极短时间）。
2. 获取原表的元数据快照。
3. 降级锁：将 MDL 写锁降级为 MDL 读锁。此时业务可以正常读写（SELECT/INSERT/UPDATE/DELETE）。

第二阶段：执行 (Execution Phase) —— 最漫长

这是真正的 Online 阶段。InnoDB 引擎内部做两件事：

1. 数据重组 (Rebuild Data)：

• InnoDB 建立一个新的临时表空间文件（.ibd）。
• 扫描原表的 B+ 树叶子节点，按顺序将数据写入新的 B+ 树中。

2. 增量捕获 (Row Log)：

• 在数据重组期间，所有业务产生的 DML（增删改）操作，除了修改原表数据外，还会被记录到一个专门的内存缓冲区：**Row Log **。如果内存存不下，会溢出写入到临时文件中。

第三阶段：提交 (Commit Phase)

1. 升级锁：再次将 MDL 读锁升级为 MDL 写锁（此时业务写入再次短暂阻塞）。
2. 日志回放 (Apply Log)：将 Row Log 中积累的增量变更，应用到新的表空间中。因为 Row Log 通常比全量数据小得多，所以这个过程很快。
3. 文件交换：用新的 .ibd 文件替换旧文件。
4. 释放锁。

总结：

• 核心机制：快照数据（基线） + Row Log（增量）。
• 代价：虽然不阻塞写入，但会消耗大量 CPU 和 IO（同时写原表和 Log），且若 DDL 耗时过长，Row Log 可能撑爆磁盘。

注意

修改列的数据类型（例如从 CHAR 改为 INT）通常必须使用 COPY 算法。因为底层二进制存储格式变了，必须重写每一行数据，无法 In-Place。

2.2 INSTANT

MySQL 8.0 引入，并在 8.0.12 和 8.0.29 版本中大幅增强。它的核心在于：彻底放弃修改物理数据文件，只修改数据字典（Metadata）。

• MySQL 8.0.12：仅支持追加列。原理很简单，在表定义的元数据中记录一个"列数"标记。旧数据读出来列数不够，就自动补默认值。
• MySQL 8.0.29：支持任意位置加列/删列。原理更加精妙，利用了行版本控制。

底层原理流程：

1. 加锁：加 MDL 写锁（极短，仅用于修改元数据）。
2. 修改元数据：
   • 在 .SDI (System Data Index) 或数据字典中，更新表的定义。
   • 关键点：给表分配一个新的 INSTANT_COLUMN_ID。
   • 设置新列的 Default Value（存储在元数据中，不存磁盘行内）。
3. 释放锁。

当业务执行 SELECT * 时，InnoDB 引擎读取磁盘上的行记录（Row）：

• 旧行（DDL 之前写入的）：行头部的版本信息或列数标记表明它是"老版本"。InnoDB 发现这一行缺少新列，于是从元数据中读取该列的默认值，动态拼接并返回给应用。
• 新行（DDL 之后写入的）：按照新的结构物理存储，包含新列的数据。

3. 风险隐患

3.1 INPLACE

虽然 INPLACE 是 "Online"，但在生产环境（特别是大表）直接执行 ALTER TABLE 依然极其危险。

3.1.1 MDL 锁风暴

这是最容易被忽视的风险。

• 现象：你发起一个 Online DDL，理论上不锁表。但是，如果有另一个长事务（比如一个正在运行的慢查询）正在引用这张表，DDL 就会挂起，等待获取 MDL 锁。
• 连锁反应：MySQL 的锁等待队列通常是 FCFS (First Come First Served) 或写锁优先级高于读锁。DDL 一旦开始等待 MDL 锁，它后面进来的所有正常业务请求（SELECT/UPDATE）全都会被阻塞！瞬间导致连接池爆满，业务挂掉。
• 对策：在执行 DDL 前，务必检查 information_schema.processlist，确保没有长事务或慢查询在操作该表。

INSTANT 也有这个问题。

3.1.2 主从延迟

这是 MySQL 主从架构的经典痛点。

• Master：Online DDL 可以开启多线程（MySQL 8.0+ 支持 parallel DDL），或者只是 Master 机器性能强，跑了 10 分钟做完了。
• Binlog：DDL 完成后，Master 会往 Binlog 写一句 ALTER TABLE ...。
• Slave：
  • Slave 的 SQL Thread 是单线程回放 DDL 的（在很多版本配置下）。
  • Slave 收到这个 DDL，也开始跑。Master 跑了 10 分钟，Slave 可能也要跑 10 分钟（甚至更久，因为 Slave 配置通常低）。
  • 后果：在这 10 分钟内，Slave 忙着做 DDL，无法处理 Master 传过来的其他 Update/Insert Binlog。
  • Seconds_Behind_Master 飙升。读写分离的业务读不到最新数据，产生逻辑错误。

3.1.3 资源争抢与 Buffer Pool 污染

Online DDL（In-Place Rebuild）本质上是一次全量的读 + 全量的写。

• Buffer Pool 污染：
  • DDL 扫描原表所有数据页。如果表很大，会把 Buffer Pool 里的热数据（业务正在用的数据）挤出去。
  • DDL 结束后，业务查询必须重新从磁盘加载数据，导致 RT (响应时间) 抖动。
• IO 争抢：虽然 DDL 设置了并发度，但它依然会占用大量的磁盘 IOPS 和 CPU。如果是云盘或机械盘，业务正常的 CRUD 可能会因为 IO 等待而变慢。

3.1.4 Apply Log 阻塞

MySQL 为了保证新表和旧表数据严格一致，在 Switch（切换）的那一刻，必须保证 Row Log 里的数据全部回放完毕。

• 理想情况：DDL 执行期间，业务写入很少。Row Log 只有几 KB。Step B 在毫秒级完成，用户无感知。
• 糟糕情况：DDL 跑了 1 个小时（全表重组）。这 1 小时内，业务疯狂写入（TPS 很高）。Row Log 积压了 500MB 甚至更多。
  • 到了 Commit 阶段，MySQL 获取写锁。
  • 开始回放这 500MB 的日志。
  • 整个回放过程，业务全部被堵在外面！
  • 如果回放需要 1 分钟，你的系统就挂了 1 分钟。

第一性原理视角：这就是 追赶模型 (Catch-up Model) 的固有缺陷。如果"增量产生的速度"接近"回放的速度"，或者存量太大，最后的同步阶段就会拉长阻塞窗口。

MySQL 其实做了一些优化（Iterative Apply），在 Execute 阶段末尾会尝试预先回放一部分日志。但为了保证最终一致性，最后的一小截尾巴，必须在写锁保护下回放。如果这截尾巴处理不掉，阻塞就不可避免。

3.1.5 磁盘空间爆满

DDL 执行期间的并发写入（Insert/Update/Delete）不会直接修改正在重建的表，而是暂存在 innodb_online_alter_log 中（内存+磁盘临时文件）。该日志的大小受到 innodb_online_alter_log_max_size 参数的硬性限制（默认仅 128MB）。

如果 DDL 耗时很久，或者业务写入量很大，填满了这个 Log。MySQL 会直接报错并回滚整个 DDL 操作，之前几个小时的 CPU/IO 资源白费。更严重的是，触发溢出的那个用户事务会被强制回滚，导致业务报错。

3.2 INSTANT

天下没有免费的午餐。INSTANT 算法虽然写得快，但它把成本转移到了读的时候。

3.2.1 读放大

• Copy/Inplace：数据在物理上已经重写好了。读取时，拿出来的就是完整的行。
• Instant：物理上的行数据可能只有 3 列，但表定义里有 4 列。每次 SELECT 读取该行时，InnoDB 引擎必须在内存中判断并加上缺失行的默认值。这增加了一点点 CPU 的开销（微乎其微，但存在）。

3.2.2 数据腐烂风险

如果你对一张表连续做了 50 次 Instant Add Column，再删几列。表里的数据行就会变得五花八门：有的行是 2023 年的版本，有的行是 2024 年的版本。

表结构的元数据会变得非常复杂，解析成本变高。

建议：如果一张表经过了极其频繁的 Instant 变更，在低峰期做一次 OPTIMIZE TABLE（这会强制触发 In-Place Rebuild）来把物理数据规整化，是有好处的。

4. 什么时候用哪个

什么时候 INSTANT，什么时候 INPLACE，什么时候 COPY？怎么判断呢？

判断这三者的核心逻辑，依然遵循第一性原理：看数据的物理存储是否需要改变。

MySQL 在执行 DDL 时，内部遵循一个懒惰原则：能偷懒就偷懒。优先级是： Instant (最懒/只改元数据) > In-Place (勤快/原地修整) > Copy (笨重/推倒重来)。

4.1 INSTANT (首选，快乐路径)

原理：只修改 .SDI (元数据) 或 数据字典。不触碰 B+ 树叶子节点的数据。

适用场景：

• 新增列 (Add Column)：
  • MySQL 8.0.12+ 支持（只能加在最后）。
  • MySQL 8.0.29+ 支持（任意位置 AFTER column）。
• 删除列 (Drop Column)：MySQL 8.0.29+ 支持。
• 重命名 (Rename)：表名、列名。
• 修改默认值 (Set/Drop Default)。
• 虚拟列 (Virtual Column)：添加或删除。
• 扩展 VARCHAR 长度：且扩展后字节数 < 256 (长度前缀保持 1 字节)。

4.2 INPLACE (主流，需谨慎)

原理：引擎层"原地"重建 B+ 树或索引树。利用 Row Log 记录执行期间的并发写入，最后回放。

适用场景：

• 添加索引 (Add Index)：最常见的场景。
• 删除索引 (Drop Index)：实际上改元数据即可，极快（但在官方分类中常归为 Inplace/Metadata）。
• 整理表碎片 (Optimize Table)：强制触发生效。
• 修改 Row Format：如 Compact -> Dynamic。

风险提示：虽不锁表，但消耗大量 IO 和 CPU，且最后 Apply Log 阶段如果追不上，可能短暂阻塞。务必避开业务高峰。

4.3 COPY (禁区，保底方案)

原理：数据的二进制存储格式发生了根本变化，引擎无法处理，必须由 Server 层建立新表，一行行读出来清洗、转换、写入。

适用场景：

• 修改字段数据类型：如 INT -> BIGINT, VARCHAR -> INT。

• 修改字符集：如 utf8 -> utf8mb4。

• 删除主键 (Drop Primary Key)。

• 扩展 VARCHAR 长度：当从 < 256 变为 ≥ 256 字节时（字节记录长度发生变化）。

  MySQL 8.0.29+ 的 INSTANT 甚至支持跨越 256 字节的 VARCHAR 扩展（只要不修改数据本身）。

• MySQL 5.6 之前的大部分操作。

警告：全程锁写入。线上大表严禁直接执行，必须使用 gh-ost 或 pt-osc。

4.4 最佳实践

不要让 MySQL 帮你选，显式指定算法，让潜在的 COPY 暴露出来：

-- 你的防御性写法
ALTER TABLE your_table
ADD INDEX idx_xxx (xxx),
ALGORITHM=INPLACE,  -- 强制要求原地执行
LOCK=NONE;          -- 强制要求不锁表

• 如果 MySQL 能够满足（是 Instant 或 Inplace），它就执行。
• 如果 MySQL 发现这事儿必须 COPY（要锁表），它会直接报错。

如下所示：

mysql> ALTER TABLE t_online_ddl MODIFY COLUMN val BIGINT, ALGORITHM=INPLACE, LOCK=NONE;

ERROR 1846 (0A000): ALGORITHM=INPLACE is not supported. Reason: Cannot change column type INPLACE. Try ALGORITHM=COPY.

5. 其他工具

原生 Online DDL 还是存在一切痛点，尤其是 INPLACE 和 COPY。所以出现了 pt-online-schema-change (pt-osc) 和 github-online-schema-migration-tool (gh-ost) 这两个工具。

它们的核心思想都是 影子表（Shadow Table）策略：建一张新表，同步数据，最后切换。

区别在于：怎么同步增量数据？

5.1 pt-osc

pt-osc 是 Percona Toolkit 的一部分，是老牌的方案。

核心原理

数据库触发器 (Database Triggers)。

工作流程：

1. 创建影子表：创建一个和原表结构一样的新表 _table_new。
2. 修改结构：在新表上执行 ALTER TABLE（比如加字段）。
3. 创建触发器 (关键)：在原表上创建 3 个触发器（AFTER INSERT, AFTER UPDATE, AFTER DELETE）。这意味着：每当业务向原表写入一行数据，MySQL 会自动触发一个动作，把这行数据的变更同步写入到新表中。
4. 拷贝存量数据：工具开始分批次（Chunk）把原表的历史数据 INSERT IGNORE 到新表中。
5. 原子切换：数据拷贝完后，利用 RENAME TABLE 原子操作，把原表改名，新表上位。

优点：

• 可靠：基于数据库内部机制，数据一致性强。
• 兼容性：支持所有 Binlog 格式（Statement/Row/Mixed）。

缺点：

• 同步阻塞：触发器是和业务 SQL 在同一个事务 里执行的。
  • 如果你的业务 SQL 执行需 1ms，加上触发器写新表可能变成 2ms。这直接导致写性能下降。
  • 如果触发器写新表失败（比如锁等待），你的业务 SQL 也会回滚失败！
• 元数据锁 (MDL)：创建和删除触发器的瞬间，需要锁表（MDL 写锁），在高并发下可能导致拥堵。

5.2 gh-ost

核心原理

模拟从库 (Binlog Simulation)。

GitHub 在被 pt-osc 的触发器搞了几次故障后，开发了 gh-ost。它彻底抛弃了触发器。

工作流程：

1. 创建影子表：同上，建新表、改结构。
2. 伪装成从库：gh-ost 进程把自己伪装成一个 MySQL Slave，连接到 Master（或者真实的 Slave）。它请求 Dump Binlog 流。
3. 监听 Binlog：业务在原表写入数据，产生 Binlog。gh-ost 读取 Binlog，将解析出来的 Binlog 事件（Insert/Update/Delete），转换成 SQL 语句，并在影子表上回放。
4. 拷贝存量数据：同上，分批拷贝历史数据。
5. 原子切换：因为 gh-ost 是异步的，所以切换的时候必须有"同步"辅助方案。所以它使用一种特殊的机制（Cut-over）进行表名切换。

Cut-over 过程：

1. 制造阻塞：gh-ost 会建立一个连接 C1，执行 LOCK TABLES tbl WRITE;。这时候，所有业务线程想写这张表，都会被堵塞住（Blocked）。原表被冻结了，不再会有新数据写入（这就消除了追不上的问题）。
2. 发起改名：gh-ost 建立另一个连接 C2，执行 RENAME TABLE tbl TO tbl_old, ghost_tbl TO tbl;。这条 SQL 也会被 C1 的锁堵塞住，卡在 MySQL 的执行队列里。
3. 插队机制：此时，MySQL 的锁等待队列里可能排着一堆请求。但是！RENAME 等 DDL 操作的优先级高于 INSERT/UPDATE 等 DML 操作。 所以，虽然大家都在排队，但 MySQL 会把 C2 的 Rename 请求提到最前面（仅次于持有锁的 C1）。
4. 瞬间释放：gh-ost 确认 C2 已经乖乖排在队首后，C1 执行 UNLOCK TABLES;。锁一释放，排在队首的 C2（Rename）瞬间执行。因为 C2 优先级最高，没有任何业务写入能插到 C1 释放和 C2 执行这两个动作中间。

优点：

• 解耦：gh-ost 是在应用层（或者说外部工具层）回放数据。它和业务的写操作完全异步。
• 轻量：业务 SQL 写入原表后就结束了，不需要等新表写入。不影响业务响应时间。
• 可暂停/限速：这是 gh-ost 的杀手锏。如果发现数据库负载高了，gh-ost 可以瞬间暂停读取 Binlog，甚至在拷贝数据的过程中随时停下来睡觉。这是触发器做不到的。

缺点：

• 依赖 Row 格式：必须开启 Binlog row 模式（现代 MySQL 标配）。
• 复杂性：架构比 pt-osc 复杂，需要处理 Binlog 解析。

6. 总结

回到第一性原理：Online DDL 的本质，是在"修改表结构"与"保持业务可用"之间寻找平衡点。

无论哪种算法，MDL 锁始终是最隐蔽的杀手。一个长事务就能让整个 DDL 链路瘫痪。

• INPLACE：主从延迟、Buffer Pool 污染、Apply Log 阻塞、磁盘撑爆。
• INSTANT：读放大、数据腐烂（频繁变更后需定期 OPTIMIZE）。

工具选型：

生产环境黄金法则：

1. 永远显式指定算法：ALGORITHM=INPLACE, LOCK=NONE，让潜在的 COPY 暴露出来。
2. 执行前检查长事务：SELECT * FROM information_schema.processlist WHERE TIME > 10;
3. 避开高峰期：再 Online 的 DDL，也会消耗资源。
4. 大表用工具：超过 100 万行，优先考虑 gh-ost。
5. 监控主从延迟：Seconds_Behind_Master 是你的生命线。

一句话总结：

Online DDL 不是银弹。它只是把"长时间锁表"变成了"短时间锁表 + 长时间后台作业"。理解它的边界，才能用好它。

要从根本上理解 MySQL 的锁，必须理解它在 内存（RAM） 和 数据结构（B+Tree） 层面是如何运作的。

可以将 MySQL（主要是 InnoDB 引擎）的锁机制拆解为五个层次：

1. 锁的结构：锁在内存里面到底长什么样？（打破"锁是数据行上的标记"这一误区）
2. 锁的对象：锁是加在什么对象上？（打破"锁行"的字面理解）
3. 锁的类型：读写冲突怎么解决？
4. 锁的粒度：如何提高并发效率？（意向锁的由来）
5. 锁的算法：如何解决幻读？（Gap Lock 的由来）

1.1 锁的结构：锁在内存里面到底长什么样？

提示

核心认知：锁不是数据行（Row）上的一个字段，而是内存中独立的数据结构。

很多初学者认为锁是磁盘上每一行数据里的一个 is_locked 标记。这是错的。如果是这样，锁事务回滚时还需要去修改磁盘数据，IO 开销太大。

在 InnoDB 内部，锁通过 Lock System (lock_sys) 进行管理，是一个巨大的 Hash Table。

InnoDB 不会为每一行数据创建一个锁对象（Lock Struct），那是巨大的内存浪费。它是按**页（Page）**来管理的。

struct lock_t {
    trx_t* trx;       // 属于哪个事务
    ulint  space_id;  // 表空间 ID
    ulint  page_no;   // 页号
    uint32 type_mode; // 锁类型 (Shared/Exclusive) | 锁模式 (Rec/Gap/Next-Key)
    // ---------------------------------------------
    // 重点来了：这里没有 Row ID，而是一个 Bitmap
    // ---------------------------------------------
    uint8  bitmap[];  // 位图！映射这一页上的物理记录
};

• 一个 lock_t 结构体对应"一个事务"在"一个数据页"上的锁信息。
• 在这个结构体后面，跟着一个 Bitmap（位图）。
• 如果一个页面有 100 条记录，位图里就有对应的一堆 Bit。如果你执行 UPDATE... WHERE id < 1000，锁住了这页的 50 行记录，InnoDB 不需要创建 50 个锁对象，只需要在一个锁对象的位图中把这 50 个 bit 置为 1。这就是为什么 MySQL 宣称它支持行级锁且开销极小，即便你锁住了 100 万行，只要它们集中在几千个 Page 里，内存消耗依然很小。

1.2 锁的对象：锁是加在什么对象上？

提示

核心认知：InnoDB 的行锁，永远是加在索引（Index）上的。

这是理解所有复杂锁问题的总钥匙。

• 如果你通过主键更新：锁加在聚簇索引（Clustered Index）的记录上。
• 如果你通过二级索引更新：锁先加在二级索引（Secondary Index）的记录上，然后回表，去锁聚簇索引上的记录。
• 如果你不走索引：因为 MySQL 必须扫描全表才能找到你要更新的行。它会扫描一条、锁一条（在聚簇索引上）。虽然在 RC 隔离级别下 MySQL 有优化（不匹配的行会释放锁），但在 RR 级别下，它会把所有扫描过的记录以及记录之间的间隙全锁上。这在效果上等同于锁表。

1.3 锁的类型：读写冲突怎么解决？

MySQL InnoDB 有 7 种锁：

1. 共享锁（S 锁）和排他锁（X 锁）
2. 意向锁（Intension Locks）
3. 记录锁（Record Locks）
4. 间隙锁（Gap Locks）
5. 临键锁（Next-Key Locks）
6. 插入意向锁（Insert Intension Locks）
7. 自增锁（Auto-Inc Locks）

MDL 是 MySQL Server 层面的锁。

可以从 2 个维度进行理解：

• 锁的粒度：锁表、锁行、锁区间
• 锁的模式：共享、排他、意向

1.4 锁的粒度：如何提高并发效率？

如果表里有 100 万行数据，事务 A 锁住了其中第 999 行（行锁）。此时事务 B 想申请整张表的写锁（表锁），B 怎么知道能不能加锁？

• 笨办法：B 遍历这 100 万行，看有没有人加了行锁。-> 效率极低，不可接受。
• 第一性原理优化：在层级结构中，下层有锁，上层必须有标记。

意向锁（Intention Lock, IS/IX） 这实际上是表级锁，它的作用只是**"信号灯"**：

• 规则：事务 A 在给第 999 行加 行级排他锁 (X) 之前，必须先给这张表挂一个 意向排他锁 (IX)。
• 效果：事务 B 来看一眼表门头，发现有 IX 标记，就知道表里有人在干活，于是 B 阻塞等待。B 不需要遍历全表，效率提升为 O(1)。

1.5 锁的算法：如何解决幻读？

为了防止幻读（Phantom Read），InnoDB 发明了复杂的锁算法，我们需要把数据想象成 B+ 树叶子节点上的一条有序链表。

假设表中现在的 ID 有：10, 20, 30。

Record Lock（记录锁）：

• 定义：仅仅锁住索引记录本身。
• 场景：精准命中。例如 SELECT * FROM t WHERE id = 10 FOR UPDATE;。
• 内存表现：Bitmap 中对应 id=10 的那个 bit 被置位。

Gap Lock（间隙锁）：

• 定义：锁住两个索引记录之间的空隙，不包含记录本身。
• 目的：纯粹是为了通过禁止插入（insert）来防止幻读。
• 场景：SELECT * FROM t WHERE id = 15 FOR UPDATE;。
• 范围：例如 (10, 20)。这意味着你不能插入 11,12... 19。
• 重要特性：Gap Lock 之间是兼容的！事务 A 可以对 (10, 20) 加 Gap Lock，事务 B 也可以对 (10, 20) 加 Gap Lock。为什么？因为它们的目的都是阻止别人插入，不冲突。真正冲突的是 Insert Intention Lock（插入意向锁）。

Next Key Lock（临键锁）：

• 定义：Record Lock + Gap Lock。即锁住记录本身，也锁住它前面的空隙。
• 默认行为：在 RR（Repeatable Read）隔离级别下，InnoDB 对于范围查询或非唯一索引的等值查询，默认加 Next-Key Lock。
• 场景：SELECT * FROM t WHERE id > 10 FOR UPDATE;
• 左开又闭：在 10, 20, 30 的例子中，扫描到 20 时，加 Next-Key Lock (10, 20]；扫描到 30 时，加 Next-Key Lock (20, 30]。扫描完 30 后，指针继续向后，发现没有真实记录了，碰到了 B+ 树页面的 Supremum 伪记录（代表无穷大）。加 Next-Key Lock (30, ∞)。综合起来是锁住了 (10, +∞)。它不仅仅是锁间隙，也会锁住记录。这意味着：你不能修改 20，也不能在 10 到 20 之间插入数据 。

Insert Intension Lock（插入意向锁）：

• 定义：这其实是一种特殊的 Gap Lock，但在代码里它叫"插入意向"。
• 触发：当执行 INSERT 时，如果目标位置已经被别的事务加了 Gap Lock，插入操作就会进入等待，并在这个间隙上生成一个"插入意向锁"。
• 死锁之源：很多死锁都是因为两个事务持有 Gap Lock，然后又都想在这个 Gap 里插入数据（申请插入意向锁），结果互相等待。

Metadata Lock（元数据锁）：

• 作用：保护表结构。当你执行 SELECT 或 UPDATE 时，自动加 MDL 读锁。当你执行 ALTER TABLE 时，需要 MDL 写锁。
• 阻塞逻辑：读写互斥。这意味着，只要有一个长事务（哪怕只是 SELECT）没提交，持有 MDL 读锁，后续的 ALTER TABLE 就会被卡住，而 ALTER TABLE 卡住后，后面所有的 SELECT/UPDATE 也会被卡住（形成锁队列堆积）。这就是著名的"MDL 暴击"。

2. 分析模板

当一个事务执行 SQL 时，InnoDB 锁引擎会遵循以下判定树：

针对 RR 隔离级别，我们要秉持三大分析原则：

1. 原则一： 加锁的基本单位是 Next-Key Lock（左开右闭）。

2. 原则二： 查找过程中，访问到的对象才会加锁。

   • 如果 SQL 走了二级索引，二级索引会被强力锁定（Next-Key + Gap）。

   • 回表时，主键索引只加 Record Lock。

3. 原则三（优化）： 索引上的等值查询：

   • 唯一索引：Next-Key Lock 退化为 Record Lock（因为不用担心那个值后面插进一样的）。

   • 非唯一索引：向右扫描到第一个不符合条件的记录，该记录加 Gap Lock（不锁记录本身，只锁它前面的空隙）。

3. 例题分析

提示

表结构：

CREATE TABLE students (
  id INT PRIMARY KEY,       -- 主键
  score INT,                -- 非唯一索引
  name VARCHAR(20),         -- 无索引
  INDEX idx_score (score)
) ENGINE=InnoDB;

现有数据：

• id=1, score=10, name='A'
• id=5, score=20, name='B'
• id=10, score=30, name='C'

当前事务执行：

-- 隔离级别：RR
DELETE FROM students WHERE score = 20;

请分析以下三个核心问题：

1. 二级索引锁： 在 idx_score 这棵 B+ 树上，锁住了哪些范围？（请用准确的区间表示，如 (10, 20]）
2. 聚簇索引锁（回表）： 在 PRIMARY KEY (id) 这棵 B+ 树上，锁住了哪些 ID？有没有加 Gap Lock？
3. 并发测试： 此时，另一个事务想执行 INSERT INTO students (id, score, name) VALUES (2, 15, 'D');，能否成功？为什么？

问题一：idx_score 到底锁了什么？

数据 (id, score): (1, 10), (5, 20), (10, 30)

SQL: DELETE FROM students WHERE score = 20; (隔离级别 RR)

InnoDB 的逻辑是：我要锁住 score=20，并且防止别人在 score=20 的前后插入数据。

• 命中记录： 首先找到 (5, 20) 这条记录。加上 Next-Key Lock。
  • 范围一： (10, 20]。
  • 注意： 这里锁的是 score 的范围，配合主键 id。确切地说，它锁的是 (score=10, id=1) 到 (score=20, id=5) 之间的间隙，加上 (20, 5) 这条记录本身。
• 向右探测：
  • 为了防止幻读（比如别人插入一个 score=20 的新行），InnoDB 必须继续向右扫描，直到遇到第一条不满足条件的记录为止。
  • 它向右看到了 (10, 30)。
  • 因为 30!= 20，扫描结束。但是，为了封锁 20 之后到 30 之前的空隙，它必须在 (10, 30) 这条记录上加一个 Gap Lock。
  • 范围二： (20, 30)。

结论： 在 idx_score 索引上，实际锁住的范围是 (10, 30)。

• score 在 (10, 20] 的不能插。
• score 在 (20, 30) 的也不能插。

问题二：聚簇索引 (PRIMARY KEY) 锁了什么？

二级索引回表锁主键时，只加 Record Lock，不加 Gap Lock。

原因： Gap Lock 是为了防止"在范围内插入"。二级索引上的 Gap Lock 已经足够阻止 score=20 的插入了（因为插入必须维护所有索引）。主键上再加 Gap Lock 是多余的，且会极大地降低并发（会误伤 id 邻近但 score 无关的行）。

所以主键 id=5 上只有 Record Lock (X 锁)。

问题三：并发测试结果分析

SQL: INSERT INTO students (id, score, name) VALUES (2, 15, 'D');

• 我们要插入 score=15。
• 检查 idx_score 锁范围：15 落在 (10, 20] 这个区间内。
• 结果： 被 idx_score 的 Next-Key Lock 阻塞。

参考

• MySQL Locks: A Comprehensive Guide 101
• Deep Dive into MySQL - Implicit Locks
• 深入浅出 MySQL 8.0 lock_sys 锁相关优化

1. 极致节省内存：能省就省，既压缩结构本身，也采用动态或共享等机制确保每一位（bit）都物尽其用。
2. 最大化 CPU 缓存友好：优先用一块连续小内存管理数据，降低指针跳转和碎片化，以提升访问速度和 CPU 缓存命中率。

这两点支撑着 Redis 各类数据类型的演进路线与编码选择。

版本声明：Redis8.4.0

0. redisObject

在深入具体类型之前，我们先对 Redis 对象头 redisObject 做一个简单的了解，因为 Redis 中的所有 Key 和 Value，在底层都是一个 redisObject 结构体。这是 Redis 多态的基石。redisObject 的定义位于 src/server.h

#define LRU_BITS 24
#define OBJ_REFCOUNT_BITS 30

struct redisObject {
    unsigned type:4;
    unsigned encoding:4;
    unsigned lru:LRU_BITS; /* LRU time (relative to global lru_clock) or
                            * LFU data (least significant 8 bits frequency
                            * and most significant 16 bits access time). */
    unsigned iskvobj : 1;   /* 1 if this struct serves as a kvobj base */
    unsigned expirable : 1; /* 1 if this key has expiration time attached.
                             * If set, then this object is of type kvobj */
    unsigned refcount : OBJ_REFCOUNT_BITS;
    void *ptr;
};

• type: 逻辑数据类型（String、List、Hash、Set、ZSet）。
• encoding: 物理编码格式（int、row、listpack、skiplist）。
• lru: 淘汰策略数据，如果是 LRU 模式，则存储最后一次访问的时间戳（秒级）。如果是 LFU 模式，则存储方法时间和访问频率。当内存达到 maxmemory 时，Redis 根据此字段决定淘汰哪个 Key。
• iskvobj: Redis 8.0 的新特性。1 表示该对象是一个 kvobj （键值对象）的一部分，意味着 Key、Value 和元数据在内存中是紧凑/内嵌存储的。这样可以消除"键值分离"带来的指针跳转，提升 CPU 缓存命中率。
• expirable: Redis8.0 的新特性。1 表示该 Key 设置了过期时间。这提供了一条快速通道，访问时若为 0，直接跳过查询 expires 哈希表的步骤，节省昂贵的哈希查找开销。
• refcount: 记录有多少个指针引用了该对象。用于内存管理和对象共享（主要用于小整数共享）。当计数降为 0 时，回收内存。这里使用了位域压缩以节省空间。
• ptr: 指向实际存储数据的内存地址（如 SDS、Dict、Quicklist 的地址）。特别地，如果 encoding 是 INT，这里直接存储整数值本身，不再是指针。

上述多个字段，最重要的就是 type 和 encoding。总的来说，type 决定了它对外声称是什么（比如 Hash），而 encoding 决定了它在内存里到底怎么存（比如是压缩列表还是哈希表）。优化 Redis 内存的核心，就是想办法让它保持在轻量级的 encoding 上。

1. String

String 是 Redis 最基本的数据类型，也是所有 Key 的类型。

1.1 核心操作

# 基础操作
SET key value                 # 设置键值对
GET key                       # 获取值
DEL key                       # 删除键
EXISTS key                    # 检查键是否存在

# 批量操作
MSET key1 value1 key2 value2  # 批量设置
MGET key1 key2 key3           # 批量获取

# 数值操作
INCR key                      # 原子递增 +1
DECR key                      # 原子递减 -1
INCRBY key increment          # 按指定值递增
DECRBY key decrement          # 按指定值递减

# 字符串操作
APPEND key value              # 追加字符串
STRLEN key                    # 获取字符串长度
GETRANGE key start end        # 获取子字符串（闭区间）
SETRANGE key offset value     # 从指定偏移量设置字符串

# 过期时间
SETEX key seconds value       # 设置带过期时间的键
TTL key                       # 查看剩余生存时间
EXPIRE key seconds            # 为已有键设置过期时间

常见使用场景：

• 缓存层：存储 JSON 序列化后的对象，如用户信息、商品详情
• 计数器：文章阅读数、点赞数、库存数量等原子计数场景
• 分布式锁：SET key value NX EX 30 实现简单的分布式锁
• 限流器：使用 INCR 和 EXPIRE 实现滑动窗口限流
• 会话管理：存储用户 session 信息，配合过期时间自动清理

1.2 底层原理

Redis 没有直接使用 C 语言的字符串 char*，而是自己封装了 SDS（Simple Dynamic String），而且还进一步分成了 sdshdr5、sdshdr8、sdshdr16、sdshdr32 和 sdshdr64。其核心目的是根据字符串的长度，使用不同大小的头部，从而进一步压缩内存的使用。

SDS 的定义位于 src/sds.h。

/* Note: sdshdr5 is never used, we just access the flags byte directly.
 * However is here to document the layout of type 5 SDS strings. */
struct __attribute__ ((__packed__)) sdshdr5 {
    unsigned char flags; /* 3 lsb of type, and 5 msb of string length */
    char buf[];
};
struct __attribute__ ((__packed__)) sdshdr8 {
    uint8_t len; /* used */
    uint8_t alloc; /* excluding the header and null terminator */
    unsigned char flags; /* 3 lsb of type, 5 unused bits */
    char buf[];
};
struct __attribute__ ((__packed__)) sdshdr16 {
    uint16_t len; /* used */
    uint16_t alloc; /* excluding the header and null terminator */
    unsigned char flags; /* 3 lsb of type, 5 unused bits */
    char buf[];
};
struct __attribute__ ((__packed__)) sdshdr32 {
    uint32_t len; /* used */
    uint32_t alloc; /* excluding the header and null terminator */
    unsigned char flags; /* 3 lsb of type, 5 unused bits */
    char buf[];
};
struct __attribute__ ((__packed__)) sdshdr64 {
    uint64_t len; /* used */
    uint64_t alloc; /* excluding the header and null terminator */
    unsigned char flags; /* 3 lsb of type, 5 unused bits */
    char buf[];
};

我们重点关注 3 个字段：

• len: 已用长度。
• alloc: 分片的总内存大小（不包括头部和末尾的 \0）。
• buf[]: 实际存储字符数据的柔性数组。

即便都是 String，Redis 为了省内存，也使用了 3 种不同的编码格式：

[!note]

💡 44 字节怎么来的？ redisObject (16B) + SDS 头 (3B) + \0 (1B) = 20B。 内存分配器（如 jemalloc）通常分配 64B 的块。 64B - 20B = 44B。刚好填满一个内存块，不浪费。

2. List

List 在 Redis 中逻辑上是一个 双向链表。这意味着：

• 头尾操作极快：LPUSH/RPOP 是 O(1)。
• 随机访问极慢：LINDEX 是 O(N)。（千万别把它当数组用！）

2.1 核心操作

# 头部操作
LPUSH key value1 value2       # 从左侧头部推入元素（栈：先进后出）
RPUSH key value1 value2       # 从右侧尾部推入元素（队列：先进先出）
LPOP key                      # 从左侧头部弹出元素
RPOP key                      # 从右侧尾部弹出元素
LPOP key count                # 批量从左侧弹出多个元素

# 阻塞操作（重要）
BLPOP key1 key2 timeout       # 阻塞式左弹出，用于消息队列
BRPOP key1 key2 timeout       # 阻塞式右弹出，用于消息队列
BLMOVE source destination timeout LEFT|RIGHT LEFT|RIGHT  # 阻塞式移动元素

# 查询操作
LLEN key                      # 获取列表长度
LRANGE key start end          # 获取指定范围内的元素（支持负数索引）
LINDEX key index              # 获取指定索引的元素
LPOS key value [COUNT count]  # 查找元素位置

# 修改操作
LSET key index value          # 设置指定索引的值
LINSERT key BEFORE|AFTER pivot value  # 在指定元素前/后插入新元素
LTRIM key start end           # 修剪列表，只保留指定范围内的元素

# 移动操作
RPOPLPUSH source destination  # 从 source 右弹出，destination 左推入
LMOVE source destination LEFT|RIGHT LEFT|RIGHT  # 灵活的元素移动

常见使用场景：

• 消息队列：LPUSH/BRPOP 实现简单的生产者-消费者模式，BLPOP 提供阻塞式消费
• 最新动态：用户动态、新闻列表使用 LPUSH/LRANGE 0 10 获取最新 10 条
• 任务队列：异步任务处理，配合 RPOPLPUSH 实现可靠队列（失败重试）
• 数据分页：存储分页数据，使用 LRANGE 实现高效分页查询
• 排行榜：结合 LPUSH/LTRIM 维护固定大小的排行榜或热榜
• 限流队列：实现滑动窗口限流，使用 LLEN 监控队列长度

2.2 底层原理

typedef struct listNode {
    struct listNode *prev;
    struct listNode *next;
    void *value;
} listNode;

typedef struct listIter {
    listNode *next;
    int direction;
} listIter;

typedef struct list {
    listNode *head;
    listNode *tail;
    void *(*dup)(void *ptr);
    void (*free)(void *ptr);
    int (*match)(void *ptr, void *key);
    unsigned long len;
} list;

Redis List 的底层实现经历了三次大的变革：

2.2.1 LinkedList

我们先来看 LinkedList，这是最直觉的实现：

          +------+     +------+     +------+
... <---- | prev | <-> | prev | <-> | prev | ----> ...
          | data |     | data |     | data |
... <---- | next | <-> | next | <-> | next | ----> ...
          +------+     +------+     +------+

优点：完美的 O(1) 头尾操作

缺点：

• 高昂的内存开销：prev 和 next 指针占据了大量内存，如果 data 不够大，那性价比就很低了。
• 糟糕的 CPU 缓存局部性：链表的节点在内存中是离散分布的。当 CPU 遍历链表时，指针跳转的行为极易导致 CPU Cache Miss。

2.2.2 Ziplist

为了克服 linkedlist 的双重代价，Redis 的设计者们创造了一种极其紧凑的数据结构：压缩列表 (ziplist)。

ziplist 的核心思想是，用一块连续的、完整的内存块来存储所有元素，从而彻底消除指针开销，并最大化利用 CPU 缓存。

<zlbytes> <zltail> <zllen> <entry_1> <entry_2> ... <entry_N> <zlend>

• <zlbytes>: 整个 ziplist 占用的总字节数。
• <zltail>: 到最后一个 entry 的偏移量，用于快速定位到表尾。
• <zllen>: entry 的数量。
• <entry>: 真正的列表元素，每个 entry 也是变长的。
• <zlend>: 特殊的结束标记 0xFF。

ziplist 的精髓在于 entry 的设计。每个 entry 的头部会记录前一个 entry 的长度 (prev_len)，这使得 ziplist 可以从后向前遍历。

优点：内存占用小且对 CPU 缓存友好。

缺点：级联更新。因为 entry 包含了前面节点的信息（prev_len），所以前面的节点发生变化时，很容易造成后面节点的级联更新。

2.2.3 Quicklist

既然 linkedlist 和 ziplist 各有优劣，能否将它们结合起来，取其精华，去其糟粕？快速列表 (quicklist) 应运而生，并从 Redis 3.2 开始成为 List 的默认实现。

quicklist 的本质，就是一个由 ziplist（或后来的 listpack）节点组成的双向链表。

+----------------+     +----------------+     +----------------+
| quicklistNode  | <-> | quicklistNode  | <-> | quicklistNode  |
| (ziplist/pack) |     | (ziplist/pack) |     | (ziplist/pack) |
+----------------+     +----------------+     +----------------+
         ^                    ^                      ^
         |                    |                      |
   [ e1, e2, e3 ]       [ e4, e5 ]           [ e6, e7, e8, e9 ]

它在宏观上是一个 linkedlist，保持了 O(1) 的头尾插入性能和灵活性。而在微观上，每个节点内部是一个 ziplist 或 listpack，存储了多个元素，极大地节省了内存，并提升了缓存局部性。quicklist 通过将连锁更新的风险限制在一个个独立的小节点内部，完美地规避了 ziplist 最大的风险。

2.2.4 Listpack

quicklist 虽然将 ziplist 的缺点限制在了一个节点之间，但是其缺点依旧存在，为此，紧凑列表(listpack) 诞生了。它去掉了 prev_len，改为在当前节点内部记录自己的长度 back-len（并且经过特殊编码支持反向解码）。修改当前节点，再也不会影响下一个节点的头部的长度了。

一个 listpack 结构如下：

重点在于这个 back-len，它等于该条目自身的 encoding-type 和 element-data 两部分加起来的长度（我们称之为"部分长度"）。当需要从后向前遍历时，解析器会从前一个条目的尾部，反向解析出这个"部分长度"，然后再动态计算出 back-len 字段自身的长度，两者相加得到前一个条目的总长度，从而实现精确的回溯跳转。

3. Hash

Hash 是一个 String 类型的 Field 和 Value 的映射表。

3.1 核心操作

# 基础操作
HSET key field value          # 设置字段值（可以同时设置多个字段）
HGET key field                # 获取字段值
HMSET key field1 value1 field2 value2  # 批量设置字段
HMGET key field1 field2 field3  # 批量获取字段
HGETALL key                   # 获取所有字段和值
HDEL key field1 field2        # 删除指定字段
HEXISTS key field             # 检查字段是否存在

# 字段操作
HLEN key                      # 获取字段数量
HKEYS key                     # 获取所有字段名
HVALS key                     # 获取所有字段值
HSTRLEN key field             # 获取字段值的字符串长度

# 数值操作
HINCRBY key field increment   # 字段值按指定整数递增
HINCRBYFLOAT key field increment  # 字段值按指定浮点数递增

# 高级操作（Redis 6.2+）
HSETNX key field value        # 仅当字段不存在时设置
HRANDFIELD key [count [WITHVALUES]]  # 随机获取字段

常见使用场景：

• 对象缓存：存储用户信息、商品属性等结构化数据，如 user:1001 {name: "张三", age: 25, city: "北京"}
• 计数器集合：文章的多维统计，如 article:1001 {views: 1000, likes: 50, comments: 20}
• 配置管理：系统配置、用户偏好设置等键值对集合
• 购物车：简化版购物车实现，cart:1001 {item_001: 2, item_005: 1}
• 会话管理：比 String 更灵活的 session 存储，支持细粒度更新
• 实时统计：网站在线用户统计、API 调用次数等分组统计场景
• 标签系统：文章标签管理，tags:article_001 {tech: 1, redis: 1, database: 1}

3.2 底层原理

Hash 的底层实现有两种：Listpack (原 Ziplist) 和 Hashtable。

[!NOTE]

💡 关键点：Hash 的 Listpack 布局 和 List 不同，Hash 在 Listpack 中存储时，是成对出现的。 [ Key1 | Val1 | Key2 | Val2 | ... ] 查找时，Redis 从头遍历，找到 Key 后，紧接着取下一个 Entry 就是 Value。

listpack 的存储结构在 List 我们已经介绍过了，这里就介绍 Hash 的默认编码格式 hashtable。构成 Redis 哈希表的核心是 dict 及其节点 dictEntry 结构，源码可看：src/dict.c。它不仅支撑了 Redis 的 Hash 数据类型，更重要的是，Redis 整个数据库（KV 空间）本身就是一个巨大的 Dict。

struct dictEntry {
    struct dictEntry *next;  /* 指向下一个节点，解决哈希冲突 */
    void *key;               /* 键 */
    union {                  /* 值（使用联合体优化内存） */
        void *val;			/* 通常指向一个 redisObject */
        uint64_t u64;		/* 无符号整数 */
        int64_t s64;		/* 有符号整数 */
        double d;				/* 浮点数 */
    } v;
};

struct dict {
    dictType *type;          /* 类型特定函数 */

    dictEntry **ht_table[2]; /* 两个哈希表，平时只用[0]，迁移时共用[0]和[1] */
    unsigned long ht_used[2];/* 两个表已有的节点数量 */

    long rehashidx;          /* Rehash 进度索引 */

    unsigned pauserehash;    /* Rehash 暂停标志 */

    /* 紧凑排列的小变量，优化内存填充 */
    signed char ht_size_exp[2]; /* 大小的指数 (size = 1 << exp) */
    signed pauseAutoResize: 15; /* 禁止自动扩容标志 */
    unsigned useStoredKeyApi: 1;
    void *metadata[];           /* 变长数组，用于存储额外元数据 */
};

• 拉链法 (Chaining)：dictEntry 中的 next 指针，是 Redis 解决哈希冲突的基础手段，构建了 bucket 内的单向链表。
• 双表架构 (Double Tables)：ht_table[2] 是 Redis 实现无阻塞扩容的物理基础。通常情况下，只有 ht_table[0] 在工作，ht_table[1] 是空的。当 ht[0] 满了需要扩容（或缩容）时，Redis 并不是在原表上操作，而是先给 ht[1] 分配更大的空间（两倍），然后将 ht[0] 的数据慢慢搬到 ht[1]。等搬完后，删除 ht[0]，把 ht[1] 变成新的 ht[0]。
• 渐进式 Rehash (Incremental)：rehashidx 记录当前搬迁到了 ht[0] 的第几个 bucket（数组下标）。每次对字典进行增删改查（CRUD）时，顺便把 rehashidx 位置的一个 bucket 搬到 ht[1]，然后 rehashidx++。不用担心没有请求时就一直不迁移，后台有定时任务 serverCron 会包含 rehash 操作用于辅助迁移，以避免这个问题。

4. Set

Set 是一个无序、唯一的字符串元素集合。其核心价值在于高效的成员关系判断（SISMEMBER）和服务器端的集合运算（SINTER, SUNION, SDIFF）。

4.1 核心操作

# 基础操作
SADD key member1 member2        # 添加成员到集合
SREM key member1 member2        # 从集合中删除成员
SPOP key [count]                # 随机弹出并删除成员
SRANDMEMBER key [count]         # 随机获取成员（不删除）
SCARD key                       # 获取集合成员数量
SMEMBERS key                    # 获取所有成员

# 成员判断
SISMEMBER key member            # 检查成员是否存在
SMISMEMBER key member1 member2  # 批量检查成员是否存在

# 集合运算（重要）
SINTER key1 key2 key3           # 计算多个集合的交集
SINTERCARD numkeys key1 key2 [key3...] [LIMIT limit]  # 计算交集的基数
SINTERSTORE destination key1 key2  # 计算交集并存储到新集合
SUNION key1 key2 key3           # 计算多个集合的并集
SUNIONSTORE destination key1 key2  # 计算并集并存储到新集合
SDIFF key1 key2 key3            # 计算差集（key1 - key2 - key3）
SDIFFSTORE destination key1 key2  # 计算差集并存储到新集合

# 集合操作（Redis 6.2+）
SADD key member1 member2 [NX|XX]  # NX:仅添加不存在的，XX:仅添加已存在的
SMOVE source destination member   # 将成员从源集合移动到目标集合

常见使用场景：

• 标签系统：文章标签、用户兴趣标签，SINTER 找共同标签，SUNION 找所有标签
• 共同好友：社交网络中找出两个用户的共同好友，SINTER user:1001:friends user:1002:friends
• 去重统计：访问用户去重、搜索关键词去重，利用 Set 的天然去重特性
• 权限控制：角色权限管理，SADD role:admin user,delete,create
• 推荐系统：基于共同兴趣的用户推荐，SINTER user:1001:likes user:1002:likes
• 黑名单/白名单：IP 黑白名单、用户黑名单等，SISMEMBER 快速判断
• 抽奖活动：SRANDMEMBER 随机抽取中奖用户，SPOP 抽取并移除避免重复中奖
• 在线用户：实时在线用户集合，SADD 用户上线，SREM 用户下线

4.2 底层原理

Set 同样采用了双重编码策略，分别是 hashtable 和 intset。

其中 hashtable 完全复用上文所述的 dict 结构。集合中的每个元素被存储为 dictEntry 中的 key，而 union v (值) 部分则被忽略（统一设为 NULL）。这种设计直接利用了 dict 键的唯一性来保证 Set 元素的唯一性，并继承了其 O(1) 的查找性能。

当一个 Set 满足以下两个条件时，会采用 intset 编码：

1. 集合中所有元素均为整数。
2. 元素数量未超过 set-max-intset-entries 配置项的阈值（默认为 512）。

intset 是一种自适应整数编码的有序数组。它可以根据存入整数的范围，将内部存储格式动态升级为 int16_t, int32_t 或 int64_t，以最小的内存空间存储数据。成员查找通过二分搜索算法实现。它的定义位于 src/intset.h。

#define INTSET_ENC_INT16 (sizeof(int16_t))
#define INTSET_ENC_INT32 (sizeof(int32_t))
#define INTSET_ENC_INT64 (sizeof(int64_t))

typedef struct intset {
    uint32_t encoding;  // 当前元素编码宽度：16/32/64 位
    uint32_t length;    // 元素个数
    int8_t contents[];  // 紧凑存放有序整数
} intset;

升级机制：

• 如果当前存的都是小整数（如 1, 2, 100），数组用 int16 存储。

• 当你插入一个大整数（如 65536，超出了 int16 范围），Redis 会将整个数组的所有元素升级为 int32，并重新分配内存。注意：IntSet 不支持降级。一旦升级，这就回不去了。

• 如果你向一个 IntSet 插入了一个字符串（比如 "a"），即使之前存的全是整数，Redis 也会立刻将其转换为 Hashtable。且不可逆：就算你后来把 "a" 删了，它也不会变回 IntSet。

这里简单补充一下 int8_t contents[] 的含义，因为笔者对 C/C++ 并不熟悉，所以一开始阅读这个代码定义的时候还觉得很奇怪？

—— 为什么 int8_t[] 类型的数组可以存放 int16/int32/int64 的元素？

在 C99 标准中，结构体最后一个元素如果是未知大小的数组（如 contents[]），被称为柔性数组成员。contents 本身不占用 intset 结构体的大小（或者只被视为一个偏移量标记）。当我们为 intset 分配内存时，会多分配一块连续内存跟在结构体后面。

// 伪代码：分配一个包含 10 个 int64 元素的 intset
size_t size = sizeof(intset) + (10 * sizeof(int64_t));
intset *is = malloc(size);

声明为 int8_t（即 1 字节），是因为在 C 语言中，int8_t（或 char）是最小的内存寻址单位。这意味着 contents 指向的是一块原始的、未被定义的字节流。

Redis 在读取数据时，并不是直接通过下标 contents[i] 来读取（那样只能读到 1 个字节），而是通过以下逻辑进行指针强转和偏移计算：

/* * 根据给定的编码方式 (encoding)，返回 intset 中指定位置 (pos) 的元素值。
 * 注意：返回值统一提升为 int64_t，确保能容纳 int16, int32 和 int64。
 */
static int64_t _intsetGetEncoded(intset *is, int pos, uint8_t enc) {
    int64_t v64;
    int32_t v32;
    int16_t v16;

    /* 情况 1: 集合存储的是 64 位整数 */
    if (enc == INTSET_ENC_INT64) {
        /* * 核心指针运算：
         * 1. (int64_t*)is->contents : 将 int8_t* 强转为 int64_t*。
         * 这告诉编译器：这里的内存步长是 8 字节。
         * 2. + pos : 指针向后移动 pos * 8 个字节，精准定位到第 pos 个元素。
         * 3. memcpy : 从计算出的地址拷贝 8 个字节到栈变量 v64 中。
         * 使用 memcpy 而不是直接赋值 (v64 = ...)，是为了防止内存未对齐导致的 CPU 异常。
         */
        memcpy(&v64,((int64_t*)is->contents)+pos,sizeof(v64));

        /* * 字节序处理：
         * 如果当前 CPU 是大端序 (Big Endian)，则翻转字节顺序为小端序。
         * 如果是小端序 (Little Endian)，此宏不做任何操作。
         * 保证数据在内存中统一以小端序存储，实现跨平台兼容。
         */
        memrev64ifbe(&v64);
        return v64;
    } else if (enc == INTSET_ENC_INT32) {
        memcpy(&v32,((int32_t*)is->contents)+pos,sizeof(v32));
        memrev32ifbe(&v32);
        return v32;
    } else {
        memcpy(&v16,((int16_t*)is->contents)+pos,sizeof(v16));
        memrev16ifbe(&v16);
        return v16;
    }
}

5. Sorted Set

Sorted Set，即 ZSet，它是一个 Member (成员) 到 Score (分数) 的有序映射。

• 特性：Member 唯一，Score 可重复。
• 排序：按 Score 从小到大排；Score 相同，按 Member 字典序排。

5.1 核心操作

# 基础操作
ZADD key score1 member1 score2 member2  # 添加成员及其分数
ZREM key member1 member2                # 删除指定成员
ZCARD key                              # 获取集合成员数量
ZSCORE key member                      # 获取成员分数
ZCOUNT key min max                     # 统计指定分数范围内的成员数量

# 排名查询（重要）
ZRANK key member                       # 获取成员排名（从0开始，分数从小到大）
ZREVRANK key member                    # 获取反向排名（分数从大到小）
ZRANGE key start stop [BYSCORE|BYLEX] [REV] [LIMIT offset count] [WITHSCORES]  # 获取排名范围内成员
ZREVRANGE key start stop [WITHSCORES]  # 获取反向排名范围内成员

# 分数范围查询
ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]     # 按分数范围查询
ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count]  # 按分数范围反向查询
ZREMRANGEBYRANK key start stop         # 按排名范围删除成员
ZREMRANGEBYSCORE key min max           # 按分数范围删除成员

# 分数操作
ZINCRBY key increment member           # 增加指定成员的分数

# 集合运算
ZINTERSTORE destination numkeys key1 key2 [WEIGHTS w1 w2] [AGGREGATE SUM|MIN|MAX]  # 计算交集
ZUNIONSTORE destination numkeys key1 key2 [WEIGHTS w1 w2] [AGGREGATE SUM|MIN|MAX]  # 计算并集
ZDIFFSTORE destination numkeys key1 key2  # 计算差集

# 字典序操作（Redis 6.2+）
ZLEXCOUNT key min max                  # 统计字典序范围内的成员数量
ZRANGEBYLEX key min max [LIMIT offset count]  # 按字典序范围查询
ZREMRANGEBYLEX key min max             # 按字典序范围删除
ZMSCORE key member1 member2 member3    # 批量获取成员分数

常见使用场景：

• 排行榜系统：游戏积分榜、文章热度榜、用户财富榜，ZRANGE/ZREVRANGE 获取 Top N
• 延迟队列：以时间戳为分数，实现定时任务调度，ZRANGEBYSCORE 获取到期任务
• 优先级队列：任务优先级管理，高优先级任务分数更高，ZPOPMAX 获取最高优先级任务
• 范围搜索：价格区间商品查询、年龄范围用户筛选，ZRANGEBYSCORE 高效范围查询
• 加权投票：用户投票系统，投票时间越新权重越高（时间戳作为分数）
• 实时统计：热门搜索词排行，搜索次数作为分数，ZINCRBY 实时更新
• 教育资源：学生成绩管理，分数直接作为 zset 分数，ZRANK 获取排名
• 地理位置排序：虽然有 Geo 类型，但 zset 可以实现更复杂的排序逻辑

5.2 底层原理

Set 同样采用了双重编码策略，分别是 ziplist/listpack 和 skiplist+dict。

相信对阅读到了这里的读者来说，已经不会对 ZSet 使用 listpack 感到意外了，这是 Redis 里典型的用时间换空间的策略了。

当 Sorted Set 中存储的元素数量很少，并且每个元素的值都不大时，Redis 会选择 listpack 编码。

条件是：

• 元素数量小于 zset-max-listpack-entries 128
• 所有元素值的字节长度小于 zset-max-listpack-value 64

它将每个 (member, score) 对紧凑地序列化存储。为了保持有序，每次插入都需要找到正确的位置，这可能导致其后的数据发生移动。当 N 非常小（例如小于 128）时，𝑂(𝑁) 的操作成本极低，几乎是瞬时的，而节省下来的内存却非常可观。

一旦 listpack 的任一触发条件被打破，Redis 会自动将其转换为 skiplist + dict 编码。其实 ZSet 要采用"双引擎"模式，也不难理解，它要解决的核心矛盾是：如何创建一个既能通过成员（member）快速查找、又能根据分数（score）高效排序和范围查找的数据集合？

• dict (字典/哈希表)：负责"集合"的部分。它建立了一个从 member 到 score 的映射。这使得 ZSCORE 这种通过成员获取分数的操作，时间复杂度 𝑂(1)。
• skiplist (跳表)：负责"排序"的部分。它将所有的 (score, member) 对按照 score（分数相同则按 member 字典序）进行排序。跳表的特性使得插入、删除和按排名/分数范围查找的平均时间复杂度都是 𝑂(𝑙𝑜𝑔𝑁)。

为了节约内存，dict 和 skiplist 中的 member 字符串是共享的，即它们都指向同一个 SDS (Simple Dynamic String) 对象。

跳表的核心思想是空间换时间和随机化。

想象一下，一个普通的单链表，查找效率是 𝑂(𝑁)。现在，我们从这个链表中，随机抽取一些节点，给它们增加一个"上层指针"，指向下一个被抽取的节点。这样我们就构建了第 2 层"快速通道"。我们可以不断重复这个过程，构建出多层快速通道。

当我们要查找一个元素时：

1. 从最高层的"快速通道"开始。
2. 在当前层向右查找，直到找到的下一个节点比目标大，或者到了链表末尾。
3. 然后从当前节点下降一层，重复步骤 2。
4. 最终在最底层（原始链表）找到目标位置。

因为高层索引可以让你"跳过"大量节点，所以平均查找效率被提升到了 𝑂(𝑙𝑜𝑔𝑁)。而这种层级的建立是完全随机的，它通过概率来维持整体的平衡，避免了红黑树那样复杂的平衡操作。

这就是 Redis 选择跳表的原因：用更简单的实现，达到了与平衡树相媲美的性能。

在 Redis 8.4.0 的源码中，关于 zset 的类型定义位于 src/server.h 文件中。如下所示，它主要包含 3 个核心数据结构：zset、zskiplist 和 zskiplistNode。

// 跳表节点
typedef struct zskiplistNode {
    sds ele;          /* 成员字符串 */
    double score;     /* 分值（排序主键） */
    struct zskiplistNode *backward; /* 反向遍历指针（指向前一个节点） */
    struct zskiplistLevel {
        struct zskiplistNode *forward; /* 本层前进指针 */
        unsigned long span;            /* 到 forward 的节点数，用于排名计算 */
    } level[];        /* 可变层高的层数组 */
} zskiplistNode;

// 跳表结构
typedef struct zskiplist {
    struct zskiplistNode *header, *tail; /* 哨兵头/尾 */
    unsigned long length;                /* 节点总数 */
    int level;                           /* 当前最高层数 */
    size_t alloc_size;                   /* 内存统计 */
} zskiplist;

// zset 结构
typedef struct zset {
    dict *dict;        /* 成员 -> score 映射，O(1) 查找/判重 */
    zskiplist *zsl;    /* 按 score+字典序排序的跳表，支持范围/排名 */
} zset;

从比较直观的角度来讲的话，跳表的结构可以用下图来演示：

如果要完全复刻上述所定义出来的数据结构，那表示起来可能会有点复杂，这里我画了张图，供你参考：

本篇限于篇幅原因和阅读性价比的关系，笔者对绝大多数数据结构都不太愿意展开源码，不过介于 skiplist 是一个非常常考的点，也是一个比较艺术性的实现，所以在本章节我们将从一个最核心的插入逻辑来更进一步了解跳表的实现细节。 zset 的核心实现逻辑位于 src/t_zset.c 文件中，其中插入操作由 zslInsert 函数来实现。这里我先把完整的代码和注释给你，接下来我们再一一拆解。

/* 在跳表中插入一个新节点。
 * 假设：调用者已经检查过该元素不存在（Redis 在调用此函数前会在 dict 中检查）。
 * 注意：跳表会接管传入的 SDS 字符串 'ele' 的所有权。*/
zskiplistNode *zslInsert(zskiplist *zsl, double score, sds ele) {
    // update[]: 记录每一层中，新节点应该插入在哪个节点之后（即前驱节点）
    zskiplistNode *update[ZSKIPLIST_MAXLEVEL], *x;
    // rank[]: 记录 update[i] 节点在整个链表中的排名（从头节点到该节点的跨度之和）
    unsigned long rank[ZSKIPLIST_MAXLEVEL];
    int i, level;

    serverAssert(!isnan(score));
    x = zsl->header;

    /* ----------------------------------------------------------------------
     * 步骤 1: 自顶向下查找插入位置
     * ---------------------------------------------------------------------- */
    for (i = zsl->level-1; i >= 0; i--) {
        /* 计算 rank:
         * 如果是最高层，rank 初始为 0。
         * 否则，rank 继承上一层已经走过的步数 (rank[i+1])。
         * 这实现了路径累加：比如 L3 走了 10 步，降到 L2 时，起点就是 10。
         */
        rank[i] = i == (zsl->level-1) ? 0 : rank[i+1];

        /* 向后遍历：直到下一个节点的 score >= 新 score (或 score 相等但 ele 字典序更大) */
        while (x->level[i].forward &&
                (x->level[i].forward->score < score ||
                    (x->level[i].forward->score == score &&
                    sdscmp(x->level[i].forward->ele,ele) < 0)))
        {
            // 累加经过的跨度 span 到 rank[i]
            rank[i] += x->level[i].span;
            x = x->level[i].forward;
        }
        // 记录第 i 层的前驱节点
        update[i] = x;
    }

    /* 此时，rank[0] 保存的是插入位置前一个节点的总排名 */

    /* ----------------------------------------------------------------------
     * 步骤 2: 生成随机层数
     * ---------------------------------------------------------------------- */
    // 幂次定律随机生成层数 (1/4 概率)
    level = zslRandomLevel();

    // 如果新生成的层数比当前跳表最高层还高
    if (level > zsl->level) {
        // 初始化多出来的层级
        for (i = zsl->level; i < level; i++) {
            rank[i] = 0;
            // 新层级的前驱自然是 header
            update[i] = zsl->header;
            // header 在这些新层级的 span 暂时覆盖整个链表长度
            // (因为 header 后直接就是 NULL，或者即将插入的新节点)
            update[i]->level[i].span = zsl->length;
        }
        zsl->level = level; // 更新跳表最大层数
    }

    /* ----------------------------------------------------------------------
     * 步骤 3: 创建节点并调整指针与 Span (最难点)
     * ---------------------------------------------------------------------- */
    x = zslCreateNode(zsl,level,score,ele);

    // 逐层处理指针链接和 span 计算
    for (i = 0; i < level; i++) {
        // 标准的链表插入操作:
        // NewNode->Next = PrevNode->Next
        // PrevNode->Next = NewNode
        x->level[i].forward = update[i]->level[i].forward;
        update[i]->level[i].forward = x;

        /* 计算 span 的逻辑：
         * update[i]->level[i].span 是原先 update[i] 到其下一个节点的距离。
         * 现在中间插了个 x。
         *
         * rank[0]: 插入点之前的总排名。
         * rank[i]: update[i] 节点的总排名。
         * (rank[0] - rank[i]): update[i] 和 实际插入点(L0层) 之间的距离。
         */

        // 1. 设置新节点 x 的 span
        // x 的 span = 原前驱的 span - (前驱到 x 的距离)
        x->level[i].span = update[i]->level[i].span - (rank[0] - rank[i]);

        // 2. 更新前驱节点 update[i] 的 span
        // 前驱的 span = (前驱到 x 的距离) + 1 (这个 1 是 x 节点本身)
        update[i]->level[i].span = (rank[0] - rank[i]) + 1;
    }

    // 对于比新节点层数更高的层级，结构没变，只是底层多了一个节点
    // 所以这些层级的 span 只需要简单的 +1
    for (i = level; i < zsl->level; i++) {
        update[i]->level[i].span++;
    }

    /* ----------------------------------------------------------------------
     * 步骤 4: 设置后退指针 (用于 L0 层双向遍历)
     * ---------------------------------------------------------------------- */
    // 如果前驱是 header，backward 设为 NULL (header 不作为数据节点)
    x->backward = (update[0] == zsl->header) ? NULL : update[0];

    // 设置下一个节点的 backward 指向新节点 x
    if (x->level[0].forward)
        x->level[0].forward->backward = x;
    else
        // 如果 x 是最后一个节点，更新 tail 指针
        zsl->tail = x;

    zsl->length++;
    return x;
}

插入操作主要分为四个步骤：

1. 查找插入位置（Search）：从最高层往下找，记录每层的前驱节点（update[]）和到达前驱节点的排名（rank[]）。
2. 生成随机层数（Random Level）：决定新节点的高度。如果比当前跳表高，需要初始化高层的前驱。
3. 创建节点与链接（Link）：调整指针，在 0 到 level-1 的每一层中将新节点插入链表，并极其精细地计算新旧节点的 span 值。
4. 收尾工作：更新高层的 span（只加 1），设置后退指针，更新长度。

接下来我们来一一拆解这段代码的每一个细节。

第 0 步：初始化与准备

zskiplistNode *zslInsert(zskiplist *zsl, double score, sds ele) {
    // update[]: 记录每一层中，新节点应该插入在哪个节点之后（即前驱节点）
    zskiplistNode *update[ZSKIPLIST_MAXLEVEL], *x;
    // rank[]: 记录 update[i] 节点在整个链表中的排名（从头节点到该节点的跨度之和）
    unsigned long rank[ZSKIPLIST_MAXLEVEL];
    int i, level;

• zskiplistNode *update[ZSKIPLIST_MAXLEVEL]: 路径记录仪。它是一个指针数组，update[i] 将用于存储新节点在第 i 层的前驱节点。为什么需要它？因为插入操作的本质就是在 update[i] 和它原来的下一个节点之间，插入我们的新节点。这个数组为我们保存了所有需要修改的连接点。
• unsigned long rank[ZSKIPLIST_MAXLEVEL]: 距离计数器。rank[i] 用于记录从跳表 header 头节点出发，到达 update[i] 这个节点时，在最底层（第 0 层）总共跨越了多少个节点。它的核心作用是为后续精确计算和更新节点的 span（跨度）提供数据支持，这是 ZRANK 命令能够实现 𝑂(𝑙𝑜𝑔𝑁) 的基石。

第 1 步：查找插入位置并记录路径

x = zsl->header;

/* ----------------------------------------------------------------------
 * 步骤 1: 自顶向下查找插入位置
 * ---------------------------------------------------------------------- */
for (i = zsl->level-1; i >= 0; i--) {
    /* 计算 rank:
     * 如果是最高层，rank 初始为 0。
     * 否则，rank 继承上一层已经走过的步数 (rank[i+1])。
     * 这实现了路径累加：比如 L3 走了 10 步，降到 L2 时，起点就是 10。
     */
    rank[i] = i == (zsl->level-1) ? 0 : rank[i+1];

    /* 向后遍历：直到下一个节点的 score >= 新 score (或 score 相等但 ele 字典序更大) */
    while (x->level[i].forward &&
            (x->level[i].forward->score < score ||
                (x->level[i].forward->score == score &&
                sdscmp(x->level[i].forward->ele,ele) < 0)))
    {
        // 累加经过的跨度 span 到 rank[i]
        rank[i] += x->level[i].span;
        x = x->level[i].forward;
    }
    // 记录第 i 层的前驱节点
    update[i] = x;
}

这是跳表算法的精髓所在——分层查找。

• for (i = zsl->level-1; i >= 0; i--): 循环从最高层（zsl->level-1）开始，逐层下降到最底层（0）。这模仿了我们在地图上查找位置的过程：先看洲际地图（高层），再看国家地图（中层），最后看城市街道图（底层）。高层级的"快速通道"可以让我们一次性跳过大量节点。
• while (...): 在当前层级，不断向右移动。判断条件 (score < ... || (score == ... && ele < ...)) 保证了跳表的排序规则：优先按 score 升序，如果 score 相同，则按 member 的字典序升序。
• rank[i] += x->level[i].span;: 这是 rank 数组工作的核心。每当我们从 x 节点跳到它的下一个节点时，并不是只前进了一步，而是前进了 x->level[i].span 步。我们将这个跨度累加到 rank[i] 中，rank[i] 就实时记录了我们距离起点的总步数。
• update[i] = x;: 当 while 循环结束时，x 节点就是新节点在第 i 层的前驱节点。我们将其记录在 update[i] 中。当整个 for 循环结束后，update 数组就完整记录了从最高层到最底层的一条插入路径。

第 2 步：确定新节点层高并处理新层级

/* ----------------------------------------------------------------------
 * 步骤 2: 生成随机层数
 * ---------------------------------------------------------------------- */
// 幂次定律随机生成层数 (1/4 概率)
level = zslRandomLevel();

// 如果新生成的层数比当前跳表最高层还高
if (level > zsl->level) {
    // 初始化多出来的层级
    for (i = zsl->level; i < level; i++) {
        rank[i] = 0;
        // 新层级的前驱自然是 header
        update[i] = zsl->header;
        // header 在这些新层级的 span 暂时覆盖整个链表长度
        // (因为 header 后直接就是 NULL，或者即将插入的新节点)
        update[i]->level[i].span = zsl->length;
    }
    zsl->level = level; // 更新跳表最大层数
}

• level = zslRandomLevel(): 新节点将拥有几层"快速通道"？这里不是由复杂的平衡算法决定，而是通过一个简单的概率函数随机生成。大部分节点只有 1 层，极少数节点会有很高的层数。正是这种随机性，使得跳表在整体上能够维持一个高效的对数级结构。
• if (level > zsl->level): 处理一个特殊情况。如果随机出的 level 比当前跳表的最大层数还大，意味着我们需要为整个跳表加盖新的楼层。在这些新楼层，路径上的前驱节点自然就是 header 节点，并且它到 NULL 的跨度就是整个跳表的长度 zsl->length。

第 3 步：节点创建、链接与跨度更新

/* ----------------------------------------------------------------------
 * 步骤 3: 创建节点并调整指针与 Span (最难点)
 * ---------------------------------------------------------------------- */
x = zslCreateNode(zsl,level,score,ele);

// 逐层处理指针链接和 span 计算
for (i = 0; i < level; i++) {
    // 标准的链表插入操作:
    // NewNode->Next = PrevNode->Next
    // PrevNode->Next = NewNode
    x->level[i].forward = update[i]->level[i].forward;
    update[i]->level[i].forward = x;

    /* 计算 span 的逻辑：
     * update[i]->level[i].span 是原先 update[i] 到其下一个节点的距离。
     * 现在中间插了个 x。
     *
     * rank[0]: 插入点之前的总排名。
     * rank[i]: update[i] 节点的总排名。
     * (rank[0] - rank[i]): update[i] 和 实际插入点(L0层) 之间的距离。
     */

    // 1. 设置新节点 x 的 span
    // x 的 span = 原前驱的 span - (前驱到 x 的距离)
    x->level[i].span = update[i]->level[i].span - (rank[0] - rank[i]);

    // 2. 更新前驱节点 update[i] 的 span
    // 前驱的 span = (前驱到 x 的距离) + 1 (这个 1 是 x 节点本身)
    update[i]->level[i].span = (rank[0] - rank[i]) + 1;
}

这是整个插入过程中最核心的逻辑：

链接 forward 指针: 这两行是经典的链表插入操作。假设原来是 A -> C，A 就是 update[i]，C 就是 update[i]->level[i].forward。现在，我们将新节点 x 插入其中，变为 A -> x -> C。

更新 span (跨度): 这是最精妙的部分，我们用一个例子来说明。

• 假设在第 i 层，前驱节点 A (即 update[i]) 原来的 span 是 10，它直接指向 C。
• 我们在第 0 层（最底层）的查找过程中，从 A 之后，又前进了 3 步才找到插入点。这意味着 rank[0] - rank[i] 的值是 3（可以理解为 A 在高层和底层之间的投影偏差）。
• update[i]->level[i].span = (rank[0] - rank[i]) + 1;: A 的新 span 变为 3 + 1 = 4。因为它现在指向新节点 x，它俩之间跨越了 3 个旧节点，加上 x 本身，总共是 4 步。
• x->level[i].span = update[i]->level[i].span - (rank[0] - rank[i]);: 新节点 x 的 span 等于 A 的旧 span (10) 减去它俩之间的距离 (3)，等于 7。

验证: 插入后，A 的新 span (4) + x 的新 span (7) = 11。而 A 的旧 span 是 10。总跨度增加了 1，正好等于新加入的节点数量。完美！

另外，对于那些高于新节点 level 的层级，新节点并不会被插入。但是，由于整个跳表的总长度增加了 1，这些更高层级上、位于插入路径上的前驱节点（update[i]），它们指向的下一个节点的相对距离也增加 1。因此，它们的 span 值需要递增。

第 4 步：更新后退指针和表尾

/* ----------------------------------------------------------------------
 * 步骤 4: 设置后退指针 (用于 L0 层双向遍历)
 * ---------------------------------------------------------------------- */
// 如果前驱是 header，backward 设为 NULL (header 不作为数据节点)
x->backward = (update[0] == zsl->header) ? NULL : update[0];

// 设置下一个节点的 backward 指向新节点 x
if (x->level[0].forward)
    x->level[0].forward->backward = x;
else
    // 如果 x 是最后一个节点，更新 tail 指针
    zsl->tail = x;

zsl->length++;
return x;

• x->backward = ...: 跳表的最底层（level[0]）是一个双向链表，backward 指针用于支持 ZREVRANGE 等反向遍历命令。这里将新节点的后退指针正确地指向它的前驱节点 update[0]。
• if...else...: 更新新节点的后继节点的 backward 指针，让它指向新节点 x。如果新节点是最后一个节点，则更新整个跳表的 tail 指针。
• zsl->length++: 最后，将跳表的总长度加 1。

至此，一个新节点被天衣无缝地织入了跳表这张大网中，所有相关的指针和跨度信息都得到了原子性的更新。

6. Bitmap

Bitmap（位图） 利用 String 的二进制位（Bit）来存数据，适用于处理 bit 级别的数据。因为 SDS 最大 512MB，所以 Bitmap 最多能存 $2^{32}$ (约 40 亿) 个 bit。

# 基础位操作
SETBIT key offset value          # 设置指定偏移量的位值（0或1）
GETBIT key offset                # 获取指定偏移量的位值

# 位统计
BITCOUNT key [start end]         # 统计位图中值为1的位数
BITPOS key bit [start end]       # 查找第一个指定值的位置

# 位运算（重要）
BITOP operation destkey key1 key2 ...  # 位运算操作
  # operation: AND(与), OR(或), XOR(异或), NOT(非)

# 字符串和位图转换
BITFIELD key [GET type offset] [SET type offset value] [INCRBY type offset increment]  # 位域操作

# 扩展命令（Redis 6.2+）
BITFIELD_RO key [GET type offset] ...  # 只读的位域操作

常见使用场景：

• 用户签到：用位表示用户每日签到状态，1 表示已签到，BITCOUNT 统计月签到天数
• 在线状态：用户在线/离线状态跟踪，SETBIT user:online 1001 1 表示用户 1001 在线
• 权限管理：RBAC 权限系统，每位代表一种权限，BITOP AND 实现权限交集
• 布隆过滤器底层：实现自定义布隆过滤器的基础数据结构
• 用户特征：用户画像标签系统，1 表示有该特征，BITOP OR 找相似用户
• A/B 测试：用户分组标识，0 为对照组，1 为实验组
• 数据统计：日活用户统计，BITOP OR 合并多日活跃用户计算总活跃数
• 去重统计：大量 ID 去重，使用位图存储已见过的 ID，节省内存
• 游戏系统：成就系统解锁状态，每个成就对应一个位，BITCOUNT 统计解锁数量

7. HyperLogLog

HyperLogLog 是一个概率数据结构，用于估计集合的基数。它的底层也是 String 类型。每个 HyperLogLog 最多消耗 12KB 的内存，在标准误差 0.81% 的前提下，可以计算 $2^{64}$ 个元素的基数。

7.1 核心操作

# 基础操作
PFADD key element1 element2 ...  # 添加元素到 HyperLogLog
PFCOUNT key1 key2 key3 ...       # 获取一个或多个 HyperLogLog 的基数估计
PFMERGE destkey source1 source2 ...  # 合并多个 HyperLogLog 到目标键

# 实用命令组合
# 创建并初始化
PFADD daily_users_20231201 "user_1001" "user_1002" "user_1003"

# 查看基数估计
PFCOUNT daily_users_20231201

# 合并多日数据
PFMERGE month_users daily_users_20231201 daily_users_20231202 daily_users_20231203

# 多键统计
PFCOUNT week_users month_users  # 可以同时查询多个键的合并基数

常见使用场景：

• UV 统计：网站/APP 日活、月活用户统计，PFADD 记录用户访问，PFCOUNT 获取 UV 数量
• 大数据去重：海量数据去重统计，如日志分析中的独立 IP 统计
• 实时统计：社交平台的活跃用户数、电商平台的访客数等实时去重统计
• 用户行为分析：页面浏览量去重、搜索关键词去重统计
• 广告曝光：广告独立曝光人数统计，避免重复计算同一用户
• 数据分析：A/B 测试中的独立用户数统计、转化漏斗的去重计数
• 监控告警：系统独立错误触发次数、独立异常 IP 统计
• 内容分发：视频独立观看人数、文章独立阅读数统计

7.2 底层原理

HyperLogLog 使用概率算法来统计集合的近似基数，而概率算法的本质是伯努利试验（Bernoulli Trial），伯努利试验可以看作一个抛硬币过程。

假设我们玩抛硬币游戏，我让你一直抛，直到抛出"正面"为止，这算一轮。

我们记录每一轮中，"反面"连续出现的次数（也就是前导 0 的个数）。

• 情况 1：你抛了 1 次就出了正面。前导 0 个数 = 0。
• 情况 2：你抛了 2 次（反、正）。前导 0 个数 = 1。
• ...
• 情况 N：如果你告诉我，你刚刚那一轮，连续抛了 10 次反面才出正面（前导 0 = 10）。

推断：连续抛 10 次反面的概率是 $(1/2)^{10} = 1/1024$。

如果你能做到这件事，我不仅认为你运气好，我更有理由相信：你肯定已经在背后偷偷抛了很多很多轮（大概 1024 轮左右），才碰巧出现了一次这么罕见的情况。所以我们可以通过观察一组随机数（Hash 值）中**"最大前导 0 的个数"**，来反推这组随机数大概有多少个（基数）。

如果只依据一次运气最好的记录（最大前导 0）来估算，偶然性太大（比如我第一次就走了狗屎运抛了 10 个反面，你不能说我抛了 1000 次）。

HyperLogLog 引入了 分桶（Bucketing）的概念：

1. 把数据分成 $m$ 个桶。
2. 分别统计每个桶里的最大前导 0。
3. 对这些桶的结果求调和平均数（而不是算术平均数），以消除极端值（离群点）的影响。

算术平均数（Arithmetic Mean）我们都懂：加起来除以 N。

$$ A = \frac{x_1 + x_2}{2} $$

调和平均数是：倒数的平均数，再取倒数。

$$ H = \frac{2}{\frac{1}{x_1} + \frac{1}{x_2}} $$

调和平均数对小数值更敏感，而对大数值（离群值）不敏感。Redis 就是通过这 16384 个桶的调和平均数，把"运气"成分对冲掉，最终让误差稳定在 0.81% 左右。

Redos 内部使用字符串 Bitmap 来存储 HyperLogLog 所有桶的计数值，一共包含 $2^{14}=16384$ 个桶，每个桶都是一个 6bit 的数组。HyperLogLog 的头部定义位于：src/hyperloglog.c

#define HLL_P 14 /* The greater is P, the smaller the error. */
#define HLL_Q (64-HLL_P) /* The number of bits of the hash value used for
                            determining the number of leading zeros. */
#define HLL_REGISTERS (1<<HLL_P) /* With P=14, 16384 registers. */
#define HLL_P_MASK (HLL_REGISTERS-1) /* Mask to index register. */
#define HLL_BITS 6 /* Enough to count up to 63 leading zeroes. */

/* HyperLogLog 头部：
 * magic：固定标识 "HYLL"，用于持久化格式识别。
 * encoding：两种存储模式
 *   - HLL_DENSE：每个寄存器 6 bit，16K 寄存器共约 12288 字节，元素多时内存固定。
 *   - HLL_SPARSE：稀疏 RLE/指令流压缩，元素少时占用小，超过阈值自动转为 DENSE。
 * notused[3]：保留位，必须为 0。
 * card[8]：缓存的基数估计值（小端），为 0 表示缓存失效，下次查询重算并写回。
 * registers[]：寄存器数据区；
 *	 - DENSE 为紧凑 6-bit 数组。
 *	 - SPARSE 为指令序列（ZERO/VAL/XZERO 等表示连续寄存器段）。
 */
struct hllhdr {
    char magic[4];      /* "HYLL" */
    uint8_t encoding;   /* HLL_DENSE or HLL_SPARSE. */
    uint8_t notused[3]; /* Reserved for future use, must be zero. */
    uint8_t card[8];    /* Cached cardinality, little endian. */
    uint8_t registers[]; /* Data bytes. */
};

当执行 PFADD key element 时：

1. Hash：Redis 使用 MurmurHash64A 算法将 element 转换为一个 64 位的整数（比特串）。
2. 分桶：Redis 使用这个 64 位整数的 前 14 位 作为桶的索引（Register Index）。$2^{14} = 16384$，所以才说 Redis 内部维护了 16384 个桶（registers[]）。
3. 计数：使用剩下的 50 位 (64 - 14) 来计算前导 0 的个数，因为只有 50 位，所以 6 个 bit（$2^6 = 64 > 50$）就足够了。如果算出来前导 0 是 $k$，就把第 $index$ 个桶的值更新为 $\max(\text{当前值}, k+1)$。

Redis 为了省内存，也不会一上来就申请 12KB，所以 registers[] 存在两种编码格式：

• 稀疏编码 (Sparse)：当 HLL 刚创建，或者元素很少时，Redis 使用一种类似 RLE (Run-Length Encoding) 的压缩格式。比如"连续 100 个桶都是 0"，它就存"100 个 0"，而不是存 100 个 0 的实际数据。
• 密集编码 (Dense)：当数据多了，稀疏编码存不下了，就会转换成标准的 12KB 密集数组。

8. Bloom Filter

Bloom Filter（布隆过滤器）是由 Burton Howard Bloom 于 1970 年提出的，它是一种 space efficient 的概率型数据结构，用于判断一个元素是否在集合中。通常用于快速判断某个元素是否可能存在于一个大型数据集中，而无需实际存储整个数据集。

在 Redis 8 之后，Bloom Filter 已经内置在 Redis 中了。在这之前，它不是 Redis 的标准功能，而是通过 Redis 4.0+ 引入 Module 插件机制安装的，详细可参考 GitHub 丨 RedisBloom。

8.1 核心操作

# 创建布隆过滤器
BF.ADD key item1 item2 item3       # 添加元素（自动创建过滤器）
BF.EXISTS key item                 # 检查元素是否存在
BF.MADD key item1 item2 item3      # 批量添加元素
BF.MEXISTS key item1 item2 item3   # 批量检查元素

# 手动创建并配置
BF.RESERVE key error_rate capacity [EXPANSION expansion] [NONSCALING]
  # error_rate: 期望的错误率（如0.01表示1%）
  # capacity: 期望的元素数量
  # EXPANSION: 扩容因子（默认2）
  # NONSCALING: 禁用自动扩容

# 高级操作
BF.INSERT key [CAPACITY cap] [ERROR error] [NOCREATE] ITEMS item1 item2 ...  # 插入元素
BF.INFO key                        # 查看过滤器信息
BF.CARD key                        # 获取过滤器中元素数量（近似值）
BF.SCANDUMP key iterator           # 用于数据备份和恢复

# 计数布隆过滤器（Cuckoo Filter替代方案）
CF.ADD key item                    # 添加元素到计数过滤器
CF.ADDNX key item                  # 仅当元素不存在时添加
CF.EXISTS key item                 # 检查元素是否存在
CF.DEL key item                    # 删除元素（支持删除）
CF.COUNT key item                  # 获取元素计数

常见使用场景：

• 缓存穿透防护：查询数据库前先用布隆过滤器检查 key 是否存在，避免无效查询穿透到数据库
• URL 去重：爬虫系统中判断 URL 是否已经爬取过，避免重复爬取
• 用户注册：检查用户名/邮箱是否已被注册，快速响应
• 垃圾邮件过滤：维护已知垃圾邮件发送者黑名单，快速过滤
• 数据库分片：快速判断某个 key 应该存储在哪个分片上
• 推荐系统：过滤用户已经看过的内容，避免重复推荐
• 安全防护：IP 黑名单、恶意请求过滤等安全场景
• 数据同步：分布式系统中判断数据是否需要同步，减少网络传输

8.2 底层原理

布隆过滤器的数据结构底层其实就是一个巨大的 Bitmap。通过一组哈希函数，将同一个元素计算出来的多个哈希值对应的 bit 位置为 1，从而判断一个元素是否存在：

• 如果存在 bit 位为 0 的：则该元素一定不存在。
• 如果不存在 bit 位为 0 的：则该元素大概率存在。

所以很显然，Bloom Filter 是不支持删除元素的。

9. Geospatial

Redis Geospatial 是 Redis 3.2 引入的一组用于处理地理位置信息的命令。它允许我们存储地理坐标（经度和纬度），并执行诸如"计算两点距离"、"查找附近的人"等 LBS（Location-Based Service）操作。

9.1 核心操作

# 基础操作
GEOADD key longitude latitude member [longitude latitude member ...]  # 添加地理位置
GEOPOS key member1 member2 ...     # 获取指定位置的坐标
GEODIST key member1 member2 [unit]  # 计算两个位置之间的距离

# 单位参数：m(米)、km(千米)、mi(英里)、ft(英尺)
GEODIST cities beijing shanghai km  # 计算北京到上海的公里距离

# 范围查询（重要）
GEORADIUS key longitude latitude radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC] [STORE key] [STOREDIST key]
GEORADIUSBYMEMBER key member radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC] [STORE key] [STOREDIST key]

# 查询选项说明：
# WITHCOORD: 返回坐标
# WITHDIST: 返回距离
# WITHHASH: 返回geohash值
# COUNT: 限制返回数量
# ASC|DESC: 按距离排序
# STORE: 存储结果到有序集合
# STOREDIST: 存储距离到有序集合

# 搜索示例
GEORADIUS restaurants 116.397128 39.916527 5 km WITHDIST WITHCOORD COUNT 10
GEORADIUSBYMEMBER restaurants starbucks 2 km WITHDIST

# 哈希操作
GEOHASH key member1 member2 ...  # 获取位置的 geohash 字符串

# 有序集合操作（底层是zset）
ZSCORE key member               # 获取位置的geohash分数
ZRANGE key start stop WITHSCORES  # 获取范围位置和分数
ZREM key member1 member2         # 删除位置
ZCARD key                       # 获取位置数量

# 批量操作（Redis 6.2+）
GEOSEARCH key [FROMMEMBER member | FROMLONLAT longitude latitude] [BYRADIUS radius m|km|ft|mi | BYBOX width height m|km|ft|mi] [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC]

常见使用场景：

• 附近的人：社交应用查找附近用户，GEORADIUS 查找指定范围内的用户
• 附近商家：生活服务平台查找附近餐厅、酒店、银行等
• 打车服务：查找附近司机、计算预估距离和费用
• 外卖配送：查找附近商家、计算配送距离和时间
• 位置签到：记录用户位置，实现签到功能
• 地理围栏：设定虚拟地理边界，进入或离开时触发事件
• 位置营销：基于地理位置的精准营销和广告推送
• 物流追踪：实时追踪包裹位置，查找附近配送点
• 旅游导航：查找附近景点、计算景点间距离
• 紧急服务：查找附近的医院、警察局等紧急服务点

实用示例：

# 添加城市位置
GEOADD cities 116.397128 39.916527 beijing
GEOADD cities 121.473701 31.230416 shanghai
GEOADD cities 113.264385 23.129112 guangzhou

# 计算距离
GEODIST cities beijing shanghai km  # 输出：1067.5

# 查找北京500km内的城市
GEORADIUS cities 116.397128 39.916527 500 km WITHDIST

9.2 底层原理

Redis Geo 并没有引入新的底层数据结构，其本质上是一个 Sorted Set。

地理位置是一个二维坐标 (经度, 纬度)，而 Redis 的 ZSet 只能按一个一维的 score 进行排序。为了复用 ZSet 的排序和范围查找能力，必须将二维坐标映射为一维整数。

GeoHash 就是这种映射算法。它将地球表面划分为无数个矩形网格，并利用 Z-Order Curve（Z 阶曲线）将二维网格编码为一维的二进制串。GeoHash 的编码过程就是将经度和纬度分别二分逼近，大于中间值记为 1，小于记为 0。然后将经纬度的二进制位交错组合（偶数位放精度，奇数位放纬度），生成最终的 52 位整数。

当我们要查询"附近的人"时，实际上是在 ZSet 中查找 score（GeoHash 值）相近的元素。

但是，GeoHash 存在一个著名的边界问题：两个点可能直线距离很近，但刚好位于两个格子的边缘，导致它们的 GeoHash 值差异巨大（例如一个在 Z 曲线的末端，一个在起端）。

为了解决这个问题，Redis 在执行 GEORADIUS 时，不仅会搜索中心点所在的那个格子（GeoHash 范围），还会自动计算并搜索周围的 8 个邻居格子。

我让 Gemini 绘制了一个网页，用于辅助理解，感兴趣的读者可自行下载参考。

https://github.com/hedon954/geohash-display

10. PubSub

PubSub（Publish/Subscribe，发布/订阅）是一种消息通信模式。发送者（Pub）将消息发送到频道（Channel），而不用知道谁订阅了它；订阅者（Sub）接收感兴趣频道的消息，而不用知道谁发送了它。

Pub/Sub 的核心逻辑是 广播 (Broadcasting)。 它和 List/Stream 最大的区别在于：它不存储消息。

10.1 核心操作

# 发布订阅操作
PUBLISH channel message         # 向指定频道发布消息
SUBSCRIBE channel1 channel2 ... # 订阅一个或多个频道
UNSUBSCRIBE channel1 channel2 ...  # 取消订阅指定频道

# 模式订阅
PSUBSCRIBE pattern1 pattern2 ...   # 订阅匹配模式的频道（支持通配符*和?）
PUNSUBSCRIBE pattern1 pattern2 ... # 取消模式订阅

# 查询操作
PUBSUB CHANNELS [pattern]         # 列出活跃的频道（支持模式匹配）
PUBSUB NUMSUB [channel1 channel2 ...]  # 查看指定频道的订阅者数量
PUBSUB NUMPAT                     # 查看模式订阅的数量

# 实用示例
# 发布者
PUBLISH news:sports "中国队获得冠军！"
PUBLISH notifications:user:1001 "您有新的消息"

# 订阅者
SUBSCRIBE news:sports
SUBSCRIBE notifications:user:1001

# 模式订阅（订阅所有新闻频道）
PSUBSCRIBE news:*
PSUBSCRIBE notifications:user:*

# 查看频道状态
PUBSUB NUMSUB news:sports notifications:user:1001
PUBSUB CHANNELS news:*

常见使用场景：

• 实时通知：系统通知、消息推送、事件提醒等实时通知场景
• 聊天室：多用户实时聊天系统，群聊广播消息
• 实时数据推送：股票价格、比赛比分、实时监控数据推送
• 事件驱动架构：微服务间的事件通信，解耦生产者和消费者
• 缓存失效：当数据更新时，通过 PubSub 通知缓存失效，实现缓存一致性
• 日志收集：应用日志实时收集和分发到日志处理系统
• 监控系统：系统告警、性能指标实时推送
• 配置更新：分布式系统中的配置变更通知
• 游戏实时通信：多人游戏中的状态同步、位置更新等

10.2 底层原理

Redis 服务器结构体 redisServer 中维护了关于 Pub/Sub 的重要字段：

/* src/server.h */
struct redisServer {
  kvstore *pubsub_channels;  /* Map channels to list of subscribed clients */
  dict *pubsub_patterns;  /* A dict of pubsub_patterns */
  int notify_keyspace_events; /* Events to propagate via Pub/Sub. This is an
                                 xor of NOTIFY_... flags. */
  kvstore *pubsubshard_channels;  /* Map shard channels in every slot to list of subscribed clients */
  unsigned int pubsub_clients; /* # of clients in Pub/Sub mode */
}

kvstore *pubsub_channels:

• 普通频道订阅关系表。Key 是频道名 (Channel)，Value 是一个链表，存储了所有订阅该频道的客户端 (Clients)。对应 SUBSCRIBE 和 PUBLISH 命令。
• 在 Redis 7.0 之前，这里是一个 dict *（字典）。但在新版本中，它升级为了 kvstore *。在 Redis Cluster 模式下，普通的 Pub/Sub 是广播的（一个节点收到消息，会转发给集群内所有节点）。kvstore 是 Redis 内部对"支持分槽（Slot）的字典"的抽象。虽然普通的 Pub/Sub 是广播的，但使用 kvstore 统一了内部的数据结构接口，方便管理和扩容。

dict *pubsub_patterns:

• 模式订阅关系表。Key 是匹配模式 (Pattern，如 news.*)，Value 是订阅了该模式的客户端列表。对应 PSUBSCRIBE 和 PPUBLISH 命令。
• 当有消息发布到 news.sports 频道时，Redis 不仅要查 pubsub_channels，还要遍历这个 pubsub_patterns 字典，看 news.sports 是否匹配其中的模式。

int notify_keyspace_events:

• 键空间通知配置。这是一个 Bitmask (位掩码) 整数。对应 redis.conf 配置中的 notify-keyspace-events（如 "Ex" 代表过期事件）。
• Redis 的键空间通知（Keyspace Notifications）本质上就是利用 Pub/Sub 机制实现的。当一个 Key 被修改或过期时，如果这个掩码中对应的位被置为 1，Redis 就会自动向特定的频道（如 __keyevent@0__:expired）发送一条 Pub/Sub 消息。

kvstore *pubsubshard_channels:

• 分片频道订阅关系表 (Sharded Pub/Sub)。对应 SSUBSCRIBE 和 SPUBLISH 命令 (Redis 7.0 新增)。
• 普通的 Pub/Sub 在集群中是全量广播的。你在节点 A 发布消息，节点 A 会把它转发给 B、C、D... 即使 B、C、D 上根本没有客户端订阅这个频道。这造成了巨大的网络带宽浪费（写放大）。
• Sharded Pub/Sub 将频道名通过 Hash 算法映射到具体的 Slot (槽)，就像普通的 Key 一样。消息只会被发送到持有该 Slot 的节点，不再全网广播。这里的 kvstore 发挥了关键作用：它能根据 Slot 快速索引和管理频道。这是 Redis 7.0 针对集群 Pub/Sub 性能优化的一大体现。

unsigned int pubsub_clients:

• 当前的 Pub/Sub 客户端总数。用于 INFO 命令统计和监控。
• Redis 需要知道当前有多少个连接处于"订阅状态"，因为处于订阅状态的客户端，其 socket 读取逻辑和普通客户端略有不同（只能发送订阅相关命令）。

[!WARNING]

注意，虽然 Pub/Sub 不保存消息，但是为了保证把消息推给（在线的）订阅者，会把积压的消息暂时存在该订阅者 Client 的 输出缓冲区 (Output Buffer) 中。如果消费者处理得很慢，导致积压越来越多，这个缓冲区会无限膨胀，最终 OOM。

Redis 默认配置了保护策略 client-output-buffer-limit：如果缓冲区超过 32MB，或者持续 60 秒超过 8MB，Redis 会强制断开这个订阅者的连接。订阅者断连，消息丢失，但 Redis 活下来了。

11. Stream

Redis Stream 是 Redis 5.0 引入的最重量级特性，它的出现是为了填补 Redis 在消息队列领域的最后一块短板——持久化与可靠性。

在此之前，使用 Redis 做消息队列主要有两种方式，但都有致命缺陷：

1. List (BLPOP)：无法支持多播；更致命的是，它没有 ACK 机制。消息一旦从队列中 POP 出来，如果消费者处理时宕机，这条消息就永久丢失了。
2. Pub/Sub：支持多播，但它是 Fire and Forget（即发即弃）模式。如果消费者下线，期间发送的所有消息都会丢失，且无法回溯。

Stream 的设计灵感深受 Kafka 影响，它不仅支持多播（消费组），还引入了 PEL (Pending Entries List) 机制来保证消息的绝对不丢失，同时在底层结构上针对"时间序列 ID"做了极致的内存压缩。

11.1 核心操作

# 基础操作
XADD key [MAXLEN len [~]] [NOMKSTREAM] *|ID field value [field value ...]  # 添加消息
XLEN key                              # 获取流中消息数量
XRANGE key start end [COUNT count]    # 读取范围内的消息（正向）
XREVRANGE key end start [COUNT count] # 读取范围内的消息（反向）

# 消息读取
XREAD [COUNT count] [BLOCK milliseconds] [NOACK] STREAMS key1 key2 ... ID1 ID2 ...
# ID选项：$（最新消息）、>（消费者组新消息）、具体时间戳ID

# 消费组操作
XGROUP [CREATE key groupname id|$] [MKSTREAM]           # 创建消费组
XGROUP [DESTROY key groupname]                         # 销毁消费组
XGROUP [SETID key groupname id|$]                      # 设置消费组最后消息ID
XGROUP [DELCONSUMER key groupname consumername]        # 删除消费者
XINFO [GROUPS key]                                     # 查看消费组信息
XINFO [CONSUMERS key groupname]                        # 查看消费者信息
XINFO [STREAM key] [FULL]                              # 查看流详细信息

# 消费者读取
XREADGROUP GROUP group consumer [COUNT count] [BLOCK milliseconds] [NOACK] STREAMS key1 key2 ... ID1 ID2 ...
# ID选项：>（新消息）、0（所有未处理消息）、具体ID

# 消息确认
XACK key group ID [ID ...]                            # 确认消息已处理
XPENDING key group [start end count consumer]         # 查看待处理消息
XCLAIM key group consumer min_idle_time ID [ID ...] [IDLE ms] [TIME ms] [RETRYCOUNT count] [FORCE] [JUSTID] [LASTID id]
XDEL key ID [ID ...]                                  # 删除消息

# 修剪操作
XTRIM key MAXLEN len [~]                              # 修剪流到指定长度
XTRIM key MINID threshold [~]                         # 删除小于指定ID的消息

# 实用示例
# 创建流并添加消息
XADD mystream * name "张三" age 25
XADD mystream * name "李四" age 30

# 读取消息
XREAD COUNT 2 STREAMS mystream 0-0

# 创建消费组
XGROUP CREATE mystream mygroup $ MKSTREAM

# 消费者读取
XREADGROUP GROUP mygroup consumer1 COUNT 1 STREAMS mystream >

# 确认消息
XACK mystream mygroup 1672502400000-0

常见使用场景：

• 消息队列：替代 RabbitMQ/Kafka，处理异步任务、事件驱动架构
• 事件溯源：记录系统状态变更历史，支持事件回放和时间旅行查询
• 日志收集：应用日志的可靠收集和转发，支持消费者组并行处理
• 监控告警：系统监控指标的时序数据存储和分析
• 数据管道：ETL 过程中的数据缓冲和批处理
• 实时分析：用户行为分析、点击流处理等实时数据流处理
• IoT 数据：物联网设备数据的时序存储和处理
• 金融交易：交易日志记录、审计追踪，支持精确的时间序列查询
• 游戏系统：游戏事件记录、玩家行为分析
• 聊天系统：可靠的消息投递，支持离线消息和消息重试

11.2 底层原理

Stream 本质上是一个 仅追加 (Append-only) 的日志结构。为了满足高效的范围查找（按时间范围读消息）和极致的内存节省，Redis 并没有使用简单的链表或数组，而是设计了一种混合结构：Radix Tree (基数树) + Listpack。

11.2.1 stream

Stream 定义在 src/stream.h，负责维护消息的元数据、存储引擎（Rax）入口以及消费组状态。

/* Stream 核心结构体
 * 位于 src/stream.h */
typedef struct stream {
    /* ---- 数据存储区 ---- */
    rax *rax;               /* 核心存储引擎：Radix Tree。
                             * Key: 消息 ID (大端序二进制)
                             * Value: 指向一个 Listpack 的指针 (每个 Listpack 存多条消息) */

    uint64_t length;        /* 当前 Stream 中的有效消息数量 (不包含已删除的消息) */

    streamID last_id;       /* 当前 Stream 中最后一条消息的 ID (若为空则为 0-0) */
    streamID first_id;      /* 当前 Stream 中第一条消息的 ID (若为空则为 0-0) */

    /* ---- 统计与清理 ---- */
    streamID max_deleted_entry_id;  /* 历史上被删除的最大消息 ID (用于协议兼容) */
    uint64_t entries_added;         /* 历史上累计写入过的消息总数 (即 ID 序列号计数器) */
    size_t alloc_size;              /* Stream 自身占用的堆内存大小 (不含 key 本身) */

    /* ---- 消费组管理 ---- */
    rax *cgroups;           /* 消费组字典。
                             * Key: 消费组名称 (String)
                             * Value: streamCG 结构体指针 */

    rax *cgroups_ref;       /* 辅助索引：用于加速 NACK 处理等场景 */

    streamID min_cgroup_last_id;    /* 缓存：所有消费组中，进度最慢的那个 last_id。
                                     * 用于垃圾回收，判断哪些数据可以安全清理 */
    unsigned int min_cgroup_last_id_valid: 1; /* 缓存是否有效标记 */
} stream;

11.2.2 streamID

Stream 的消息 ID 默认是自动生成的，格式为 <时间戳>-<序列号>（例如 1702108800000-0）。

typedef struct streamID {
    uint64_t ms;        /* Unix time in milliseconds. */
    uint64_t seq;       /* Sequence number. */
} streamID;

观察这组 ID，你会发现一个显著特征：前缀高度重复。在同一毫秒甚至同一秒内产生的消息，其 ID 的高位部分是完全相同的。如果使用普通的 Hash 表或跳表存储，这些重复的前缀会浪费大量内存。

11.2.3 Radix Tree

Radix Tree (Rax) 是一种前缀树。它将公共前缀提取出来作为父节点，差异部分作为子节点。这种结构天然适合存储时间序列数据，极大地压缩了索引空间。

这并非标准的 Radix Tree 的实现，标准的 Radix Tree 一个节点只有一个字符，当然这对于 Stream 这个场景依旧是极大的浪费，所以一个改进方案就是将多个相同前缀的字符合并在一个作为一个共享节点。

事实上 Go 的 Gin 框架的路由树也是采取的这种策略，具体可参考：Go 底层原理丨深度剖析 Gin 框架核心机制：从 HTTP 请求生命周期到高性能设计哲学。

如果 Rax 的每个叶子节点只挂一条消息，那指针开销依然很大。Redis 再次运用了"打包"的思想。

Stream 在 Rax 的节点中，并不直接存储单个消息，而是存储一个 listpack（又来了，神奇的 listpack）。一个 Rax 节点（称为宏节点）可能包含几十条甚至上百条消息。

• 宏观上：利用 Radix Tree 对 ID 前缀进行压缩，支持 $O(\log N)$ 的时间范围查找。
• 微观上：利用 Listpack 对具体的消息内容（Field-Value）进行紧凑存储，利用 CPU 缓存行并减少内存碎片。

[!IMPORTANT]

这再次印证了 Redis 的设计哲学：在大规模索引上使用树/跳表（空间换时间），在局部小数据块上使用紧凑数组（时间换空间）。

Radix Tree 定义在 src/rax.h。

/* Rax (Radix Tree) 头部 */
typedef struct rax {
    raxNode *head;          /* 指向根节点的指针 */
    uint64_t numele;        /* 树中存储的元素总数 (即 Key 的数量) */
    uint64_t numnodes;      /* 树中节点的总数 */
    size_t *alloc_size;     /* 指向外部变量的指针，用于统计该树占用的总内存 */
    void *metadata[];       /* 可选的元数据区域 (通常用于填充对齐) */
} rax;

/* Rax 节点 */
typedef struct raxNode {
    /* ---- 位域标志头 (4字节) ---- */
    uint32_t iskey:1;     /* 1 表示这就到达了一个 Key 的终点 (包含 Value) */
    uint32_t isnull:1;    /* 1 表示 Value 为 NULL (即使 iskey=1) */
    uint32_t iscompr:1;   /* 1 表示这是压缩节点 (Compressed)，0 表示非压缩 (Normal) */
    uint32_t size:29;     /* 节点负载大小：
                           * - 若 iscompr=1: 表示压缩后缀的长度 (字节数)
                           * - 若 iscompr=0: 表示子节点的数量 (边数) */

    /* ---- 柔性数组：数据负载区 ----
     * 这里的布局根据 iscompr 的值完全不同
     */
    unsigned char data[];
} raxNode;

由于 data[] 是变长的，C 语言无法直接描述其结构，其内存布局如下：

1. 压缩节点（iscompr = 1）

这意味着这是一条单行道。 当前节点只有一个子节点，且中间经过了一串字符。 比如：从节点 A 到节点 B，中间的路径字符串是 "QD"。

data[] 的内存布局：它像三明治一样，把路径字符串”和唯一的子节点指针紧挨着放。

+-----------------------+ <-- 节点起始地址
| Header (4 Bytes)      | iskey=1, iscompr=1, size=2
+-----------------------+
| 'Q' (1 Byte)          | \
+-----------------------+  > 压缩字符串 "QD"
| 'D' (1 Byte)          | /
+-----------------------+
| Child Ptr (8 Bytes)   | --> 指向下一个 raxNode (代表 ID 后续部分的节点)
+-----------------------+
| Value Ptr (8 Bytes)   | --> 指向 Listpack (存储消息内容) [仅当 iskey=1 时存在]
+-----------------------+

2. 非压缩节点（iscompr = 0）

这意味着这是一个十字路口（分叉点）。 当前节点有多个子节点。 比如：节点 A 下面分出了 'A', 'B', 'C' 三条路。

data[] 的内存布局： 它把**所有的路牌（字符）放一起，把所有的路（指针）**放一起。

+-----------------------+ <-- 节点起始地址
| Header (4 Bytes)      | iskey=1, iscompr=0, size=3
+-----------------------+
| 'A' (1 Byte)          | \
+-----------------------+  |
| 'B' (1 Byte)          |  > 子节点索引字符 (共3个)
+-----------------------+  |
| 'C' (1 Byte)          | /
+-----------------------+
| Padding (X Bytes)     | <-- 内存对齐填充 (视当前偏移量而定，确保后续指针地址对齐)
+-----------------------+
| Child Ptr 1 (8 Bytes) | --> 指向 'A' 分支的下一个 raxNode
+-----------------------+
| Child Ptr 2 (8 Bytes) | --> 指向 'B' 分支的下一个 raxNode
+-----------------------+
| Child Ptr 3 (8 Bytes) | --> 指向 'C' 分支的下一个 raxNode
+-----------------------+
| Value Ptr (8 Bytes)   | --> 指向 Listpack (存储消息内容) [仅当 iskey=1 时存在]
+-----------------------+

11.2.4 streamCG

Stream 能替代 List 成为企业级消息队列的核心，在于它引入了消费组 (Consumer Group) 和 PEL (Pending Entries List)。

当消费者调用 XREADGROUP 读取消息时：

1. 消息不会从 Stream 中删除（这点与 List 不同）。
2. 消息 ID 会被加入到该消费者的 PEL 中。
3. 只有当消费者显式调用 XACK 后，Redis 才会把该 ID 从 PEL 中移除。

这背后的核心数据结构是 streamCG。

/* Consumer group. */
typedef struct streamCG {
    streamID last_id;       /* 该消费组最后一次交付（但未确认）的消息 ID。
                               当消费者请求“新消息”时，Redis 会提供大于此 ID 的消息。 */

    long long entries_read; /* 统计信息：该组读取的消息总数 */

    rax *pel;               /* Pending Entries List (待处理列表)。
                               这是一个 Radix Tree。
                               Key: 消息 ID (64位大端序)
                               Value: streamNACK 结构 (记录了投递次数、最后投递时间等)
                               作用: 记录所有已发给消费者但尚未 ACK 的消息。 */

    rax *pel_by_time;       /* 辅助索引：按“投递时间”排序的 PEL。
                               Key: pelTimeKey (包含 delivery_time + stream ID)
                               Value: NULL (所有信息都在 Key 里)
                               作用: 加速超时消息的查询 (如 XPENDING ... IDLE <time>)。 */

    rax *consumers;         /* 消费者字典。
                               Key: 消费者名称
                               Value: streamConsumer 结构 */
} streamCG;

每个消费组都有一个全局游标 last_id。

• 当你使用 XREADGROUP GROUP mygroup alice > 时，那个 > 符号实际上就是告诉 Redis："请把 last_id 之后的消息发给我"。
• Redis 发送消息后，会更新 last_id。这保证了在同一个组内，消息不会被重复消费（除非显式回溯）。

如下图所示，如果我们把 Radix Tree 摊平来看，每个消费组有自己的游标位置，互不干扰，而 stream 结构中的 min_cgroup_last_id 字段会存储最满的 last_id，那前面的消息就可以删除了。

PEL (Pending Entries List) 是 Stream 实现 At Least Once 的关键。streamCG 维护了一个名为 pel 的 Radix Tree。

• 写入时机：当消息被 XREADGROUP 读取但未 XACK 时，它会立即进入 pel。
• 移除时机：只有收到 XACK，Redis 才会将该 ID 从 pel 中移除。

如果消费者宕机，这条消息会永久停留在 pel 中。运维人员可以通过 XPENDING 命令查看到这些消息，并安排其他消费者进行 Claim (接管)。

仔细观察结构体，你会发现 streamGC 维护了两个与 PEL 相关的 Radix Tree：

/* Consumer group. */
typedef struct streamCG {
    rax *pel;
    rax *pel_by_time;
} streamCG;

这是一种典型的空间换时间设计：

• pel: 按 ID 索引，Key 是 消息 ID。当消费者发送 XACK <id> 时，Redis 需要快速找到这条消息并标记完成。使用 ID 索引可以达到 $O(\log N)$ 的查找速度。
• pel_by_time: 按时间索引，Key 是 投递时间 + 消息 ID。用于故障恢复。当我们需要找出"哪些消息已经超时 10 分钟没处理了？"（即 XPENDING ... IDLE <time> 命令），Redis 不需要遍历整个 PEL，而是直接在 pel_by_time 这个时间树上进行范围查找。

这种主键索引 + 辅助索引的设计，确保了 Stream 无论是正常确认 (ACK) 还是故障排查 (Pending Query)，都能保持极高的性能，不会因为积压消息过多而拖慢 Redis。

[!WARNING]

但这不意味着 Redis Stream 就可以替代传统的 MQ 了，其本质上是受限于昂贵的内存容量和异步持久化机制，无法像基于磁盘的 Kafka 那样以低成本实现海量数据的长期堆积与金融级的零丢失保障。

12. 原理和应用场景总结

Redis 的数据类型虽然丰富多样，但万变不离其宗。回顾全文，我们可以看到 Redis 在设计上始终在做两个维度的权衡（Trade-off）：

1. 内存 vs CPU：在数据量少时，倾向于使用时间换空间的紧凑结构（如 Listpack、Intset），通过 CPU 的轮询计算来节省昂贵的内存；在数据量大时，倾向于使用空间换时间的索引结构（如 Hashtable、Skiplist），通过增加指针开销来保证 O(1) 或 O(logN) 的访问速度。
2. 精确 vs 概率：在处理海量数据统计时，为了突破物理内存的限制，引入了概率型数据结构（HLL、Bloom Filter），用极小的误差换取了巨大的空间收益。

以下是全系数据类型的核心原理与选型指南：

参考

• Redis 8.4.0
• Redis Commands
• Bloom Filters Explained
• Wikipedia-Radix tree
• redis streams

我们要构建一个**“微型分布式事务同步系统”**。

目标：当 MySQL 中的用户余额发生变更（充值）时，Go 程序自动捕获 Binlog，并将最新的余额实时同步到 Redis 中，实现最终一致性。

我们将全流程分为 四个步骤：

1. 环境准备 (MySQL & Redis)
2. Go 项目初始化
3. 编写核心代码 (main.go)
4. 运行与验证

🟢 第一步：环境准备 (MySQL & Redis)

请确保你的本地或开发机已经启动了 MySQL 和 Redis。

1. MySQL 建表与数据准备

请在你的 MySQL 中执行以下 SQL。我们创建一个简单的 user_balance 表。

SQL

-- 1. 创建测试数据库
CREATE DATABASE IF NOT EXISTS order_db;
USE order_db;

-- 2. 创建用户余额表
CREATE TABLE IF NOT EXISTS user_balance (
    uid INT PRIMARY KEY,
    username VARCHAR(50),
    balance INT DEFAULT 0 COMMENT '余额(分)',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB;

-- 3. 初始化一个用户 (uid=10086, 余额=0)
INSERT INTO user_balance (uid, username, balance) VALUES (10086, 'Hedon', 0)
ON DUPLICATE KEY UPDATE balance=0;

-- 4. 确认 Binlog 格式为 ROW (必须!)
SET SESSION binlog_format = 'ROW';

2. 创建拥有复制权限的用户 (可选，推荐)

为了安全，通常创建一个专门用于同步的账号，而不是用 root。

SQL

CREATE USER 'canal_user'@'%' IDENTIFIED BY 'canal_pass';
GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'canal_user'@'%';
FLUSH PRIVILEGES;

🔵 第二步：Go 项目初始化

在你的工作目录下创建一个新项目：

Bash

# 1. 创建目录
mkdir binlog-sync-demo
cd binlog-sync-demo

# 2. 初始化 go mod
go mod init binlog-sync-demo

# 3. 下载依赖库
# go-mysql: 用于解析 Binlog
# go-redis: 用于操作 Redis
go get github.com/go-mysql-org/go-mysql/replication
go get github.com/redis/go-redis/v9

🟠 第三步：编写核心代码 (main.go)

这是整个系统的灵魂。我会加上详细的注释，帮助你理解每一行。

创建一个 main.go 文件，将以下代码完整复制进去。

注意：请修改代码顶部的 MySQL 配置 和 Redis 配置，适配你本地的环境。

Go

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	"github.com/go-mysql-org/go-mysql/replication"
	"github.com/redis/go-redis/v9"
)

// --- 配置区域 (请修改为你自己的配置) ---
var (
	// MySQL 配置
	mysqlHost     = "127.0.0.1"
	mysqlPort     = uint16(3306)
	mysqlUser     = "canal_user" // 或者 root
	mysqlPass     = "canal_pass" // 或者你的密码
	targetDB      = "order_db"
	targetTable   = "user_balance"

	// Redis 配置
	redisAddr     = "127.0.0.1:6379"
	redisPass     = ""
)

var ctx = context.Background()

func main() {
	// 1. 初始化 Redis 客户端
	rdb := redis.NewClient(&redis.Options{
		Addr:     redisAddr,
		Password: redisPass,
	})
	if _, err := rdb.Ping(ctx).Result(); err != nil {
		fmt.Printf("❌ Redis 连接失败: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("✅ Redis 连接成功！等待数据同步...")

	// 2. 初始化 Binlog Syncer
	cfg := replication.BinlogSyncerConfig{
		ServerID: 100, // 假装自己是一个从库，ID 必须唯一
		Flavor:   "mysql",
		Host:     mysqlHost,
		Port:     mysqlPort,
		User:     mysqlUser,
		Password: mysqlPass,
	}
	syncer := replication.NewBinlogSyncer(cfg)

	// 3. 开始同步
	// 这里的 Position 设置为 File="", Pos=4 表示从当前最新的位置开始监听
	// 生产环境需要从存储的 Checkpoint 读取
	streamer, err := syncer.StartSync(replication.Position{Name: "", Pos: 4})
	if err != nil {
		fmt.Printf("❌ 启动 Binlog 监听失败: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("🚀 Binlog 监听器启动成功！正在监听 MySQL 变更...")

	// 4. 进入事件循环
	for {
		ev, err := streamer.GetEvent(context.Background())
		if err != nil {
			fmt.Printf("❌ 获取事件错误: %v\n", err)
			break
		}

		// 我们只关心 UPDATE 事件 (充值通常是 Update)
		// 如果是新用户注册，还需要监听 WRITE_ROWS_EVENTv2
		if ev.Header.EventType == replication.UPDATE_ROWS_EVENTv1 || ev.Header.EventType == replication.UPDATE_ROWS_EVENTv2 {
			handleUpdateEvent(ev, rdb)
		}
	}
}

// 处理更新事件
func handleUpdateEvent(ev *replication.BinlogEvent, rdb *redis.Client) {
	rowsEvent := ev.Event.(*replication.RowsEvent)

	// 1. 过滤库名和表名 (我们只关心 user_balance 表)
	// 注意：go-mysql 解析出来的 SchemaName 和 TableName 是 byte 数组
	dbName := string(rowsEvent.Table.Schema)
	tblName := string(rowsEvent.Table.Table)

	if dbName != targetDB || tblName != targetTable {
		return // 不是我们要的表，跳过
	}

	fmt.Printf("\n⚡ 捕获到 %s.%s 的更新事件！\n", dbName, tblName)

	// 2. 解析行数据
	// Update 事件的 Rows 数组结构：[旧行1, 新行1, 旧行2, 新行2, ...]
	for i := 0; i < len(rowsEvent.Rows); i += 2 {
		oldRow := rowsEvent.Rows[i]
		newRow := rowsEvent.Rows[i+1]

		// 根据你的表结构 user_balance (uid, username, balance, update_time)
		// 对应的索引是: 0, 1, 2, 3

		// 提取 UID (主键)
		uid := getInt(newRow[0])

		// 提取余额 Balance
		oldBalance := getInt(oldRow[2])
		newBalance := getInt(newRow[2])

		fmt.Printf("   用户 UID: %d\n", uid)
		fmt.Printf("   余额变更: %d -> %d\n", oldBalance, newBalance)

		// 3. 业务逻辑：同步到 Redis
		// 只有余额真的变了才同步
		if newBalance != oldBalance {
			redisKey := fmt.Sprintf("user:balance:%d", uid)

			// 模拟耗时，体现"异步"特性
			// time.Sleep(10 * time.Millisecond)

			err := rdb.Set(ctx, redisKey, newBalance, 0).Err()
			if err != nil {
				fmt.Printf("   ❌ Redis 同步失败: %v\n", err)
				// 生产环境这里需要重试或报警
			} else {
				fmt.Printf("   ✅ Redis 同步成功！Key: %s, Value: %d\n", redisKey, newBalance)
			}
		} else {
			fmt.Println("   ⚠️ 余额未发生实质变化，忽略同步。")
		}
	}
}

// 辅助函数：处理 go-mysql 解析出来的 int 类型差异
// go-mysql 可能会根据数值大小返回 int, int32, int64 等不同类型
func getInt(v interface{}) int64 {
	switch val := v.(type) {
	case int:
		return int64(val)
	case int8:
		return int64(val)
	case int16:
		return int64(val)
	case int32:
		return int64(val)
	case int64:
		return val
	case uint:
		return int64(val)
	case uint32:
		return int64(val)
	case uint64:
		return int64(val)
	default:
		return 0
	}
}

🟣 第四步：运行与验证 (见证奇迹的时刻)

现在我们打开两个终端窗口。

窗口 1：运行 Go 程序 (同步器)

Bash

go run main.go

你会看到输出：

✅ Redis 连接成功！等待数据同步...

🚀 Binlog 监听器启动成功！正在监听 MySQL 变更...

程序现在处于阻塞监听状态。

窗口 2：操作 MySQL (模拟充值)

连接到你的 MySQL，执行充值操作。

SQL

USE order_db;

-- 模拟：给用户 10086 充值 100 块 (10000分)
UPDATE user_balance SET balance = balance + 10000 WHERE uid = 10086;

👀 观察结果

回到窗口 1 (Go 程序)，你应该会立刻看到如下输出：

Plaintext

⚡ 捕获到 order_db.user_balance 的更新事件！
   用户 UID: 10086
   余额变更: 0 -> 10000
   ✅ Redis 同步成功！Key: user:balance:10086, Value: 10000

检查 Redis (可选)：

如果你有 Redis 客户端，可以去验证一下：

Bash

redis-cli get user:balance:10086
# 输出应该是 "10000"

🧠 深度复盘：这个 Demo 里的架构点

通过这个实操，你实际上已经跑通了**“异构数据同步”**的最核心路径。

1. ROW 格式的威力：

   代码里的 oldRow 和 newRow 之所以能拿到，全靠 MySQL Binlog 的 ROW 格式记录了镜像数据。

2. 准实时性：

   你会发现，当你敲下 SQL 回车的一瞬间，Go 程序几乎同时输出了日志。这就是 Binlog 推送 的效率（通常在 10ms 以内），足以满足绝大多数“最终一致性”的业务需求。

3. 解耦：

   你在操作 MySQL 时，完全不需要知道 Redis 的存在。是 Go 程序作为“旁路”把数据搬运过去的。这就实现了业务代码与缓存逻辑的解耦。

去做一下这个实验吧！跑通的那一刻，你会对“分布式事务”有全新的实感。

这是一个非常敏锐的架构问题！你能问出这个问题，说明你已经具备了**“生产级架构”**的思维，不再局限于写一个小 Demo。

结论先行：

在刚才的 Demo 中，我跳过 Kafka 是为了降低学习门槛和演示环境复杂度（避免让你在本地搭建 Zookeeper + Kafka 集群）。

但在真实的生产环境（高并发/大规模）中，引入 Kafka（或 RocketMQ）几乎是必须的。

我们来深度剖析一下：为什么在这个链路中，我们需要 Kafka 做中间件？ 它到底解决了什么“直连模式”解决不了的问题？

1. 架构演进：从“直连”到“消息队列”

🔵 阶段一：直连模式 (刚才的 Demo)

架构：MySQL -> Binlog 监听程序 (Canal/Go) -> Redis

• 优点：
  • 简单，无中间件依赖。
  • 延迟极低（少了一次网络传输）。
• 致命缺陷：
  1. 强耦合：Go 程序既要负责解析 Binlog（复杂的协议），又要负责写 Redis（业务逻辑）。如果 Redis 挂了，或者 Redis 写得太慢，会阻塞 Binlog 的解析，导致主从延迟堆积。
  2. 无法复用：如果你的搜索团队说：“嘿，我也想要一份用户余额变更的数据写到 Elasticsearch 里”。你就得改代码，或者再起一个 Binlog 监听（对 MySQL 造成双倍压力）。
  3. 无削峰能力：如果 MySQL 瞬间爆发 10 万 TPS 的写入，Go 程序会尝试向 Redis 发起 10 万次写入，Redis 可能会直接崩掉（缓存雪崩）。

🟠 阶段二：引入 Kafka (生产标准)

架构：MySQL -> Binlog 解析器 (Canal/Debezium) -> Kafka -> 消费者 (Go App) -> Redis

在这个架构中，Kafka 扮演了最重要的“缓冲”和“解耦”角色。

2. Kafka 在 CDC 链路中的四大核心价值

如果你在面试中被问到“为什么要加 Kafka”，请抛出这四个关键词：

① 解耦 (Decoupling) —— 各司其职

• Binlog 解析器 (Producer)：只负责把 Binlog 变成 JSON 扔进 Kafka。它根本不关心下游是 Redis 还是 ES，也不关心下游是不是挂了。它的任务就是快，紧跟 MySQL 主库。
• 业务消费者 (Consumer)：只负责从 Kafka 拿消息写 Redis。如果 Redis 挂了，消费者可以暂停，Kafka 会帮我们保存进度（Offset）。等 Redis 修好了，消费者重启，继续从断点消费。整个过程不影响 MySQL 主库。

② 削峰填谷 (Traffic Shaping) —— 保护下游

• 场景：大促期间，MySQL 瞬间涌入 5 万 QPS 的充值请求。
• 作用：Kafka 极其能抗写（百万级 TPS）。它能瞬间吞下这 5 万条消息，像一个巨大的蓄水池。
• 下游：后端的 Go 程序可以按照自己的节奏（比如每秒处理 2000 个），慢慢地从 Kafka 里取数据更新 Redis。Redis 此时是非常安全的，不会被流量洪峰打死。

③ 广播/多路分发 (Fan-out) —— 数据资产化

• 场景：一份数据，多处使用。
• 作用：Binlog 数据进入 Kafka 的 Topic: user_balance_update 后：
  • Consumer Group A (缓存组)：读取数据 -> 更新 Redis。
  • Consumer Group B (搜索组)：读取同一份数据 -> 更新 Elasticsearch。
  • Consumer Group C (数仓组)：读取同一份数据 -> 存入 Hive/ClickHouse。
• 收益：MySQL 只需要承受一次 Binlog Dump 的压力，实现了**“一次生产，多次消费”**。

④ 数据回放 (Data Replay) —— 容错后悔药

• 场景：你写的更新 Redis 的代码有个 Bug，把余额加错了。代码上线跑了 1 个小时你才发现。
• 作用：如果是直连模式，Binlog 早就流过去了，难以重来。但在 Kafka 模式下，你可以把消费者的 Offset (偏移量) 重置到 1 小时前。
• 结果：消费者会重新拉取过去 1 小时的历史消息，重新计算并覆盖 Redis 中的错误数据。

3. 代码层面的变化

如果要上 Kafka，你的 Go 代码会拆分成两个独立的程序。

程序 A：Producer (Binlog -> Kafka)

你可以继续用 go-mysql，或者直接部署开源的 Canal Deployer 或 Debezium（推荐，基于 Java/Kafka Connect）。它们配置一下就能用，不需要写代码。

程序 B：Consumer (Kafka -> Redis)

这才是你需要写的业务代码：

Go

// 伪代码：从 Kafka 消费
func main() {
    reader := kafka.NewReader(kafka.ReaderConfig{
        Brokers: []string{"localhost:9092"},
        Topic:   "mysql_binlog_user_balance",
        GroupID: "redis_updater_group", // 消费者组
    })

    for {
        m, _ := reader.ReadMessage(context.Background())

        // 1. 解析 Kafka 消息 (JSON)
        var event BalanceUpdateEvent
        json.Unmarshal(m.Value, &event)

        // 2. 写入 Redis
        redis.Set("user:"+event.Uid, event.NewBalance)

        // 3. 提交 Offset (表示这条我处理完了)
        reader.CommitMessages(context.Background(), m)
    }
}

总结

你问得非常好。

• 学习/开发/小规模：直连模式（MySQL -> App -> Redis）完全 OK，简单粗暴，延迟最低。
• 生产/大规模/核心链路：必须上 Kafka。不仅仅是为了解耦，更是为了数据的安全和系统的健壮性。

建议：

既然你已经跑通了直连。如果想挑战高阶，可以尝试在本地起一个 Kafka，把刚才 Demo 里的 handleUpdateEvent 函数改成“发送 Kafka 消息”，然后再写一个小程序去消费它。这就构成了一个完整的工业级 CDC 链路。

我们可以从 "不可能三角" 开始，层层拆解，最后落实到工业级的设计。

1. 不可能三角

在分库分表场景下，一个优秀的 ID 必须同时满足以下三个维度的苛刻要求，但这往往存在权衡：

1. 全局唯一性 (Uniqueness)：这是基本底线。不能出现两个分片生成了同一个 ID。
2. 单调递增性 (Trend Increasing)：这是 MySQL 场景下的核心痛点。MySQL 的 InnoDB 引擎使用 聚簇索引 (Clustered Index)。数据是直接挂在主键 B+ 树叶子节点上的。如果 ID 是随机的（如 UUID），插入新数据时，会频繁导致 B+ 树中间节点的 页分裂 (Page Split)，造成大量的随机磁盘 I/O 和碎片，极大地降低写入性能。所以：ID 必须尽量有序，最好是严格递增。
3. 高可用与高性能 (Availability & Performance)：发号器不能成为系统的瓶颈，也不能因为单点故障导致整个业务停摆。

2. 方案演进

2.1 反面教材：UUID

UUID 是原理是利用网卡 MAC 地址、时间戳、随机数生成 128 位字符串。它适用于生成 Token、文件名，但绝不用于数据库主键。

主要缺点有：

• 性能杀手：无序，导致 MySQL 频繁页分裂（写入性能比有序 ID 差 N 倍）。
• 存储浪费：128 位字符串太长，且作为二级索引的叶子节点值，会膨胀整个数据库索引空间。
• 不可读：无法在日志中快速定位时间或业务含义。

2.2 远古方案：数据库步长法

利用 MySQL 的 auto_increment，但不同分片设置不同的起始值和步长。

• DB1: start=1, step=2 -> 1, 3, 5...
• DB2: start=2, step=2 -> 2, 4, 6...

这种方案有一个最大的缺陷：一旦设定了 step=2，后续想扩容成 3 个分片，所有旧数据的 ID 生成逻辑都要改，几乎无法平滑扩容。

美团的 Leaf-segment 对这个方案进行了改进，它的核心思路是单独搞一个发号服务，每次从数据库领 1000 个 ID（号段）放在内存里慢慢发。

• 优点：减轻数据库压力，容忍数据库短时间宕机。
• 缺点：ID 不严格连续，依赖中心化服务。

2.3 黄金标准：雪花算法

这是目前最主流的分布式 ID 方案，由 Twitter 提出。它本质上是一个位运算 (Bit Manipulation) 的艺术。

• 1 bit：不使用（符号位）。
• 41 bits：毫秒级时间戳（可以使用 69 年）。
• 10 bits：机器 ID（5 位数据中心 ID + 5 位工作机器 ID，支持 1024 个节点）。
• 12 bits：序列号（每毫秒内支持生成 4096 个 ID）。

笔者认为，雪花算法最大的价值在于提出了ID 分段的思想，我们大可以根据需求、借助时间戳和分段，自由切割 ID 的不同比特位，赋予其不同的含义，灵活设计自己的 ID 算法。

雪花算法有两大优势：

• 本地生成：不依赖网络请求，性能极高。
• 趋势递增：高位是时间，整体随时间递增，对 B+ 树友好。

但是雪花算法强依赖服务器系统时间。如果服务器时间校准（NTP）导致时间回退，可能会生成 重复 ID。

2.3.1 直接拒绝

如果发现当前时间 < 上次生成时间，抛出异常，拒绝服务（最简单，但影响可用性）。

// Rust 伪代码示例
if current_timestamp < self.last_timestamp {
    // 警报！当前时间竟然比上一次发号的时间还早！
    // 说明发生了时钟回拨
    return Error("Clock moved backwards!");
}

2.3.2 等待追赶

NTP 的校准通常非常微小。如果发现回拨了 2ms，程序可以选择 不报错，死循环等待。

// Rust 伪代码示例
if current_timestamp < self.last_timestamp {
    let offset = self.last_timestamp - current_timestamp;
    if offset <= 5 { // 如果只回拨了 5ms 以内
        // 睡一会儿，或者空转，直到时间追上来
        thread::sleep(Duration::from_millis(offset));
        // 重新获取时间
        current_timestamp = Now(); 
    } else {
        panic!("回拨太多了，救不了！");
    }
}

• 代价：这次 ID 生成请求会增加几毫秒的延迟（用户无感知）。
• 收益：服务不会挂，数据不会错。

2.3.3 扩展位

如果回拨时间较长（比如几秒），等待策略会导致请求超时。 百度开源的 UidGenerator 使用了一种**"未来时间"**的思路，或者利用保留位。

• 思路：Snowflake 的 64 位中，通常有 1-2 位是保留位（Reserved）。
• 做法：当发生回拨时，将 last_timestamp 继续递增（使用虚拟时间），同时修改 sequence 或者启用 回拨位。
• 本质：此时生成的 ID 里的"时间戳部分"已经不是真实的物理时间了，而是逻辑时间。只要保证 ID 的单调递增性，物理时间不准确并不影响数据库的主键性能。

这里还有个问题！self.last_timestamp 是存在内存中的，服务重启怎么办？

解决方案是：

每次服务启动时，先去 ZK/Redis 拿一下这台机器"上次汇报的时间"。如果 当前系统时间 < 上次汇报时间，说明机器时间有问题，拒绝启动报警。当然，这里肯定是异步汇报的，而且，可以汇报未来时间，比如 当前系统时间+3s，这样，哪怕我崩溃了，Redis 里记录的时间戳一定比我发出的最后一个 ID 的时间戳要大。重启时只要检查 Redis，就能 100% 保证时间轴没有重叠。

3. 多维查询

分库分表的 ID 问题，除了 ID 的生成问题，还有 ID 的选择问题。

思考一下：订单ID、用户ID、商户ID。 当拆分的时候，根据哪个维度进行拆分呢?

假设按用户 ID 维度拆分，同一个用户 ID 的所有订单会落到同一个库的同一张表里。 当查询的时候，按用户 ID 查，可以很容易地定位到某个库的某个表。但如果按订单 ID 或 商户 ID 维度查询，就很难做。

解决思路有：

1. 建立一个映射表：商户 ID 和用户 ID 之间的映射关系，订单 ID 和用户 ID 之间的映射关系，存在分布式事务问题。
2. 业务双写：同一份数据，两套分库分表。一套按用户 ID 切分，一套按商户 ID 切分。同样，存在写入多个库的分布式事务问题。
3. 异步双写：还是两套表，只是业务单写。然后通过监听 Binlog，同步到另外一套表。
4. 基因法：两个维度统一到一个维度，把订单 ID 和用户 ID 统一成一个维度，比如订单 ID 固定前几位是用户 ID。

在单表场景下，数据库利用 B+ 树索引可以快速定位 offset；但在分片环境下，数据分散在不同的物理节点，没有任何一个节点拥有全局视图。

当然，在单表场景下，如果 offset 太大，依旧需要白白扫前面的 offset 条数据，然后才取 limit 要的数据，很浪费。

我们可以从 问题本源（第一性原理）、通用方案、深度分页优化 以及 业务折衷 四个层面来思考解决方案。

1. 为何分表后分页变难了？

假设我们有 3 个分片（Node A, Node B, Node C），按照 ID 取模分片。现在我们要按时间排序，查询第 10 页的数据（每页 10 条，即 LIMIT 10 OFFSET 90）。

1.1 错误的直觉

直觉告诉我们：在每个分片上执行 LIMIT 10 OFFSET 90，然后把结果拿回来合并。

这是错误的。因为 Node A/B/C 的第 91 条数据，可能是全局第 91 条，也可能是全局第 1 条（如果 Node A 的数据时间都很新），也可能是全局第 270 条。你无法确定每个分片内部数据的全局相对位置。

1.2 正确但低效的做法（Broadcast & Merge）

为了保证数据的准确性，你必须确保不错过任何可能的记录。

• 你需要向 所有分片 发送请求：SELECT * FROM table ORDER BY time LIMIT 100 (OFFSET + LIMIT)。
• 汇总所有分片返回的数据：$3 \times 100 = 300$ 条。
• 在内存中对这 300 条数据进行全局排序。
• 取第 91-100 条，抛弃其余 270 条。

这种做法被称为 全局视野法。它的代价是随着页码（OFFSET）的增加，查询代价呈指数级（或线性倍数）增长。

如果用户查询第 10,000 页（Offset 100,000, Limit 10），有 N 个分片：

• 网络 I/O： 需要传输 $N \times (100,000 + 10)$ 条数据。
• 内存 CPU： 应用层或中间件需要对 $N \times 100,010$ 条数据进行排序。

这就是著名的 分库分表深分页（Deep Paging）问题。

2. 通用解决方案

针对上述问题，工界通常有以下几种演进方案：

• 全局视野法：中间件代理，即上述的 broadcast & merge。
• 二次查询法：新增一个全局 ID 映射表，先查 ID 后查数据。
• 同步至异构数据源：利用专门的 OLAP 数据库进行处理。

2.1 全局视野法（中间件代理）

即上述的 "Broadcast & Merge"。

• 实现： 依赖 ShardingSphere、MyCat 等中间件，或者在代码层并发调用。
• 适用场景： 分页深度较浅（前 10-20 页），对性能要求不极致的后台管理系统。
• 缺点： 越往后翻，数据库压力越大，最终会导致 OOM（内存溢出）或超时。

2.2 二次查询法（全局 ID 映射）

如果必须精确分页且页码较深，可以建立一张 「索引表」。

• 原理： 建立一张只有 (排序字段, 主键 ID) 的表，这张表不分片（或者按照排序字段分片）。
• 步骤：
  1. 先在索引表中执行 LIMIT 10 OFFSET N，拿到 10 个 ID。
  2. 拿着这 10 个 ID，去各个分片中查询具体数据（利用 IN 查询，命中分片键）。
• 适用场景： 排序字段单一，且索引表数据量在单机可承受范围内（例如数据量虽大但每行很小）。
• 缺点： 多了一次查询；索引表本身可能成为瓶颈。

2.3 同步至异构数据源（大数据方案）

这是最通用的重型解决方案。MySQL 只做 OLTP（事务处理），复杂的查询交给专门的检索引擎。

• 原理： 通过 Binlog（Canal/Debezium）将数据实时同步到 Elasticsearch (ES) 或 ClickHouse。
• 步骤： 分页查询直接走 ES，ES 天然支持分布式搜索和排序。拿到 ID 后，如果需要最新鲜的详情，再回查 MySQL（可选）。
• 适用场景： C 端搜索、复杂条件筛选、海量数据分页。
• 缺点： 架构复杂，存在数据同步延迟（秒级或毫秒级）。

3. 深度分页的优化技巧

如果不想引入 ES，必须在 MySQL 体系内解决深分页，可以使用以下方法：

• 游标法：不用 offset，改用 where + limit。
• 只有 ID 的全局排序：分片只查询 ID，然后再逐个去查询其他字段。

3.1 游标法

这是最高效的方案，将 $O(N)$ 的复杂度降为 $O(1)$。

• 核心思想： 抛弃 OFFSET，使用 "上一页的最后一条记录" 作为锚点。
• 前提： 排序字段必须有唯一性（通常用 order by time, id）。
• SQL 变化：
  • 第 1 页：LIMIT 10 -> 记录最后一条的 time=T1, id=ID1。
  • 第 2 页：WHERE time < T1 OR (time = T1 AND id < ID1) ORDER BY time DESC, id DESC LIMIT 10。
• 优点： 无论翻到第几万页，每个分片只需要扫描 10 条数据，性能恒定。
• 缺点： 不支持跳页（只能点击"下一页"或"加载更多"），不适合需要跳转到"第 X 页"的场景。适用于 App 的无限流（Feed 流）。

单表场景其实也建议使用这个方案，不然 offset 会白白扫描很多的数据。

3.2 只有 ID 的全局排序

如果必须支持跳页，可以结合方案一进行优化。

步骤：

1. 每个分片只查询 id 和 排序字段（不查询 select *），减少网络传输和内存消耗。
2. 在内存中对 ID 列表排序，截取需要的 ID。
3. 用 ID 回表查询完整数据。

效果： 缓解了网络带宽压力，但没有解决数据库扫描的 I/O 压力。

4. 业务折衷与产品设计

很多时候，技术上的难题可以通过修改产品逻辑来规避。

4.1 限制最大页码

真的有用户会看电商商品的第 5000 页吗？通常 Google 搜索也只给你看前几十页。

可以限制只能查看前 100 页。超过 100 页提示“请输入更精确的搜索条件”。

4.2 牺牲精度（模糊分页）

当数据量达到亿级，用户并不在乎显示的 "共 10000+ 条" 是否精确，也不在乎第 100 页的第一条数据和第 99 页的最后一条是否严格连续。

可以每个分片各取一部分数据，按照某种权重拼凑一页给用户。或者，每隔一定时间预计算一次全局 Count。

5. 总结

推荐方案：

• 首选游标法（Cursor-based pagination）：设计 API 时，参数不要用 page_number，而是用 next_cursor（加密的 token，包含上一页的 ID）。这是现代 API（如 Twitter, Stripe）的标准做法。
• 兜底方案：如果必须用传统分页，限制 max_offset。

1. gRPC

要彻底掌握 gRPC，我们不能仅停留在会写 .proto 文件和生成代码的层面。我们需要从 第一性原理 出发，理解它到底解决了什么问题，它是如何构建在网络协议之上的，以及在生产环境中会遇到哪些真实挑战。

特此声明，本篇是笔者与 Google Gemini 3Pro 共创所作，非常庆幸在当今 AI 时代下获取知识已是如此便利，且也为学习者从第一性原理理解所学知识大大降低了门槛。不过本篇的篇章安排和叙述逻辑，均由笔者把控和审阅，欢迎放心阅读。

1.1 为什么需要 gRPC

在深入技术细节前，必须理解 gRPC 诞生的背景。它本质上是 RPC (Remote Procedure Call) 技术的一种现代演进

RPC 的核心愿景是：让调用远程服务就像调用本地函数一样简单。

• 本地函数： result = calculator.add(a, b)，在内存中跳转，极快。
• 远程调用： result = request("http://api/add", {a, b})，需要跨越网络，面临延迟、丢包、序列化开销。

要掌握 gRPC，首先要明白它为什么要革 REST 的命：

gRPC 的高性能并非魔法，而是通过 空间效率（Protobuf 压缩率高）和 时间效率（HTTP/2 并发高、序列化快）的物理层优化换来的。

1.2 两大基石

1.2.1 Protocol Buffers (Protobuf)

不要只把它当作 XML/JSON 的替代品，要理解其 编码原理。

• TLV 格式： Protobuf 采用 Tag - Length - Value 的紧凑存储方式，没有字段名（字段名在编译后的代码中），只有字段编号 (Field ID)。
• Varint 编码： 对于整数，使用变长编码（Base 128 Varints）。例如数字 1 只需要 1 个字节存储，而不是标准的 4 个字节 (int32)。
• 向后兼容性： 掌握如何安全地增加、删除字段而不破坏现有的客户端（永远不要修改已存在的 Field ID）。

// The greeter service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

1.2.2 HTTP/2 传输机制

gRPC 强依赖 HTTP/2。你需要理解以下概念在 gRPC 中如何映射：

• Frame (帧)： HTTP/2 通信的最小单位。gRPC 的数据被封装在 DATA 帧中。
• Stream (流)： 一个 RPC 调用对应一个 Stream。
• HPACK： HTTP 头压缩。RPC 调用往往 Header 重复度高，HPACK 能极大减少带宽消耗。

1.3 四种模式与工程化

1.3.1 四种通信模式

• Unary RPC： 一问一答。适用于常规 API。
• Server Streaming： 客户端发一个，服务端回一堆。适用于：大列表数据、实时行情推送。
• Client Streaming： 客户端发一堆，服务端回一个。适用于：物联网传感器上报、大文件上传。
• Bidirectional Streaming： 双向实时对话。适用于：聊天室、实时游戏同步。

1.3.2 Interceptor (拦截器)

这是 gRPC 的中间件机制。彻底掌握它是做架构设计的关键。

• 用途： 鉴权 (Auth)、日志 (Logging)、监控 (Metrics)、分布式追踪 (Tracing)。
• 实践： 学会编写一个 UnaryServerInterceptor，在其中计算每个请求的耗时并打印日志。

笔者的开源项目 goapm 中提供了 gRPC Server 和 Client 的链路追踪封装，有需要的读者可参考。

1.3.3 Error Handling (错误处理)

gRPC 的错误不是 HTTP Status Code（虽然底层映射了）。

• gRPC Status Code： 掌握标准码的含义，如 OK(0), CANCELLED(1), DEADLINE_EXCEEDED(4), UNAVAILABLE(14)。
• Rich Error Model： 学会使用 google.rpc.Status 传递更详细的错误信息（如具体的字段校验错误），而不仅是一个简单的错误码。

1.4 注意事项

1.4.1 负载均衡的陷阱

• 问题： gRPC 基于 HTTP/2，连接是 长连接 (Persistent Connection)。一旦连接建立，后续请求都在同一个 TCP 连接中复用。
• 后果： 传统的 L4 负载均衡器（如 AWS NLB、LVS）只在连接建立时起作用。结果就是：一个后端实例累死，其他实例闲死。
• 解决方案：
  • 客户端负载均衡 (Client-side LB)： 客户端感知所有后端 IP（需配合 Service Discovery，如 Consul/Etcd），自己做轮询。
  • 代理负载均衡 (Proxy LB / L7 LB)： 使用支持 HTTP/2 的网关（如 Envoy, Nginx）来拆解请求并分发。

14.2 Deadlines (超时控制)

• 原则： 永远不要发起没有 Deadline 的 RPC 调用。
• 级联故障： 如果服务 A 调 B，B 调 C，A 必须设置超时，且该超时上下文 (Context) 应该传递给 B 和 C。如果 A 超时了，C 的运算也应该立即取消 (Context Cancel)，避免浪费资源。

2. 数据编码

为了更深入理解 gRPC 的高性能，从根本上掌握为什么 gRPC 要使用 Protobuf 编码格式。本篇将参考 Designing Data-Intensive Applications(DDIA) 一书，对业内常用的数据编码格式进行统一梳理。

2.1 JSON

基于文本的、自描述 (Self-describing) 的键值对格式。

https://www.json.org/json-en.html

JSON 实际上是一长串 Unicode 字符。

• 自描述性： 数据中包含了结构信息（{, }, [, ]）和字段名称。这意味着接收端不需要任何预先的沟通，只要有一个标准的 JSON 解析器就能读懂。
• 编码方式： 数字存储为字符串（ASCII/UTF-8）。例如整数 12345 在内存中通常是 4 字节整数，但在 JSON 中变成了 5 个字符 "1", "2", "3", "4", "5"，占用 5 个字节。

{
	"userName": "Martin",
	"favoriteNumber": 1337,
	"interests": ["daydreaming", "hacking"]
}

对于上面的例子，去掉空格后，JSON 格式需要占用 81 bytes。

2.2 Message Pack

二进制的 JSON (Binary JSON)。

https://msgpack.org/

MessagePack 的目标是：在保留 JSON 的灵活性的前提下，极致压缩体积和提升解析速度。 它不需要 Schema，依然存储 Key，但它引入了 类型前缀 (Type Prefix) 系统。

对于 JSON {"a": 1}，MessagePack 的二进制流可能如下：

1. Map 标记 (1 byte): 0x81
   • 0x8 表示这是一个 Map。
   • 0x1 表示这个 Map 有 1 个元素。
2. Key 标记 (1 byte): 0xa1
   • 0xa 表示这是一个 String。
   • 0x1 表示字符串长度为 1。
3. Key 内容 (1 byte): 0x61 (ASCII 'a')
4. Value (1 byte): 0x01，MessagePack 使用 FixInt，对于小整数，直接用一个字节存值，不需要额外的类型标记。

与 JSON 的核心差异：

• 无分隔符： 它不需要 { 或 :。解析器读到 0xa1 就知道接下来读 1 个字节作为字符串，无需扫描，直接进行内存拷贝，速度极快。
• Key 依然存在： 它虽然压缩了结构，但 "userName" 这种字段名依然被完整地编码进去了。

我们来看相同的例子：

{
	"userName": "Martin",
	"favoriteNumber": 1337,
	"interests": ["daydreaming", "hacking"]
}

对于上面列举的数据，MessagePack 会将其进行如下图所示编码：

1. 第 1 个字节 0x83表示接下来是一个对象（顶部四位 = 0x80），有三个字段（底部四位 = 0x03）。（如果你想知道，如果一个对象有超过15个字段，字段数不适合四位，它会得到不同的类型指示器，字段数编码为两字节或四字节。）
2. 第 2 个字节 0xa8 表示接下来是一个字符串（顶部四位 = 0xa0），长度为八字节（底部四位 = 0x08）。
3. 接下来的 8 个字节是 ASCII 中的字段名 userName。既然之前已经标明了长度，就不需要任何标记来告诉我们弦的终点（或任何逸出点）。
4. 接下来的 7 个字节编码带有前缀 0xa6 的六字母字符串值 Martin，依此类推。

同样的数据，MessagePack 将数据大小压缩到了 66 bytes。

2.3 Protocol Buffer

基于 IDL (接口定义语言) 的 Tag-Length-Value (TLV) 协议。

https://protobuf.dev/

Protobuf 的核心哲学是 "约定优于配置"。通信双方必须预先持有 .proto 文件（契约）。 因为有了契约，数据包里 完全抛弃了字段名，只保留了字段编号 (Field ID)。

其核心由三个机制组成：

1. Varint (Base 128): 用变长字节存储整数。数字 1 占 1 字节，数字 300 占 2 字节。
2. ZigZag: 将有符号整数映射为无符号整数，解决了负数 varint 编码效率低的问题。
3. TLV 结构: 每一个字段都是 $Tag + [Length] + Value$。$Tag$ 包含了 Field ID 和 Wire Type。

Protobuf 的关键是其兼容性：

• 向后兼容性：如果接收端的 .proto 是旧的，它读到了一个新的 Tag（例如 ID=5），它通过 Wire Type 知道这个字段的数据类型，因此它可以安全地 跳过 这段数据，继续解析下一个字段，而不会报错。
• 向前兼容性：如果接收端的 .proto 是新的，客户端没有传递新的字段，如果该字段被定义为 optional 可选的，则接收端依旧可以跳过该缺失的字段，继续解析下一个字段，而不会报错。

对于上面给出的例子，proto 文件定义如下：

message Person {
	required string user_name = 1;
	optional int64 favorite_number = 2;
	repeated string interests = 3;
}

1. 每一个字段都是 $Tag + [Length] + Value$。$Tag$ 包含了 Field ID 和 Wire Type。
2. 第 1 个字节 0x0a 的低 3 位 010 代表 Wire Type 2（Length-delimited，即后面跟着长度）。这告诉解析器：准备好读取一段指定长度的数据（通常是字符串或嵌套对象）。高 5 位 00001 代表 Field ID=1。
3. 第 2 个字节 0x06 表示接下来的数据长度为 6 字节。既然 Tag 里的 Wire Type 是 2，解析器就知道这里必须读一个 Varint 来确定长度。06 就是长度。
4. 接下来的 6 个字节 4d 61 72 74 69 6e 是 ASCII 编码的字符串值 "Martin"。解析器读完这 6 个字节后，知道当前字段结束，准备读取下一个 Tag。
5. 重点的对于数组，它们的 tag 是一样的，如上图都是 0x1a，Protobuf 会把一样的 tag 组成数组。

同样的数据，Protobuf 将数据大小压缩到了 33 bytes：

1. 没有 Key： 整个流里你找不到 "userName" 这个单词，只有 0x0a (ID=1) 和 0x10 (ID=2) 这样的编号。
2. 紧凑的数字： 1337 这种数字被压缩成了变长格式，且低位在前（Little Endian 风格）。
3. 无分隔符： 字符串没有结束符（如 \0），完全依靠前面的 Length (06, 0b, 07) 来精确定位边界。这使得解析过程可以利用内存拷贝（Memcpy），非常高效。

2.4 Thrift

全栈式的 RPC 框架与序列化协议。

https://thrift.apache.org/docs/

Thrift 是由 Facebook 开发的跨语言 RPC 框架。与 gRPC (Protobuf) 相比，Thrift 最显著的特点是它把"传输格式"抽象出来了：

• BinaryProtocol: 简单粗暴，不做压缩，解析速度极快，但占用带宽。
• CompactProtocol: 极致压缩，逻辑复杂，节省带宽（类似 Protobuf）。

其实还有 DenseProtocol，不过只支持 C++，不具备跨语言，所以暂不讨论。

对于上面给出的例子，thrift 文件定义如下：

struct Person {
	1: required string userName,
	2: optional i64 favoriteNumber,
	3: optional list<string> interests
}

2.4.1 BinaryProtocol

核心特征： 定长、豪横、浪费。它不喜欢做位运算，喜欢用标准的 4 字节（32位）或 8 字节（64位）来存储数字，哪怕数字很小。

我们看第一个字段 userName="Martin"：

1. 第 1 个字节 0b （Type）用于表示数据类型（String）。
2. 第 2-3 个字节 00 01 表示 Field ID = 1。用了 2 个字节表示 ID，很奢侈啊！
3. 第 4-7 个字节 00 00 00 06 表示字符串长度为 6。用了 4 个字节表示长度，真奢侈啊！
4. 第 8-13 个字节即为 Martin 的 ASCII 编码。

再来看第二个字段 favoriteNumber=1337：

1. 第 1 个字节 0a （Type）表示数据类型 I64。
2. 第 2-3 个字节 00 02 表示 Field ID = 2。
3. 第 4-11 个字节，用 8 字节的定长证书来表示 1337，真是奢靡！

接下来比较复杂的第三个字段 interest(List)：

1. 第 1 个字节 0f （Type）表示接下来是一个 List。
2. 第 2-3 个字节 00 03 表示 Field ID = 3。
3. 第 4 个字节 0b 表示数组元素的数据类型的 String。
4. 第 5-8 个字节 00 00 00 02 表示数组列表长度是 2，又是豪横的 4 字节整数。
5. 剩下的就是数组的两个元素的 Length + Value。

最后还有一个结尾字符 00，类似于 C 语言字符串的 \0，表示整个 Struct 结束。

同样的数据，Thrift Binary Protocol 用了 59 bytes：

2.4.2 CompactProtocol

核心特征： 变长、紧凑、巧妙。这一张图的逻辑和 Protobuf 非常像，但有一个关键的区别（Delta Encoding）。

我们看第一个字段 userName="Martin"：

1. 第 1 个字节 0x18 （Tag）跟 Protobuf 一样，是一个组合字节，低 4 位 1000 （Type）表示数据类型是 String，高 4 位 0001 （Delta）表示 FieldID = 上一个 ID + 1。因为这是第一个字段，所以 ID=1。
2. 第 2 个字节 06（Length） 表示字符串长度为 6。Compact Protocol 使用 Varint 存储长度 6。只占 1 字节。
3. 第 3-8 个字节即为 Martin 的 ASCII 编码。

再来看第二个字段 favoriteNumber=1337：

1. 第 1 个字节 0x16 （Tag）低 4 位 0110 （Type）表示数据类型是 i64，高 4 位 0001 （Delta）表示 FieldID = 上一个 ID + 1。因为这是第二个字段，所以 ID=1+1=2。
2. 第 2-3 个字节 f2 14 是 1337 的 ZigZag Varint 编码。和 Protobuf 一样，它把 1337 编码成了变长格式，只用了 2 个字节，而不是 BinaryProtocol 的 8 个字节。

接下来比较复杂的第三个字段 interest(List)：

1. 第 1 个字节 0x19 （Tag）低 4 位 1001（Type）代表数据类型 List，高 4 位 0001 （Delta）表示 FieldID=1+2=3。
2. 第 2 个字节 28 也是一个组合字节，低 4 位（ElemType）表示数组元素类型是 String，高 4 位（Size）代表有 2 个元组。
3. 剩下的就是数组的两个元素的 Length + Value。

最后一样有一个结尾字符 00 表示整个 Struct 结束。

同样的数据，Thrift Compact Protocol 用了 34 bytes：

2.5 Avro

Schema 与数据分离的、面向大数据的序列化协议。

https://avro.apache.org/

Avro 是为 Hadoop 生态系统设计的。它的第一性原理假设是：一次定义 Schema，处理百万条数据。 因此，Avro 采取了最激进的策略：数据包里连 Field ID (Tag) 都不存。

假设 Schema 定义如下：

{ "type": "record", "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"}
]}

对于数据 id=10, name="foo"，Avro 的二进制流里只有： [Varint 10] + [Length 3] + [Bytes 'foo']

• 没有 Key，没有 Tag： 没有任何标记告诉解析器 10 是 id。
• 依序解析： 解析器必须手里拿着 Schema，严格按照顺序读："Schema 说第一个字段是 int，那我读一个 Varint；Schema 说第二个是 string，那我读一个 string..."。

既然没有 ID，怎么处理 Schema 变更（比如加字段）？ Avro 引入了 Writer Schema（写数据时的格式）和 Reader Schema（读数据时的格式）。 在反序列化时，Avro 库会对比这两份 Schema：

• 如果 Reader 想要字段 A，但 Writer 里没有，且 Reader 定义了默认值，则自动填入默认值。
• 如果 Writer 有字段 B，但 Reader 不需要，则自动跳过。 这种 动态解析 能力使得它非常适合存储历史数据。

Avro 的优缺点也很明显：

• 优点： 对于大批量数据（数组、文件），体积最小（因为完全去除了每条记录的元数据）。支持动态 Schema。
• 缺点： 如果没有 Schema，数据完全是一堆乱码，无法解析。单条小数据传输时，如果还要带上 Schema，开销反而巨大。

我们还是回到前面介绍的例子，它的 avro 定义如下：

record Person {
	string userName;
	union { null, long } favoriteNumber = null;
	array<string> interests;
}

或者同等含义的 JSON 结构：

{
	"type": "record",
	"name": "Person",
	"fields": [
		{"name": "userName", "type": "string"},
		{"name": "favoriteNumber", "type": ["null", "long"], "default": null},
		{"name": "interests", "type": {"type": "array", "items": "string"}}
	]
}

对于上面的例子，Avro 会编码成如下图所示：

如前面所说的，在解析这张图之前，解析器必须先加载对应的 schema。

我们看第一个字段 userName="Martin"：

1. 第 1 个字节 0c （Length）表示字符串长度。那问题就来了，字符串 "Martin" 长度是 6，为什么这里是 12 (0x0c)？这是因为 Avro 对长度也使用了 ZigZag 编码。
   • Thrift/Protobuf 认为：长度永远是正数，所以用 无符号数 (Unsigned Varint)。
   • Avro 认为：为了统一简单的底层实现，所有整数都当 有符号数 (ZigZag Varint) 处理；而且在数组场景下，长度甚至 真的可以是负数（作为一个特殊标记）。所以 Avro **最低位**留给符号位，所以 1100 中，110 表示大小 6，而最后的 0 表示正数。
2. 第 2-7 个字节即为 Martin 的 ASCII 编码。前面没有任何 Tag 告诉我们这是 userName，解析器只是因为这是第一个字段所以把它当字符串读。

再来看第二个字段 favoriteNumber=1337：

1. 第 1 个字节 02 表示 Union Index，这是 Avro 的关键特性。 Schema 定义这个字段可能是 null，也可能是 long。数据流必须明确这次传的是哪个。由于 Schema 中定义的顺序是 [null, long]，所以 index0=null、index1=long。我们要选择 index1，又根据 ZigZag 编码，所以 $1×2=2=0x02$。
2. 第 2-3 个字节 f2 14 是 1337 的 ZigZag Varint 编码，跟 Protobuf/Thrift Compact 完全一致。

接下来比较复杂的第三个字段 interest(List)：

1. 第 1 个字节 0x04 表示接下来有 2 个元素（$2×2=4=0x04$)。
2. 剩下的就是数组的两个元素的 Length + Value。
3. 最后有一个 00 代表数组的结束标志。

同样的数据，Avro 只用了 33 bytes，这目前的最好成绩！

通过上图的分析，我们可以清晰地看到 Avro 与 Protobuf/Thrift 的根本区别：

1. 消失的 Tag：
   • Protobuf: 08 (Field ID=1) -> Value
   • Avro: 直接 Value
2. Length 的 ZigZag 化：
   • Protobuf 的长度就是单纯的 Varint。
   • Avro 连长度都要乘 2 (ZigZag)，这是为了保持整个协议整数编码的一致性。
3. **Union 的代价：**虽然省去了 Tag，但在处理 Nullable 字段时，Avro 需要一个额外的字节来标记非空。

2.6 总结

通过对同一个 Person 对象（包含 String, Int64, Array）的编码过程进行显微镜式的观察，我们可以从 空间效率 和 设计哲学 两个维度对这些数据编码协议进行最终的复盘。

在去除了所有不必要的空格和换行后，各协议的编码结果如下表所示：

从底层设计原理来看，这几种协议代表了三种不同的数据治理哲学：

1. 自描述模式 (Self-describing) —— JSON, MessagePack
   • 特征： 数据包内部自带 Schema 信息（键名、类型）。
   • 优势： 灵活性极高，无需预定义 IDL，完全解耦。
   • 劣势： 存在大量冗余信息，不适合高频或高吞吐场景。
2. 静态契约模式 (Static IDL) —— Protobuf, Thrift
   • 特征： 依赖预定义的 IDL 文件（.proto / .thrift）。数据包通过 Field ID（Tag）与 IDL 映射。
   • 优势： 实现了强类型约束与向后兼容性（Tag 机制），解析速度快。
   • 劣势： 需要维护 IDL 文件，客户端与服务端需同步更新代码。
3. 动态分离模式 (Schema-on-Read) —— Avro
   • 特征： 数据与 Schema 分离（或在文件头仅定义一次）。数据体中不包含任何字段标识，仅包含值。
   • 优势： 在处理大规模数据集（如数仓文件）时，消除了每条记录的元数据开销。支持读写 Schema 动态演进。
   • 劣势： 必须严格依赖 Schema 解析，单条数据传输时若需附带 Schema 则开销巨大。

在实际架构设计中，应根据业务场景的 I/O 特性 与 协作模式 进行选择：

• 对外 API / 前端交互 / 调试接口 $\rightarrow$ JSON
  • 优先考虑可读性与通用性，浏览器原生支持是其不可替代的优势。
• 微服务内部通信 (RPC) $\rightarrow$ Protobuf (gRPC)
  • 强契约（IDL）能有效降低多人协作中的接口不一致风险，且 Google 生态支持完善。
• 大数据存储与离线分析 (Data Lake) $\rightarrow$ Avro
  • 在 HDFS/S3 存储 TB 级数据时，移除 Tag 带来的存储成本节省十分显著，且适合 Schema 频繁变更的 ETL 场景。
• 遗留系统或特定语言栈 $\rightarrow$ Thrift
  • 如果需要完整的 RPC 框架且不仅限于序列化（如需要特定的 Server 模型），或者在 Protobuf 支持较弱的语言环境中使用。

3. 总结

回顾 gRPC 的设计架构，我们可以清晰地看到，其高性能并非源于单一技术的突破，而是源于 传输层 (HTTP/2) 与 表示层 (Protobuf) 两个维度的深度优化叠加。gRPC 从第一性原理出发，分别解决了网络通信中的"拥塞"与"冗余"问题。

在表示层，gRPC 坚定地选择了 Protocol Buffers，这不仅仅是为了更小的体积，更是为了更严谨的契约。

• 极高的信噪比：通过前文的字节级解剖，我们看到 Protobuf 将一个包含丰富信息的 Person 对象压缩至 33 bytes，仅为 JSON (81 bytes) 的 40%。它通过移除字段名（Keys）并使用 Varint/ZigZag 压缩数字，极大地减少了网络带宽的占用。
• 解析效率：二进制协议允许计算机通过位运算直接解析数据，避免了文本协议中昂贵的字符串匹配与浮点数转换开销。
• 强契约保证：IDL (.proto) 的存在使得通信双方必须遵守严格的类型约束，这种“静态”特性消除了运行时猜测数据类型的成本，同时也为大规模微服务治理提供了坚实的基础。

在传输层，gRPC 摒弃了文本格式的 HTTP/1.1，全面拥抱二进制的 HTTP/2，这从物理上改变了连接的使用方式。

• 多路复用 (Multiplexing)：这是 HTTP/2 最核心的优势。gRPC 允许在同一个 TCP 连接上并发处理多个请求（Stream）。每个 Request/Response 被拆分成多个二进制帧 (Frame) 并打乱发送，接收端根据 Stream ID 重新组装。这彻底解决了 HTTP/1.1 的 队头阻塞 (Head-of-Line Blocking) 问题，使得单一连接的吞吐量成倍提升。
• 头部压缩 (HPACK)：在微服务架构中，RPC 调用往往伴随着大量重复的 Header (如 Auth Token, Tracing ID)。HTTP/2 使用 HPACK 算法在客户端和服务端维护动态字典，对 Header 进行增量压缩，进一步减少了带宽消耗。
• 双向流 (Bi-directional Streaming)：得益于 HTTP/2 的流特性，gRPC 原生支持四种通信模式，使得实时推送、长连接对话等复杂业务场景的实现变得像普通函数调用一样简单。

最终，彻底掌握 gRPC 意味着理解它在 互操作性 与 性能 之间所做的权衡：

1. 它不是万能的：在浏览器前端、简单的 CRUD 接口或对调试可读性要求极高的场景下，REST/JSON 依然是更优的选择。
2. 它是云原生的通用语：在微服务内部通信、移动端与后端的长连接交互、以及低延迟高吞吐的系统中，gRPC 凭借其 Protobuf 的极致编码 与 HTTP/2 的高效传输，成为了现代分布式系统事实上的标准。

理解了这些底层原理，我们才能在架构选型时，不盲目跟风，而是根据业务的真实需求（是追求极致的 Bytes 节省，还是追求开发的灵活性），做出最准确的技术决策。

本文不会特别深入和细节地探讨各个协议的底层实现，会尽量从第一性原理去介绍为什么要出现这些协议，以及这些协议的适应场景是什么。

要真正理解 HTTP、Streamable HTTP、SSE、WebSocket 和 gRPC这几者的区别，我们不能仅停留在 API 调用的表面，而需要回到网络通信的第一性原理：TCP 连接的使用方式、数据编码格式以及协议层面的抽象。绝大多数现代网络通信（除了 HTTP/3 基于 UDP）都建立在 TCP 之上。这五种技术的本质区别，实际上是如何利用 TCP 连接以及如何定义数据交换的格式。

1. 协议速览

HTTP/1.1

这是互联网的基石。在最原始的模型中，它遵循一次请求，一次连接的模式（虽然 Keep-Alive 改善了复用，但逻辑上仍是独立的）。

• 底层原理： 客户端发起 TCP 握手 -> 发送 HTTP Header + Body -> 服务器处理 -> 返回 HTTP Header + Body -> (可能) 关闭连接。
• 通信模式： 严格的半双工（Half-duplex）逻辑。客户端不问，服务器不说。
• 数据格式： 通常是 JSON (文本) 或 XML。可读性好，但序列化/反序列化有性能损耗。
• 缺点： 头部冗余（Header overhead）大。如果要实时获取数据，必须使用 轮询 (Polling)，这会制造大量的无效请求，浪费服务器资源和带宽。

关于 HTTP 更多细节可参阅：从 HTTP1.0 到 HTTP3 的演化

Streamable HTTP

Streamable HTTP 本质上仍然是 HTTP，但利用了 HTTP/1.1 的一个特性：Transfer-Encoding: chunked。

• 底层原理：
  1. 客户端发送标准 HTTP 请求。
  2. 服务器在响应头中声明 Transfer-Encoding: chunked，并不返回 Content-Length（因为长度未知）。
  3. 服务器通过同一个 TCP 连接，分批次（Chunk）发送数据块。
  4. 发送一个长度为 0 的块表示传输结束。
• 通信模式： 单向流（Server -> Client）。连接保持打开，直到传输完成。
• 适用场景： 生成式 AI（LLM）的打字机效果、大文件下载、动态生成的报表。

SSE

SSE 是 Streamable HTTP 的一种标准化封装，专门用于浏览器端的服务器推送。它规定了特定的 Content-Type: text/event-stream 和数据格式（data: ...）。

• 底层原理：
  1. 客户端发起 HTTP 请求。
  2. 服务器挂起连接，不关闭。
  3. 服务器有数据时，通过该连接直接写入遵循特定格式的文本流。
  4. 浏览器原生支持 EventSource API，能自动处理断线重连。
• 与 WebSocket 的本质区别： SSE 依然是 HTTP 协议。它不需要协议升级，防火墙友好，但只能 服务器 -> 客户端 单向传输。
• 适用场景： 股票行情更新、新闻推送、CI/CD 日志流、系统状态监控。

关于 SSE 更多细节可参阅：Rust 实战丨SSE(Server-Sent Events)

WebSocket

WebSocket 旨在解决 HTTP "请求-响应"模式在实时双向通信上的无能。它从 HTTP 开始，但随后"背叛"了 HTTP。

• 底层原理：
  1. 握手： 客户端发送一个 HTTP 请求，带上 Upgrade: websocket 头。
  2. 升级： 服务器如果同意，返回 101 Switching Protocols。
  3. 裸奔： 此刻起，HTTP 协议层消失，连接变成了原始的 TCP 通道（Over TCP）。
  4. 帧（Frame）： 双方可以在这个通道上自由地发送自定义的二进制帧或文本帧，不再受 HTTP Header 的束缚。
• 通信模式： 真正的全双工（Full-duplex）。客户端和服务器地位对等，谁都可以随时发消息。
• 缺点： 状态管理复杂（需要处理心跳、重连、鉴权），且不支持 HTTP 的语义（如 404、500 状态码，需要自己定义业务层协议）。
• 适用场景： 多人在线游戏、实时聊天室、协同编辑文档。

gRPC

gRPC 是 Google 开发的高性能框架。它和前面几个不在一个维度：WebSocket 是一种协议，而 gRPC 是一个框架，它默认基于 HTTP/2 协议。

• 底层原理：
  1. HTTP/2 多路复用： 也就是在一个 TCP 连接上并发处理多个请求，解决了 HTTP/1.1 的队头阻塞问题。
  2. Protobuf (Protocol Buffers)： 放弃 JSON，使用二进制序列化。数据极其紧凑，且需要预先定义 .proto 文件（Schema）。
  3. RPC (远程过程调用)： 对开发者屏蔽了网络细节。你调用远程服务器的 GetUser() 方法，就像调用本地函数一样。
• gRPC 支持四种模式：
  1. 简单 RPC（类似标准 HTTP）。
  2. 服务端流式（类似 SSE）。
  3. 客户端流式。
  4. 双向流式（类似 WebSocket）。
• 缺点： 浏览器支持较差（需要 gRPC-Web 代理），调试不如 JSON 直观（是乱码的二进制）。
• 适用场景： 微服务内部通信（高频、低延迟）、IoT 设备通信、多语言混合开发环境。

对比

2. 为什么 MCP 弃用 SSE

https://blog.fka.dev/blog/2025-06-06-why-mcp-deprecated-sse-and-go-with-streamable-http/

color="orange" 总结

废弃 SSE 不是因为它传输文本格式不好，而是因为"长连接订阅模式"在复杂的 RPC（远程过程调用）场景下是一种架构错误。

MCP 从 SSE 转向 Streamable HTTP，本质上是从 异步的消息总线模式 回归到了 同步流式的 RPC 模式。后者更简单、更健壮，也更符合 AI Agent 这种"一来一回"的思考特性。

2.1 核心痛点：双通道架构

这是博客中提到的最直观的原因。

• 旧的 SSE 模式（Legacy MCP）： 你必须维护两条独立的连接才能完成一次对话：

  1. 听筒（GET /sse）： 建立一个长连接，专门用来听服务器说话（接收 Event）。
  2. 话筒（POST /messages）： 每次要说话时，发起一个新的短连接，专门用来发指令。

  比喻： 就像你给朋友打电话，手里拿着两个手机。左手拿一个手机只听不因，右手拿另一个手机只发短信。朋友回话还得通过左手的手机传过来。

• 新的 Streamable HTTP 模式： 回归单通道。 你发送一个 POST 请求（说话），服务器直接在这个请求的 Response 里通过流式传输回话（听）。代码复杂度指数级下降。不再需要维护一个"永远在线"的幽灵连接，也不需要处理"指令发出去了，但接收通道断了"这种分布式系统里的脑裂状态。

2.2 基础设施的敌意

博客中重点提到了这一点，这是运维层面的第一性原理。

• SSE 的长连接诅咒： 旧版 MCP 要求 /sse 连接必须一直活着。
  • 现实世界： 企业的防火墙、Nginx 负载均衡器、云服务网关（AWS ALB, Cloudflare）非常讨厌占着茅坑不拉屎的空闲长连接。它们会强行切断这些连接（Timeout）。
  • 后果： 客户端必须不断写复杂的保活（Keep-alive）和重连逻辑。
• Streamable HTTP 的优势： 它是**按需（On-Demand）**的。
  • 有任务？发个 POST，保持连接直到任务结束。
  • 没任务？连接自然关闭。
  • 这完全符合 HTTP 的设计初衷，对所有的中间件（Middleware）都非常友好。

2.3 状态管理的灾难

这也是博客中提到的关键技术细节。

• SSE 的状态同步难题： 在旧模式下，因为"听"和"说"是分离的，很容易出现竞态条件（Race Condition）。
  • 比如：客户端刚发了一个 POST 指令，但在服务器回包之前，SSE 连接断了。此时服务器把结果推给了谁？数据丢了吗？客户端重连后还能收到刚才的结果吗？
  • 为了解决这个问题，需要引入复杂的 Session ID 和消息队列机制。
• Streamable HTTP 的原子性： 请求和响应绑定在同一个 TCP 上下文里。
  • 连接断了 = 请求失败。逻辑非常清晰（要么成功，要么重试），不需要在应用层去猜测数据去哪了。

2.4 为什么博客中提到它依然支持 SSE 格式？

这是一个容易混淆的点。

博客中澄清了：Streamable HTTP 依然可以使用 text/event-stream 作为数据传输的格式（Framing），但它改变的是传输的载体（Transport）。

• 旧 MCP： SSE 是一个订阅频道（Pub/Sub）。
• 新 MCP： SSE 只是 POST 响应体里的一种编码方式。

OpenAI 和 Anthropic 现在的做法也是如此：他们不再使用浏览器原生的 EventSource（那个只能 GET 的订阅 API），而是使用 fetch POST 请求，然后把响应体当成流来处理。

HTTP1.0

HTTP/1.0 的设计初衷只是为了在网络上传输 HTML 文档。

• 模型：Request-Response（一问一答）。

• 底层：基于 TCP。

• 瓶颈：TCP 连接成本过高。

  • 在 1.0 默认行为中，每一次 HTTP 请求（比如下载一张图片）都要新建一个 TCP 连接。

  • TCP 三次握手：这意味着每个请求都要先消耗 1.5 个 RTT（往返时延）才能开始发数据。

  • TCP 慢启动（Slow Start）：新连接的速度是从低到高爬坡的，短连接导致 TCP 永远在低速爬坡阶段就断开了，带宽利用率极低。

HTTP1.1

为了解决连接成本问题，HTTP/1.1 在 1999 年成为了标准，并统治互联网长达 15 年。

1. Keep-Alive（长连接）：解决连接复用

• 机制：引入持久连接（Persistent Connection）。默认 Connection: keep-alive。
• 效果：只要连接不断开，后续请求可以直接发送，省去了三次握手和 TCP 慢启动的开销。
• 细节：设置 Keep-Alive: timeout=5, max=100 来控制连接的生命周期。

2. Pipeline（管道化）：解决串行等待（失败的尝试）

• 尝试：允许客户端一口气发出去 10 个请求，不用等第一个回来再发第二个。
• 致命缺陷：HTTP 层面的队头阻塞（HOL Blocking）。
  • 服务器必须按照接收请求的顺序返回响应（FIFO）。如果第 1 个请求处理很慢（比如数据库查询），第 2-10 个请求即使处理完了，也必须排队等待第 1 个发送完毕。
  • 由于这个风险，浏览器厂商默认都关闭了 Pipeline。

3. Transfer-Encoding: chunked（分块传输）

• 痛点：HTTP/1.0 需要在 Header 里通过 Content-Length 告诉对方包体多大。如果是动态生成的流（比如视频、动态页面），服务器必须先把所有数据生成完算出长度才能发，延迟太高。
• 解决：chunked 模式允许服务器产生一部分数据就发一部分，最后发一个长度为 0 的块表示结束。这使得流式传输成为可能。

4. 缓存控制增强

• 引入 Cache-Control、Etag、If-None-Match，比 1.0 的 Expires 和 Last-Modified 提供了更精细的缓存策略，节省带宽。

HTTP2

HTTP/1.1 虽然有了长连接，但本质上请求还是串行的。为了并发下载资源，浏览器被迫对同一个域名开启 6 个 TCP 连接。HTTP/2 旨在解决这个问题。

1. 核心改变：二进制分帧层 (Binary Framing Layer)

这是 HTTP/2 的基石。

• HTTP/1.1：纯文本，换行符分隔。解析慢，且无法交错。
• HTTP/2：将报文切分为更小的Frame（帧）。
  • Headers Frame：存放头部。
  • Data Frame：存放包体。
• 意义：机器解析二进制比解析文本快得多，更重要的是，这为多路复用提供了基础。

2. 多路复用 (Multiplexing)：解决 HTTP 队头阻塞

• 机制：在一个 TCP 连接中，通过 Stream（流） 的概念，同时传输多个请求的数据帧。
  • 每个帧都有一个 Stream ID。
  • 比如：Stream 1 的帧和 Stream 2 的帧可以乱序发送，接收端根据 ID 重新组装。
• 彻底解决：HTTP/1.1 的队头阻塞。请求 A 的处理慢，完全不影响请求 B 的数据传输。

3. HPACK：头部压缩

• 痛点：HTTP/1.1 的 Header 很多是冗余的（如 Cookie, User-Agent），每次都要重复发几百字节，浪费带宽。
• 原理：
  • 静态表：预定义 61 个常用头部（如 method: GET 对应索引 2）。传输时只传索引号（1 个字节）。
  • 动态表：连接建立后，双方动态维护一个表。第一次发过 User-Agent 后，把它存入动态表，下次只发索引即可。
  • Huffman 编码：对字符串进行压缩。

TLS1.2

在进入 HTTP3 之前，先来阐述一下 TLS1.2 和 TLS1.3，它们都是 HTTPS 的基石。

HTTPS 常用的密钥交换算法有两种，分别是 RSA 和 ECDHE 算法。

其中，RSA 是比较传统的密钥交换算法，它不具备前向安全的性质，因此现在很少服务器使用的。而 ECDHE 算法具有前向安全，所以被广泛使用。

1. RSA

我们先回顾一下 RSA 方式的密钥交换，笔者发现大多数的书籍和文章介绍的都是这种方式。但事实上因为它不具备前向安全的性质，现在很少被服务器所使用。

1. 客户端发送 ClientHello：客户端向服务器发送 ClientHello 消息，包含支持的 TLS 版本、加密算法列表、压缩方法以及一个随机数（Client Random），用于后续生成会话密钥。
2. 服务器发送 ServerHello：服务器收到 ClientHello 后，选择一个 TLS 版本和加密算法，发送 ServerHello 消息，包含选择的版本、加密算法、另一个随机数（Server Random）以及服务器的数字证书（包含公钥和 CA 信息）。
3. 客户端验证证书并生成预主密钥：
   • 客户端验证服务器的数字证书，检查是否由受信任的 CA 颁发（一直验证到根 CA）、是否在有效期内、域名是否匹配。如果验证通过，客户端生成一个预主密钥（Pre-Master Secret），并用服务器的公钥加密后发送给服务器。
   • 结合预主密钥，结合 Client Random 和 Server Random，生成对称加密的会话密钥（Session Key）。
   • 并把迄今为止的通信数据内容生成一个摘要，形成 Finished 报文，发送给服务端。
4. 服务端生成会话密钥：
   • 服务器使用私钥解密客户端发送的预主密钥，结合 Client Random 和 Server Random，用跟客户端相同的算法生成对称加密的会话密钥（Session Key）。
   • 然后发送 Finished 报文。
5. 完成握手：如果双方都能正确解密对方的 Finished 消息，握手成功。
6. 加密传输数据：握手完成后，客户端和服务器使用会话密钥对所有通信数据进行加密和解密，确保数据的机密性和完整性。

2. ECDHE

向前安全的定义

即便现在私钥泄漏了，也无法破解过去截获的流量。

为什么说 TLS 1.2 使用 RSA 握手会有前向安全（Forward Secrecy）的问题呢？

在 TLS 1.2 (RSA) 中，最终用来加密数据的 Session Key 是这样算出来的：

$$ Session\ Key = Function(ClientRandom, ServerRandom, Pre\text{-}Master\ Secret) $$

因为 ClientRandom 和 ServerRandom 都是明文的，所以整个会话的安全性，完全变成了"如何保护 Pre-Master Secret"这一个问题。

只要私钥一旦泄露，那黑客就可以根据过完的 ClientRandom 和 ServerRandom 以及解密后的 pre-master-secret 还原所有的历史消息。

ECDHE 旨在解决这个问题。这个名字由四部分组成：

• EC (Elliptic Curve)：椭圆曲线。相比 RSA，它用更短的密钥就能实现同等强度，计算更快，带宽更省。
• DH (Diffie-Hellman)：密钥交换算法。它的魔力在于：双方只交换公钥，就能算出同一个密钥，而无需传递密钥本身。
• E (Ephemeral)：临时（关键点！）。指每次握手生成的"私钥"都是临时的，用完即焚。

它的核心原理是：核心原理（离散对数难题）。

为了不陷入复杂的数学证明，我们用最简化的数学逻辑描述：

假设椭圆曲线上有一个基点 $G$。

1. Client 生成一个随机临时私钥 $a$，计算公钥 $A = a \cdot G$，发给 Server。
2. Server 生成一个随机临时私钥 $b$，计算公钥 $B = b \cdot G$，发给 Client。
3. 计算共享密钥：
   • Client 计算：$S = a \cdot B = a \cdot b \cdot G$
   • Server 计算：$S = b \cdot A = b \cdot a \cdot G$
   • 结果一样！双方都得到了 $S$。

注意：黑客截获了 $A$ 和 $B$，但根据椭圆曲线离散对数难题，他无法反推出 $a$ 或 $b$，因此算不出 $S$。

为什么 ECDHE 有前向安全？在 ECDHE 中，Session Key 依然需要三个参数，但第三个参数的来源变了：

1. ClientRandom（明文，可见）。
2. ServerRandom（明文，可见）。
3. ECDH 算出的共享密钥（替代了原来的 Pre-Master Secret）。

关键区别在于：

• 这个共享密钥是 Client 和 Server 通过交换**临时的（Ephemeral）**公钥 $A$ 和 $B$ 算出来的。
• 在这个过程中，服务器的长期私钥仅仅用来"签名"（证明 $B$ 是我发的），而不参与密钥的加密或计算。
• 握手结束后，Client 和 Server 会把计算用的临时私钥 $a$ 和 $b$ 删掉。

我们来看使用 ECDHE 的握手流程：

1. 客户端发送 ClientHello： 客户端向服务器发送 ClientHello 消息，包含支持的 TLS 版本、加密算法列表（必须包含 ECDHE 算法）、压缩方法以及一个随机数（Client Random）。

2. 服务器发送 ServerHello 和密钥协商参数： 服务器收到 ClientHello 后，选择 ECDHE 算法，发送 ServerHello（包含选择的版本、算法、Server Random）以及服务器数字证书。

   关键区别：服务器会在本地生成一对临时的椭圆曲线公私钥。它将服务器临时公钥发送给客户端，并用证书中的长期私钥对这个临时公钥进行数字签名，以防止篡改。

3. 客户端验证并协商预主密钥：

   • 客户端验证服务器证书的合法性。并用证书中的长期公钥验证收到的服务器临时公钥的签名是否有效。

   • 验证通过后，客户端也在本地生成一对临时的椭圆曲线公私钥。

   • 计算预主密钥：客户端利用自己的临时私钥和收到的服务器临时公钥，通过 ECDH 算法在本地计算出预主密钥（Pre-Master Secret）。

   • 客户端将自己的临时公钥明文发送给服务器。

   • 结合算出的预主密钥、Client Random 和 Server Random，生成会话密钥（Session Key），并发送 Finished 报文。

4. 服务端计算预主密钥：

   • 计算预主密钥：服务器收到客户端的临时公钥后，利用自己的临时私钥和收到的客户端临时公钥，通过同样的 ECDH 算法在本地计算出一模一样的预主密钥。
   • 结合预主密钥、Client Random 和 Server Random，生成相同的会话密钥（Session Key），并发送 Finished 报文。

5. 完成握手： 如果双方都能正确解密对方的 Finished 消息，握手成功。双方立即删除各自生成的临时公私钥（实现前向安全）。

6. 加密传输数据： 握手完成后，客户端和服务器使用会话密钥对通信数据进行加密传输。

TLS1.3

TLS 1.2 虽然支持 ECDHE，但握手还是很慢（需要 2-RTT），而且保留了很多不安全的加密算法。TLS 1.3 做了大刀阔斧的改革。

TLS 1.2 的逻辑是："先打招呼，商量用什么算法，再交换密钥"。 TLS 1.3 的逻辑是："我猜你会用这个算法，先把公钥给你！"

1-RTT

通过上述流程图可以看到，TLS1.3 直接从 2-RTT 缩短到了 1-RTT：

• Client 在发 ClientHello 时，不再干等服务器选算法，而是直接猜测服务器支持 ECDHE，并直接把自己的Key Share（临时公钥） 一起发过去。
• Server 收到后直接生成密钥，回复 ServerHello + Finished。握手直接结束。

0-RTT

更进一步，如果是连接恢复的情况，TLS1.3 还可以做到 0-RTT。

在初始连接 1-RTT 之后，在连接结束前，服务器会生成一个极其重要的数据结构，叫做 Session Ticket（会话票据），并通过 NewSessionTicket 指令发给客户端。Session Ticket 包含了 Pre-Shared Key（预共享密钥）

• 一个 PSK (Pre-Shared Key，预共享密钥)：这是从当前的会话主密钥衍生出来的一个秘密数据。
• 有效期、加密算法等信息。
• 这个 Ticket 通常只有服务器能解密（用服务器只有自己知道的密钥加密）。

客户端收到 Ticket 后，把它安全地存在本地（比如浏览器的缓存里），然后断开连接。

假设过了几个小时，用户又打开了同一个网站。客户端发现本地有上次存的 Ticket。

客户端动作：

1. 取出 PSK：客户端从 Ticket 里提取出 PSK。
2. 生成早期密钥：客户端利用这个 PSK，结合当前的 Client Random，提前算出用于加密早期数据（Early Data）的密钥。
3. 客户端构造一个超级数据包，一次性发给服务器：
   • ClientHello：标准的问候，包含支持的算法、随机数。
   • Session Ticket
   • Key Share：为了保险起见，依然带上新的 ECDHE 临时公钥（万一 0-RTT 失败了，可以无缝降级回 1-RTT）。
   • Early Data (加密的)：这是重点！用刚才算的早期密钥加密的 HTTP 请求（如 GET /index.html）。

服务器动作：

1. 收到大礼包：服务器收到这一大堆数据。
2. 验证凭证：服务器解密 Session Ticket，确认它有效，并从中提取出 PSK。
3. 尝试解密：服务器用提取出的 PSK，算出同样的早期密钥，尝试解密后面的 Early Data。
4. 并行处理（极速的核心）：
   • 路径 A（应用层）：如果解密成功，服务器立即把解出来的 HTTP 请求（GET /）交给后端应用（比如 Nginx/Tomcat）去处理。此时此刻，握手甚至还没完成，但服务器已经开始干活了！
   • 路径 B（握手层）：与此同时，服务器利用客户端发来的 Key Share，完成标准的 ECDHE 密钥协商，生成新的、具有前向安全的正式会话密钥。
5. 回复：服务器发送 ServerHello + Finished（完成握手），紧接着发送用新密钥加密的 HTTP 响应（网页内容）。

效果对比：

• 1-RTT：客户端发送 -> 服务器处理握手 -> 服务器回复握手完成 -> 客户端发送 HTTP 请求 -> 服务器处理并回复网页。
• 0-RTT：客户端发送(含 HTTP 请求) -> 服务器处理握手并同时处理 HTTP 请求 -> 服务器回复握手完成和网页内容。
• 用户感受到网页加载的时间，整整少了一个 RTT。在跨国网络或移动网络下，这可能是几百毫秒的提升。

然而！天下没有免费的午餐。0-RTT 带来了极致的速度，也引入了一个巨大的安全风险。

在标准的 ECDHE 握手中，每次的密钥都是基于全新的 Client Random 和 Server Random 实时计算出来的。黑客录制了昨天的握手数据包，今天重新发给服务器，服务器一看随机数是旧的，或者因为没有对应的临时私钥无法算出正确的密钥，直接就拒绝了。

然而 0-RTT 用于加密 Early Data 的密钥，是基于以前的 PSK 衍生出来的，所以是存在重放危险的！

由于这个致命缺陷，TLS 1.3 标准明确建议：千万不要用 0-RTT 发送非幂等（Non-Idempotent）请求！

• 安全场景：GET 请求（如获取图片、网页）。重放多少次结果都一样，没副作用。
• 危险场景：POST、PUT、DELETE 等改变服务器状态的请求。

HTTP3

HTTP/3 不再使用 TCP，而是基于 Google 开发的 QUIC（Quick UDP Internet Connections），底层使用 UDP。

1. 核心机制

• 机制 1：独立的流控制（解决 TCP 队头阻塞）
  • QUIC 在用户态（User Space）实现了类似 TCP 的可靠传输。
  • 但它知道"流"的概念。如果 Stream 1 丢包，QUIC 只会阻塞 Stream 1，Stream 2 的数据包可以直接交给浏览器渲染。
• 机制 2：连接迁移 (Connection Migration)
  • TCP：使用四元组（源 IP, 源端口, 目的 IP, 目的端口）标识连接。手机从 Wi-Fi 切到 4G，源 IP 变了，连接断开，必须重连。
  • QUIC：使用 Connection ID (CID) 标识连接。只要 CID 不变，IP 变了也能继续传输，实现无缝网络切换。
• 机制 3：内置 TLS 1.3
  • HTTP/3 没有把 TLS 当作上层协议，而是直接将 TLS 1.3 的握手过程嵌入到 QUIC 的建立过程中。
  • 传输层握手 + 加密层握手合并，实现真正的 1-RTT 建连（TCP+TLS 需要分别握手）。
• 机制 4：用户态拥塞控制
  • TCP 的拥塞控制（CUBIC, BBR）在操作系统内核里，升级困难（需要更新 OS）。
  • QUIC 在应用层实现，浏览器更新一下就能换用最新的拥塞控制算法，迭代极快。
• QPACK：
  • HTTP/2 的 HPACK 依赖于数据的顺序到达（更新动态表）。
  • 由于 QUIC 允许乱序，HPACK 失效。HTTP/3 引入了 QPACK，专门适配乱序环境下的头部压缩。

2. 握手机制

接下来我们重点讨论 QUIC（HTTP3）的握手机制。QUIC 的握手是其最核心的创新之一，它解决了 TCP + TLS 分层架构带来的根本性低效问题。

在传统的 HTTPS (HTTP/2) 中，网络栈是分层的：

1. TCP 层：先花 1-RTT（三次握手）建立可靠连接。此时数据是明文的。
2. TLS 层：再花 1-RTT（TLS 1.3）在 TCP 之上协商密钥。

总共需要 2-RTT 才能开始发 HTTP 数据。

QUIC 的革命性设计：融合层级

QUIC 基于 UDP，UDP 没有连接的概念。QUIC 协议栈直接包含了 TLS 1.3 模块。 QUIC 的握手目标是：**在建立逻辑连接的同时，完成加密密钥的协商。**它把这两个步骤合并成了真正的 1-RTT。

在深入 QUIC 的握手机制之前，我们需要先了解几个 QUIC 特有的概念：

1. Connection ID (CID, 连接 ID)：

   • 因为 UDP 没有连接，IP 地址和端口又可能会变（比如手机切网络），QUIC 使用 CID 来标识一个连接。

   • 每个数据包头都会带上目标 CID (DCID) 和源 CID (SCID)。这使得连接可以迁移。

2. 报文类型 (Packet Types)：

   • QUIC 在握手阶段使用特殊的长首部（Long Header）报文。

   • Initial 包：用于承载 TLS 的 ClientHello 和 ServerHello。

   • Handshake 包：用于承载加密后的 TLS 握手消息（如证书、Finished）。

   • 0-RTT 包：用于承载 0-RTT 的早期应用数据。

   • Short Header 包：握手完成后，传输普通应用数据使用。

3. 反放大攻击 (Anti-Amplification)：

   • 由于 UDP 容易被伪造 IP 进行 DDoS 攻击（发送小包骗取大包回复），QUIC 规定在验证客户端 IP 地址之前，服务器回复的数据量不能超过客户端发送数据量的 3 倍。

2.1 1-RTT

这是最基础的场景，目标是达到 TLS 1.3 的 1-RTT 效果，但不需要 TCP 握手。

步骤 1：客户端发送 Initial 包

• 外层 (QUIC)：客户端生成一个随机的各种 CID。封装一个 Initial 类型的 QUIC 包。
• 内层 (TLS 1.3)：包含标准的 TLS ClientHello 消息。
  • 带着 Key Share（猜测的临时公钥，如 X25519 公钥 A）。
  • 带着 TLS 版本、加密套件列表等。
• 注意：这个包本身也需要加密，但因为还没协商密钥，所以使用一个协议标准里写死的"初始密钥"进行模糊化（Obfuscation），主要为了防干扰，不防黑客。

步骤 2：服务器回复 Initial + Handshake 包

• 服务器收到包，提取出 ClientHello，交给内置的 TLS 模块处理。

• TLS 模块生成自己的临时公钥 B，算出握手密钥（Handshake Keys）。

• 服务器需要连续发送两个逻辑上的包（可能会合并在一个 UDP 数据报里）：

  1. QUIC Initial 包：包裹着 TLS ServerHello（包含服务器的临时公钥 B）。这个包用初始密钥模糊化。
  2. QUIC Handshake 包：包裹着 TLS 的后续消息——证书 (Certificate)、签名 (CertificateVerify)、结束消息 (Finished)。
  • 关键点：这个 Handshake 包是使用刚才算出来的握手密钥加密的。这是第一批真正加密的数据。

步骤 3：客户端完成握手并发送数据

• 客户端收到 ServerHello，算出握手密钥。
• 用握手密钥解密后续的 Handshake 包，验证证书和签名。
• 验证成功后，客户端算出最终的传输层会话密钥（1-RTT Keys）。
• 发送两个逻辑包：
  1. QUIC Handshake 包：包裹着客户端的 TLS Finished 消息（用握手密钥加密）。
  2. QUIC Short Header 包：包裹着真正的 HTTP/3 请求数据（如 GET /），用最终会话密钥加密。
• 握手结束。

2.2 0-RTT

如果你理解了 TLS 1.3 的 0-RTT 原理（利用之前的 PSK/Ticket），QUIC 只是把它封装到了特定的包类型中。

所以它跟 TCP+TLS1.3 的 0-RTT 一样会存在重放危险。

步骤 1：客户端发送 Initial + 0-RTT 包（大礼包）

• 客户端找到了上次连接存下来的 Session Ticket (PSK)。
• 客户端使用 PSK 生成"早期数据密钥"。
• 客户端一股脑发送出去：
  1. QUIC Initial 包：包含 TLS ClientHello，里面带着 PSK Ticket，同时也带着新的 Key Share (以防 0-RTT 失败回退到 1-RTT)。
  2. QUIC 0-RTT 包：使用早期密钥加密的 HTTP 请求数据。

步骤 2：服务器并行处理

• 服务器收到这些包。TLS 模块验证 PSK 成功。
• 关键动作（并行）：
  • 服务器使用 PSK 算出早期密钥，立即解密 0-RTT 包里的 HTTP 请求，交给后端应用处理。
  • 同时，服务器利用 ClientHello 里的新 Key Share，完成标准的 1-RTT 握手流程，生成新的、前向安全的会话密钥。

步骤 3：服务器回复

• 服务器发送 ServerHello 和加密的握手消息（Finished），完成正式握手。
• 紧接着发送用新密钥加密的 HTTP 响应数据。

特殊情况：地址验证（Retry 机制）

为了防止 UDP 反放大攻击，当服务器是一个热门服务，它可能会要求客户端先证明"你确实拥有这个 IP 地址，不是伪造的"。

这会引入一个额外的 RTT：

1. Client -> Server: 发送 Initial 包 (ClientHello)。
2. Server -> Client: 服务器感觉有风险，不进行复杂的 TLS 运算，而是回复一个很小的 QUIC Retry 包，里面包含一个加密的 Token。
3. Client -> Server: 客户端收到 Retry，必须重新发送 Initial 包，但这次要带上刚才收到的 Token。
4. Server -> Client: 服务器验证 Token 有效，确认客户端 IP 没问题，才开始正常的 1-RTT 握手流程（回复 Certificate 等）。

虽然多了一步，但这是一个轻量级的 UDP 交互，比完整的 TCP 握手还是要快。

总结

回顾从 HTTP/1.0 到 HTTP/3 的二十多年演进历程，我们可以清晰地看到，推动 Web 协议不断升级的核心动力，始终是为了提供更快、更稳、更安全的网络体验。这是一部与网络延迟、带宽限制和计算成本进行持续抗争的历史。

• HTTP/1.0 -> HTTP/1.1：为了解决 TCP 短连接带来的巨大开销，HTTP/1.1 引入了持久连接（Keep-Alive），让多个请求可以复用同一个 TCP 连接，显著减少了握手次数，是 Web 性能优化的第一步。
• HTTP/1.1 -> HTTP/2：为了解决 HTTP/1.1 在持久连接上仍然存在的应用层队头阻塞问题，HTTP/2 引入了二进制分帧和多路复用（Multiplexing）。它允许在同一个 TCP 连接上并发处理多个请求和响应，极大地提高了带宽利用率和并发能力。
• TLS 的演进 (1.2 -> 1.3)：在安全层面，TLS 协议也在不断进化。TLS 1.3 通过废除不安全的加密算法、强制使用具备前向安全的 ECDHE 密钥交换，并将握手流程极致优化至 1-RTT 甚至 0-RTT，实现了速度与安全的双重飞跃。
• HTTP/2 -> HTTP/3：为了彻底解决受制于 TCP 协议特性的传输层队头阻塞以及网络切换时的连接中断问题，HTTP/3 做出了颠覆性的改变。它基于 UDP 构建了全新的 QUIC 协议，将 TLS 1.3 的安全握手深度融合，实现了真正的 1-RTT 建连、基于 Connection ID 的无缝连接迁移，以及更高效的独立流控制。

从最初的简单文本传输，到如今基于 UDP 的高性能、高安全复合协议，HTTP 的演进之路从未停歇。未来的网络协议将如何发展？也许会更加智能化、更加适应边缘计算和物联网的需求，但其核心目标——连接你我，更快更安全——将永远不变。

特此声明，本篇是笔者与 Google Gemini 3Pro 共创所作，非常庆幸在当今 AI 时代下获取知识已是如此便利，且也为学习者从第一性原理理解所学知识大大降低了门槛。不过本篇的篇章安排和叙述逻辑，均由笔者把控和审阅，欢迎放心阅读。

1. 宏观理解

之所以背了又忘，通常是因为我们把传输层看作是一堆枯燥的字段（Flags、Window size）和死记硬背的流程（三次握手、四次挥手），而忽略了它存在的核心目的和演化逻辑。

要从根本上理解传输层（Transport Layer），我们需要剥离掉具体的协议细节，回归到第一性原理：传输层到底解决了什么网络层（IP）解决不了的问题？

1.2 三个层级

我们可以将其分解为三个层级来理解：复用与分用、不可靠基础上的可靠性、传输效率的权衡。

1.2.1 第一层级：复用与复用

👉🏻 核心逻辑

从主机到主机进化为进程到进程。

网络层（IP 层）的任务非常纯粹：通过 IP 地址，把数据包从地球的一端（主机 A）送到另一端（主机 B）。

但是，当数据包到达主机 B 时，IP 的任务就结束了。主机 B 此时正运行着微信、浏览器、Steam 和网易云音乐。这个数据包到底是给谁的？IP 协议不知道，也不管。

这就是传输层存在的第一个根本原因：

• 网络层只负责把快递送到大楼传达室（主机 IP）。
• 传输层负责把快递分发给大楼里的具体某个人（进程 Port）。

这个过程叫做复用（Multiplexing）和分用（Demultiplexing）。

不要把端口想象成物理插口，它只是一个逻辑地址。如果没有传输层，你的电脑同一时间只能运行一个网络程序，这显然是不可接受的。

1.2.2 第二层级：不可靠基础上的可靠性

👉🏻 核心逻辑

在不可靠的物理世界，构建一个完美的虚拟管道。

这是传输层最难理解、也最容易忘的部分。我们来看 TCP 为什么要搞得这么复杂。

第一性原理推导： 底层的网络环境（IP 层及更底层）本质上是不可靠的。

1. 丢包： 路由器太忙，直接把包扔了。
2. 乱序： 或者是前面的包走了远路，后面的包走了近路。
3. 篡改/错误： 电信号干扰导致比特翻转。

如果你的应用是"银行转账"或"网页浏览"，你无法容忍上述任何一种情况。你希望应用层感受到的是一条连续的、无差错的字节流。

TCP 的所有机制，都是为了填补"不可靠的现实"与"可靠的需求"之间的鸿沟。我们不需要死记硬背，而是通过问题来推导方案：

1. 问题：我怎么知道数据包丢没丢？
   • 方案（确认应答 ACK）： 接收方收到数据必须回一个"收到了"。
   • 衍生问题： 如果发送方一直收不到 ACK 怎么办？
   • 方案（超时重传）： 设个闹钟，时间到了没消息就重发。
2. 问题：数据包乱了怎么办？重复了怎么办？
   • 方案（序列号 Sequence Number）： 给每个字节的数据编号。1, 2, 3... 这样接收方就可以重新排序，或者丢弃重复的号。
3. 问题：接收方处理不过来怎么办？（比如服务器太慢，或者你发得太快）
   • 方案（流量控制 Flow Control）： 接收方在回信里告诉发送方："我的缓冲区还剩 X 大小（Window Size）"。发送方根据这个 X 调整发送速度。这就是滑动窗口的本质——保护接收方。
4. 问题：网线堵塞了怎么办？（中间的路由器处理不过来）
   • 方案（拥塞控制 Congestion Control）： 这是 TCP 最伟大的设计。发送方通过试探（慢启动、拥塞避免），感知网络的拥堵程度。一旦发现丢包（暗示堵车），立马减速。这是一个保护互联网基础设施的利他机制。

不要孤立地背诵"慢启动"、"快重传"。把 TCP 想象成一个强迫症晚期的快递员：他必须给每一个包裹编号（序列号），必须拿到客户的签字（ACK），发现客户家堆满了（流量控制）就暂停发货，发现路上堵车（拥塞控制）就换个时间发。

1.2.3 第三层级：速度与质量的权衡

👉🏻 核心逻辑

有时候，比起准确，我更需要实时。

并不是所有应用都需要 TCP 那样的强迫症。

• 场景： 视频通话、在线 FPS 游戏（如 CS:GO）。
• 思考： 在视频通话中，如果第 5 秒的画面丢了一帧，TCP 会怎么做？它会暂停后续播放，疯狂重传第 5 秒的那一帧，直到成功。等你看到那一帧时，已经是第 8 秒了，画面卡顿延迟。
• 实际需求： 丢了就丢了，赶紧把第 6 秒、第 7 秒的画面给我，我要的是实时性。

这就是 UDP（用户数据报协议） 的生存空间。

• 它几乎不加修饰，只做最基础的“复用/分用”（加个端口号）。
• 它不保证到达，不保证顺序，没有拥塞控制。
• 特点： 快、自由、无连接。

理论与实践结合：

• HTTP/3 (QUIC)： 现在的互联网巨头发现 TCP 太重了（握手慢、队头阻塞），于是开始在 UDP 之上重新实现一套可靠传输协议（QUIC）。这说明传输层的本质功能（可靠性）可以上移到应用层实现，但底层的物理限制永远存在。

1.2.4 总结

1.3 三个时代

要彻底理解这四个协议，我们不能平铺直叙地去背它们的定义。我们需要站在进化论的视角，看它们是如何为了解决特定时代的特定痛点而诞生的。

这不仅仅是协议的区别，更是思维模式（Mindset）的转变：从内核态的僵化走向用户态的灵活。

我们将这四个协议分为三个代际来理解：二元对立的世界 (TCP vs UDP)、暴力美学的补丁 (KCP) 和 颠覆架构的革命 (QUIC / HTTP3)。

1.3.1 第一代：二元对立的世界 (TCP vs UDP)

这是互联网早期的基础设定。设计者面临一个根本的取舍（Trade-off）：你是要绝对准确，还是要绝对速度？

1. TCP (Transmission Control Protocol) —— 老好人

• 第一性原理： 公平与可靠。
• 痛点解决： 互联网早期网络极不稳定，必须保证数据不丢、不乱。
• 性格缺陷：
  • 太守规矩（慢）： 建立连接要三次握手，断开要四次挥手。
  • 太顾大局（拥塞控制）： 一旦发现丢包，TCP 默认认为是网络堵了，为了不给互联网添乱，它会立刻减速（慢启动、拥塞避免）。哪怕其实只是因为你家 WiFi 信号抖了一下，它也会大幅降低速度。
  • 队头阻塞（Head-of-Line Blocking）： 前面一个包没到，后面的包到了也不能用，必须排队等。

2. UDP (User Datagram Protocol) —— 甩手掌柜

• 第一性原理： 简单与直接。
• 痛点解决： 解决 TCP 头部太大、握手太慢的问题。
• 性格特征：
  • 只管发，不管你收没收到。
  • 没有任何"流控"或"拥塞控制"，有多少发多少。
• 问题： 在复杂的互联网环境下，纯 UDP 几乎无法直接传输关键数据，因为丢包率不可控。

1.3.2 第二代：暴力美学的补丁 (KCP)

随着**实时对战游戏（如王者荣耀、MMORPG）**的兴起，开发者遇到了两难：

• 用 TCP？延迟太高，角色瞬移，因为 TCP 一丢包就降速等待。
• 用 UDP？包丢了技能放不出来。

于是，KCP 诞生了。它不是一个标准的网络协议，而是一个运行在 UDP 之上的算法库。

• 核心逻辑： 用带宽换延迟（流量换速度）。
• 第一性原理： TCP 的可靠性逻辑是对的（要确认、要重传），但 TCP 的策略太保守了。KCP 在 UDP 上重新实现了 TCP 的可靠机制，但把参数调得非常激进。
• KCP 怎么魔改 TCP 的？
  1. 死不退让（RTO 不翻倍）： TCP 发现超时，下一次等待时间会翻倍（1s -> 2s -> 4s）；KCP 说不，超时了我立马重传，等待时间只增加一点点（1s -> 1.5s），绝不让用户等。
  2. 选择性重传： 丢了哪个包，只重传那个包，不像早期 TCP 可能把后续的一起重传。
  3. 快速重传： 只要发现跳号（比如收到了 1, 3, 4，没收到 2），KCP 不等超时，立马重传 2。
• 代价： 会比 TCP 多消耗 10%-20% 的带宽。这是一种自私的协议，为了我的应用快，我不惜挤占网络资源。
• 总结： KCP = 激进版 TCP + UDP 的外壳。

1.3.3 颠覆架构的革命 (QUIC / HTTP3)

到了移动互联网时代，网页请求变得极其复杂（一个页面几百个资源），且用户经常切换网络（从 WiFi 切到 4G）。TCP 的底层架构（基于 IP 和端口）和队头阻塞成了瓶颈。KCP 这种小修小补已经不够了。

Google 站出来说：我们要重新发明轮子。这就是 QUIC (Quick UDP Internet Connections)。

• 核心逻辑： 移花接木，在用户态重构一切。
• 第一性原理： 既然操作系统的 TCP 协议栈（Kernel）更新太慢（你没法强迫全世界升级 Windows/Linux 内核），那我们就绕过内核，在应用层（用户态）基于 UDP 自己写一套完美的传输协议。
• QUIC 解决了什么 TCP 解决不了的问题？
  1. 彻底解决队头阻塞（多路复用）：
     • TCP： 一条高速公路，前面车坏了，后面全堵死。
     • QUIC： 并不是单纯的一条路，而是并行的多车道（Stream）。图片 A 的包丢了，只影响图片 A，不影响旁边的 CSS 文件和文字加载。这是 QUIC 最核心的优势。
  2. 网络切换不断线（Connection Migration）：
     • TCP： 依靠 IP:Port 识别连接。你从 WiFi (IP: A) 切换到 4G (IP: B)，IP 变了，TCP 连接必断，必须重新握手。
     • QUIC： 发明了一个 Connection ID (UUID)。不管你的 IP 怎么变，只要 ID 没变，服务端就知道还是你，连接保持，无需重连。
  3. 0-RTT 建连：
     • TCP + TLS 需要多次往返才能建立加密连接。QUIC 把传输层握手和加密层（TLS 1.3）握手合并了，最快可以做到 0 延迟发送数据。

1.3.4 总结

1. TCP 和 UDP 是操作系统提供的原材料。TCP 也就是加了确认和流控的 UDP。
2. KCP 是为了游戏和弱网环境，在 UDP 上模仿并魔改了 TCP，甚至不惜浪费流量也要快。
3. QUIC 是为了现代 Web，在 UDP 上彻底重写了 TCP + TLS，解决了 TCP 几十年改不掉的"队头阻塞"和"僵化"毛病。

一句话总结： TCP 是老古董，UDP 是地基，KCP 是为了快而拼命的魔改插件，QUIC 是试图取代 TCP 的下一代互联网标准。

2. 底层剖析

要详细剖析这四个协议的底层原理，我们必须深入到数据包（Packet）的结构和**状态机（State Machine）**的控制逻辑中去。

我们要抓住一个核心矛盾：如何在不可靠的物理线路（丢包、乱序、延迟）上，构建出符合应用层需求的逻辑管道。

2.1 UDP：裸奔的传输层

UDP 是理解其他所有协议的基准。它的底层原理非常简单，几乎就是 IP 协议的“影分身”。

2.1.1 头部结构

UDP 的头部只有 8 个字节。

• Source Port & Destination Port： 也就是前面提到的"复用/分用"。
• Length & Checksum： 告诉你包有多长，校验一下数据有没有坏（比特翻转）。

2.1.2 核心机制

• 无状态（Stateless）： 操作系统内核不会为 UDP 维护任何表格。来一个包，查一下端口，扔给应用程序。发一个包，直接扔给网卡。
• MTU 限制： UDP 不负责切分数据。如果你应用层给 UDP 一个 2000 字节的数据包，而底层以太网 MTU 只有 1500，IP 层会进行分片（Fragmentation）。一旦其中一个分片丢了，整个 UDP 包就废了。

既然 UDP 什么都不管，那么所有的高级功能（KCP 的重传、QUIC 的流控）都必须由应用层代码自己来实现。

2.2 TCP：流量与拥塞的博弈

传输控制协议（TCP）是互联网的基石，其设计目标是在不可靠的 IP 网络上提供可靠（Reliable）、**有序（Ordered）且错误检查（Error-Checked）**的字节流服务。从第一性原理来看，TCP 是一个复杂的控制论系统，通过负反馈机制（ACK）来调节系统的输入（发送速率），以维持系统的稳定性（避免拥塞崩溃）。

2.2.1 字节流抽象与序列号管理

TCP 的核心抽象是字节流。不同于 UDP 的报文，TCP 将应用层数据视为无边界的水流。

为了实现有序重组，TCP 为发送的每一个字节（Octet）分配一个 32 位的序列号。

• 语义：TCP 段头部的 Sequence Number 字段表示该段数据载荷中第一个字节在整个数据流中的偏移量。
• ACK 机制：TCP 使用累积确认（Cumulative ACK）。Acknowledgment Number 表示接收端期望收到的下一个字节的序列号。例如，ACK=1001 意味着 1000 及以前的所有字节均已正确接收。

内核为每个 TCP 连接维护一个接收缓冲区（Receive Buffer）。

• 当数据包乱序到达（例如，先收到 SEQ 2000，后收到 SEQ 1000），内核会将 SEQ 2000 的数据暂存在缓冲区中的对应位置（SACK 机制辅助记录这一空洞）。
• 只有当 SEQ 1000 到达填补空洞后，内核才会更新 ACK 指针，并唤醒用户进程读取数据。
• 队头阻塞（Head-of-Line Blocking, HOL）：这是 TCP 在低延迟场景下的致命弱点。如果 SEQ 1000 的包丢失，即使 SEQ 2000-5000 的数据已经完整到达，应用层也无法读取这 3000 字节。内核必须等待 SEQ 1000 重传成功，才能交付后续数据。在丢包率为 1%-2% 的网络中，HOL 会导致巨大的延迟抖动。

2.2.2 可靠传输：RTO 与 ARQ

TCP 的可靠性依赖于自动重传请求（ARQ）。核心问题在于：发送端发出数据后，应该等待多久才认为数据丢失？这个时间被称为重传超时（RTO）。

RTO 的计算必须基于对往返时间（RTT）的动态估算。

• SRTT（Smoothed RTT）：采用指数加权移动平均（EWMA）算法平滑采样值。 $$ SRTT_{new} = (1 - \alpha) \cdot SRTT_{old} + \alpha \cdot RTT_{sample} $$ 其中 $\alpha$ 通常取 0.125。

• RTTVAR（RTT Variation）：Van Jacobson 引入了对 RTT 抖动（方差）的估算，以适应网络波动 17。

  $$ RTTVAR_{new} = (1 - \beta) \cdot RTTVAR_{old} + \beta \cdot |SRTT_{old} - RTT_{sample}| $$ 最终 RTO 计算公式为： $$ RTO = SRTT + 4 \cdot RTTVAR $$ 系数 4 的选择基于切比雪夫不等式，旨在覆盖 99% 以上的 RTT 分布。

• Karn 算法：解决重传二义性问题。如果一个包发生了重传，收到 ACK 时无法确定是回应原包还是重传包，因此 Karn 算法规定：发生重传时，不更新 RTT 估算值，并将 RTO 指数退避（Exponential Backoff） 。

等待 RTO 超时过于缓慢。TCP 引入了快速重传机制：当发送端收到 3 个重复的 ACK（Duplicate ACK） 时，推断该 ACK 指示的下一个报文段已丢失，立即重传，而不必等待定时器溢出。这一机制利用了"重复 ACK"作为网络丢包的隐式信号，显著降低了恢复延迟。

2.2.3 拥塞控制：从 AIMD 到 BBR

TCP 认为丢包是网络拥塞的信号（这一假设在无线网络中往往不成立，却是 TCP 设计的基石）。

1. 慢启动（Slow Start）：连接建立初期，拥塞窗口（cwnd）呈指数增长，每收到一个 ACK，cwnd 加 1 MSS（最大报文段长度）。这实际上是倍增过程，用于快速探测可用带宽。
2. 拥塞避免（Congestion Avoidance）：当 cwnd 达到慢启动阈值（ssthresh）后，进入线性增长阶段（AIMD：加法增，乘法减）。每经过一个 RTT，cwnd 增加 1 MSS。
3. 拥塞发生：一旦检测到丢包（超时或 3 个重复 ACK），TCP 立即大幅削减 cwnd（通常减半或降为 1），以释放网络压力。

2.2.3.1 CUBIC 算法

Linux 默认使用的 CUBIC 算法，将窗口增长函数设计为一个三次函数。 $$ W(t) = C(t - K)^3 + W_{max} $$ 其曲线在接近上次丢包窗口 $W_{max}$ 时变得平缓（稳定探测），而在远离饱和点时快速增长。这种凹凸性使得 CUBIC 在高带宽延迟积（BDP）网络中比线性增长的 Reno 算法更高效。

2.2.3.2 BBR(Bottleneck Bandwidth and RTT)

Google 提出的 BBR 算法颠覆了“基于丢包”的传统逻辑。BBR 基于模型（Model-based），试图实时测量网络的两个物理边界：

• RTprop（物理链路的最小往返传播时延）。

• BtlBw（瓶颈链路带宽）。

  BBR 试图将发送速率控制在 BtlBw，同时保持 inflight 数据量等于 BDP（带宽×延迟），从而在不填满路由器缓冲区（Bufferbloat）的情况下跑满带宽。这种机制使得 BBR 在高丢包率环境下依然能保持高吞吐，因为它不会因为非拥塞性丢包而错误地降低速度。

TCP 的丢包判断机制（通常是 3 次重复 ACK 或超时）在现代高丢包率或高延迟网络（如跨海传输）下显得反应太慢，且一旦退让就退让太多。

2.3 KCP：用带宽换时延

KCP 是一个纯算法层面的 ARQ 协议，其设计者 skywind3000 明确指出，KCP 的第一性原理是用带宽换延迟。如果说 TCP 是为了最大化全网的带宽利用率和公平性，那么 KCP 就是为了在单点连接上压榨出物理极限的响应速度，不惜牺牲带宽资源。

2.3.1 头部结构

KCP 的核心在于其精巧的数据段结构 IKCPSEG，其头部占据 24 字节（TCP 通常为 20 字节），字段定义直接服务于激进的重传逻辑。

2.3.2 激进 ARQ

KCP 的激进性体现在它对传统 TCP 策略的全面修正。

2.3.2.1 混合确认机制：UNA + ACK List

TCP 主要依赖累计确认（UNA）。KCP 则采用了 UNA + ACK List 的混合模式。

• 头部中的 una 字段提供累计确认，保证基础的滑动窗口推进。
• 同时，KCP 会单独发送 ACK 包（或者在数据包后追加 ACK 信息），显式告知收到了哪些特定的 sn。这种机制类似于 TCP 的 SACK，但在 KCP 中是原生且强制的。它允许发送端精确知道哪些包丢失，从而只重传丢失的包（选择性重传，Selective Repeat），避免了 Go-Back-N 的带宽浪费。

2.3.2.2 快速重传

TCP 需要 3 个重复 ACK 触发快重传。KCP 引入了 fastack 计数器：

• 当发送端收到一个 ACK，确认了 sn=100 和 sn=102，但没有确认 sn=101 时，sn=101 的 fastack 计数器加 1。
• 一旦 fastack 达到设定阈值（resend 参数，通常设为 2 甚至 1），KCP 不等待 rto 超时，立即重传 sn=101。
• 这使得 KCP 在跨越长肥管道（Long Fat Network）时，能比 TCP 快数倍地感知并恢复丢包。

2.3.2.3 非退让的流控

TCP 检测到丢包会减半窗口（拥塞避免）。KCP 提供了 nc（No Congestion Control）配置开关。

• 当 nc=1 时，KCP 完全关闭拥塞窗口（cwnd）逻辑，只受限于接收端的接收窗口（rwnd）和发送端的发送缓冲区大小。
• 这意味着即使网络极度拥塞，丢包率极高，KCP 依然会按照最大速度发送数据和重传包。这种“自私”的行为在公共互联网上可能加剧拥塞，但对于实时游戏等对延迟极度敏感的应用，它是保证流畅体验的关键手段。

2.3.2.4 RTO 策略优化

• 不翻倍：TCP 超时后 RTO 翻倍（x2, x4, x8）。KCP 默认仅 x1.5，这意味着它会更频繁地重试。
• RTO 最小值：TCP 的 RTO 最小值通常受限于内核 tick（例如 200ms），虽然现代 Linux 已优化，但 KCP 允许在用户态设置极低的 RTO 最小值（如 10ms-30ms），这对于局域网或高质量光纤网的微小抖动反应极快。

2.3.3 算力代价：用户态时钟与轮询

KCP 的高性能是有代价的——CPU 利用率。

• User-space Scheduling：KCP 没有内核的中断驱动机制。用户程序必须在一个循环中不断调用 ikcp_update(current_time)。
• Tick 频率：为了获得低延迟，ikcp_update 通常每 10ms 甚至 1ms 调用一次。这导致 CPU 即使在空闲时也难以进入深度睡眠状态，产生了大量的空轮询开销。

KCP 的本质是在应用层实现了一个高频轮询的调度器（通常 update 间隔为 10ms）。它比 TCP 多耗费 20%-30% 的流量，换取了低延迟。

关于 KCP 更多的底层细节可参阅 KCP 源码分析与原理总结。

2.4 QUIC：用户态的 TCP+TLS

QUIC（Quick UDP Internet Connections），现已标准化为 RFC 9000，代表了网络传输协议的最新演进方向。它不仅仅是一个传输协议，更是一个将传输层（Transport）、安全层（TLS）和部分应用层（HTTP/2）功能融合的垂直整合架构。

关键点：

1. 低连接延迟
2. 无队头阻塞
3. 灵活拥塞控制
4. 连接迁移

2.4.1 报文结构

QUIC 设计了两种头部格式，以适应握手和数据传输的不同需求。

• 长首部（Long Header）：用于连接建立阶段（Initial, Handshake, Retry, 0-RTT）。第一字节最高位为 1。包含完整的 Source CID 和 Destination CID，以及版本号。

  

• 短首部（Short Header）：用于连接建立后的数据传输（1-RTT）。第一字节最高位为 0。仅包含 Destination CID（可选）和 Packet Number。这极大地减少了头部开销。

  

QUIC 的一个关键安全特性是对 Packet Number 进行加密。

• 机制：利用 Header Protection Key（从 TLS 协商导出），对 Packet Number 字段进行异或掩码操作。
• 目的：防止中间设备（Middleboxes）窥探连接的 RTT 或丢包率，也防止中间设备基于明文头部做深度包检测（DPI）从而干扰连接。这强化了协议的抗僵化能力（Ossification Resistance）。

2.4.2 核心结构：Frame 与 Stream（解决队头阻塞）

TCP 的队头阻塞源于其单一的字节流抽象。QUIC 引入了Stream作为一等公民。

• 独立性：一个 QUIC 连接可以包含多个 Stream。每个 Stream 有独立的 ID 和 Offset。
• 底层实现：QUIC 数据包（Packet）是传输单元，Frame 是逻辑单元。一个 Packet 可以承载属于 Stream A 的 Frame 和属于 Stream B 的 Frame。
• 抗阻塞：如果承载 Stream A 数据的 Packet 丢失，接收端只需等待该 Packet 重传即可恢复 Stream A；而 Stream B 的数据如果在后续 Packet 中到达，接收端可以立即提交给应用层，无需等待 Stream A 的恢复。这彻底消除了传输层的队头阻塞。

2.4.3 连接迁移与 CID

移动互联网时代，设备的 IP 地址经常变动（Wi-Fi 切 5G）。TCP 依赖四元组（SrcIP, SrcPort, DstIP, DstPort）标识连接，IP 变动会导致连接中断。

• Connection ID (CID)：QUIC 使用 CID 唯一标识连接。
• 迁移机制：当客户端 IP 变化时，它在新的 IP 上发送包含原有 Destination CID 的数据包。服务器收到后，通过哈希表查找 CID 对应的连接上下文，验证数据包的真实性（防欺均），然后更新路径信息。连接保持不断，应用层无感知 22。
• 隐私保护：为了防止路径关联攻击（通过追踪 CID 关联用户的物理位置），QUIC 允许在连接期间协商一组新的 CID。客户端在切换网络时主动更换使用新的 CID，使得监听者无法关联前后两条路径。

2.4.4 低延迟连接

QUIC 深度集成了 TLS 1.3，将传输层握手与加密握手合并。

• 1-RTT：首次连接，客户端发送 Initial 包包含 TLS ClientHello，服务器回复 ServerHello 和 EncryptedExtensions。1 个 RTT 后即可发送应用数据。
• 0-RTT：对于曾经连接过的服务器，客户端缓存了 ServerConfig 或 Session Ticket。在重连时，客户端利用预共享密钥（PSK）加密应用数据，随第一个 Initial 包（ClientHello）一起发送。服务器收到后立即解密处理。
• 反重放（Anti-Replay）：0-RTT 数据不具备前向安全性，且容易被重放。RFC 9000 要求服务器对 0-RTT 数据的使用极其谨慎，通常只允许幂等请求（如 GET），并通过时间窗和 Ticket 唯一性检查来限制重放窗口。

2.4.5 更精确的恢复

QUIC 改进了 TCP 的 ACK 机制：

• ACK Ranges：TCP SACK 只有 3-4 个块。QUIC 的 ACK Frame 可以携带大量的 ACK Ranges（交替的 Ack 和 Gap 块），能精确描述极度碎片化的接收状态。
• Packet Number 单调递增：TCP 重传时使用相同的 SEQ。QUIC 重传一个 Frame 时，会将其封装在一个新的 Packet 中，使用新的 Packet Number。
  • 消除二义性：接收端收到 ACK 时，根据 ACK 中的 Packet Number 就能明确知道是确认了原始包还是重传包。这彻底解决了 TCP 的重传二义性问题，使得 RTT 计算极其精准，不再需要 Karn 算法的退避策略。

2.5 总结

为了更直观地理解，我们对比一下它们处理"数据发送"这个动作的底层逻辑：

从原理出发，我们可以得出工程实践的指导原则：

1. 内网微服务 (RPC)： 依然首选 TCP。因为内网环境极其稳定，带宽大，丢包率几乎为 0。TCP 的内核态实现效率极高，CPU 消耗比 QUIC 低得多（QUIC 需要在用户态频繁解密和计算，非常吃 CPU）。
2. 公网实时游戏/音视频： 首选 KCP（或类 KCP 的私有协议）。因为你要的是低延迟，且你可以容忍多跑一点流量。
3. 弱网环境下的 App/Web： 首选 QUIC。比如跨国访问、移动端环境。它解决了 TCP 的队头阻塞和连接迁移问题，能显著提高用户的加载体验。

3. 实践检验

抓包看一下 TCP 的三次握手、四次挥手和数据传输。

server:

use axum::{routing::get, Router};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let router = Router::new().route("/hello", get(hello_handler));
    let listener = TcpListener::bind("0.0.0.0:12345").await?;
    println!("listening on {}", listener.local_addr()?);
    axum::serve(listener, router.into_make_service()).await?;
    Ok(())
}

async fn hello_handler() -> &'static str {
    "hello world"
}

client:

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let res = reqwest::get("http://localhost:12345/hello").await?;
    println!("{}", res.text().await?);
    Ok(())
}

tcpdump:

sudo tcpdump -Xvvvnnttt -i any  -s 0 tcp port 12345 -w ./packet.pcap > tcpdump.log

3.1 三次握手

第一次握手：client(57831) 向 server(12345) 发送 SYNC 包

- 初始化 `Sequence Number` 为 408182767
- 初始化 `Acknowled Number (raw)` 为 0
- 设置 `SYNC` 标记位
- 初始化窗口 `65535`
- Options 中允许 `SACK` 选择性确认

第二次握手：server(12345) 向 client(57831) 发送 ACK+SYNC 包

- 初始化 `Sequence Number` 为 785921704
- 初始化 `Acknowled Number (raw)` 为 408182768（为上一步的 `Sequence Number 408182767` + 1）
- 设置 `SYNC` 和 `ACK` 标记位
- 初始化窗口 `65535`
- Options 中允许 `SACK` 选择性确认

第三次握手：client(57831) 向 server(12345) 发送 ACK 包

- `Sequence Number` 加 1 变为 `408182768`，即上一步的 `Acknowled Number (raw)`
- 初始化 `Acknowled Number (raw)` 为 785921705（为上一步的 `Sequence Number 785921704` + 1）
- 设置 `ACK` 标记位
- 窗口修改为 `5379`

3.2 数据传输

初始状态：

client:
- SeqNum: 408192768
- AckNum: 78591705
server:
- SeqNum: 78591705（SYNC 包占了一个序列号，所以是 785921704+1）
- AckNum: 408192768

client → server:

server → client:

3.3 四次挥手

第一次挥手：client(57831) 向 server(12345) 发送 FIN 包

第二次挥手：server(12345) 向 client(57831) 发送 ACK 包

第三次挥手：server(12345) 向 client(57831) 发送 FIN 包

第四次挥手：client(57831) 向 server(12345) 发送 ACK 包

3.4 两个工具

3.4.1 netstat

基础参数

-a    # 显示所有连接和监听端口
-n    # 以数字形式显示地址和端口号
-p    # 显示进程名称/进程号
-t    # 显示 TCP 协议的连接
-u    # 显示 UDP 协议的连接
-l    # 仅显示监听中的连接

常见组合使用

# 显示所有 TCP 连接
netstat -at

# 显示所有监听端口
netstat -l

# 显示所有 TCP 监听端口
netstat -lt

# 显示所有进程和监听端口（需要 root 权限）
netstat -nltp

# 显示路由表信息
netstat -r

查看特定端口

# 查看 80 端口的使用情况
netstat -an | grep ':80'

查看程序连接

# 查看所有 HTTP 相关连接
netstat -anp | grep 'http'

统计连接数

# 统计各种状态的连接数
netstat -n | awk '/^tcp/ {++state[$NF]} END {for(key in state) print key,"\\\\t",state[key]}'

netstat 输出的典型字段包括：

• Proto: 协议（TCP/UDP）
• Recv-Q: 接收队列
• Send-Q: 发送队列
• Local Address: 本地地址:端口
• Foreign Address: 远程地址:端口
• State: 连接状态
• PID/Program name: 进程ID和程序名称

常见连接状态：

• LISTEN: 监听中
• ESTABLISHED: 已建立连接
• TIME_WAIT: 等待关闭
• CLOSE_WAIT: 等待关闭
• SYN_SENT: 发送同步
• SYN_RECV: 接收同步

3.4.2 ss

ss [选项] [过滤条件]

基础参数

-n    # 不解析服务名称，以数字显示
-a    # 显示所有套接字
-l    # 显示监听状态的套接字
-p    # 显示进程信息
-t    # 显示 TCP 套接字
-u    # 显示 UDP 套接字
-x    # 显示 Unix domain 套接字
-s    # 显示套接字使用概况
-4    # 仅显示 IPv4
-6    # 仅显示 IPv6

常见用法

# 显示所有 TCP 连接
ss -t -a

# 显示所有监听端口和进程信息（常用）
ss -tlnp

# 显示统计信息
ss -s

# 显示所有 established 状态的 TCP 连接
ss -t state established

状态过滤

# 显示指定状态的连接
ss state established
ss state time-wait
ss state listening

端口过滤

# 显示指定端口的连接
ss sport = :80    # 源端口
ss dport = :80    # 目标端口

# 显示特定端口范围
ss sport gt :1024  # 大于1024的源端口

地址过滤

# 显示与特定 IP 相关的连接
ss dst 192.168.1.1
ss src 192.168.1.1

查看具体服务

# 查看 HTTP 相关连接
ss -np state established '( dport = :80 or sport = :80 )'

# 查看 SSH 连接
ss -o state established '( dport = :22 or sport = :22 )'

查看连接统计

# 查看连接速率
ss -i

# 查看内存使用
ss -m

高级过滤

# 查看特定进程的连接
ss -p | grep nginx

# 查看非监听 TCP 连接
ss -t -a '( dport != :22 )'

ss 输出的典型字段包括：

• Netid: 协议类型
• State: 连接状态
• Recv-Q: 接收队列
• Send-Q: 发送队列
• Local Address:Port: 本地地址和端口
• Peer Address:Port: 对端地址和端口
• Process: 进程信息（使用 -p 参数时显示）

性能优势：

1. ss 直接从内核空间读取信息，而不是像 netstat 那样读取 /proc
2. ss 的运行速度更快
3. ss 能够显示更多的 TCP 状态信息

注意事项：

1. 某些操作需要 root 权限
2. 不同 Linux 发行版的 ss 版本可能有细微差异
3. 使用 -p 参数时，非 root 用户可能看不到所有进程信息

与 netstat 的对比：

# netstat 命令              # ss 等效命令
netstat -tulpn            ss -tulpn
netstat -antop            ss -antop
netstat -t                ss -t
netstat -l                ss -l

traceroute 回顾

先回顾一下 traceroute 这个工具：

• 作用：用来跟踪一个 IP 数据包从源点到终点的路径。
• 原理：它利用 IP 数据报中的 TTL 字段和 ICMP 时间超时差错报告报文实现对从源点到终点的路径的跟踪。
• 过程：
  • 客户端发送一个 TTL 为 1 的探测数据包（Linux/macOS 默认使用 UDP，Windows 使用 ICMP），在第一跳的时候超时并返回一个 ICMP 超时数据包，得到第一跳的地址。
    • 客户端发送一个 TTL 为 2 的探测数据包，得到第二跳的地址。
    • 依次递增 TTL，直到到达 目标主机，目标主机返回响应（UDP 端口不可达或 ICMP 回显应答），traceroute 结束。

问题再现

我在使用 traceroute 跟踪我本机到我的博客域名 hedon.top 的跳转路径时，发现很奇怪，返回的全是 * * *！

➜  ~ traceroute hedon.top
traceroute to hedon.top (172.19.0.13), 64 hops max, 40 byte packets
 1  * * *
 2  * * *
 3  * * *
 4  *

我就怀疑是不是因为我开启了 VPN，所以我就询问了一下 Google Gemini 3Pro，还真是！它说是因为 VPN 里面的 fake ip 导致了，我立马检查了我的 Clash Mi，发现果真如此，同时我关闭 Clash Mi 后，traceroute 就一切正常了。

原理分析

为什么会这样呢？

[!IMPORTANT]

很多代理软件开启 增强模式 (Fake IP) 时，会拦截所有 DNS 请求。为了加快速度，它不进行真正的 DNS 查询，而是直接扔给你一个“假的内部 IP”（通常是 198.18.x.x，但也可以配置成 172.x.x.x），然后由代理软件接管流量。

又因为大多数 VPN 软件的 Fake IP 逻辑只处理 TCP/UDP 数据流（用来浏览网页），它并不支持通过 Fake IP 来做 ICMP 路由探测。所以就导致了探测包发出去如泥牛入海，VPN 不回信，真实服务器更收不到（因为根本没发给真实 IP），所以看到的全是 * * *。

为什么需要 Fake IP 呢？ —— 为了快！

在正常的 VPN/代理模式下，当你访问 hedon.top 时，采用的是 Redir-Host 模式：

1. 本地 DNS 解析：电脑问 DNS 服务器 "hedon.top 是多少？"
2. 等待：等待 DNS 返回 IP（比如 30ms）。
3. 建立连接：电脑拿着 IP 去发起 TCP 连接。
4. 代理软件：拦截连接，发现这个 IP 是国外的，于是走代理通道。

代理软件的设计者觉得步骤 2 是纯浪费时间。既然反正要走代理，我为什么要让本地 DNS 去查一个国外的 IP？而且万一 DNS 被污染了，给了一个错误的 IP，我还得想办法纠错。

开启 VPN (Fake IP 模式) 后的流程：

1. 拦截：你发出的 DNS 请求，还没出电脑网卡，就被 VPN 软件截获了。
2. 秒回：VPN 立刻、马上、随便编一个内网 IP（比如我看到的 172.19.0.13）扔给你的系统。
   • VPN 在心里记了个账：172.19.0.13 <==> hedon.top。
3. 欺骗成功：浏览器（或 traceroute）拿到了这个 IP，以为是真的，于是向这个 IP 发起连接。
4. 偷梁换柱：数据包发出来，又被 VPN 截获。VPN 查账本，发现目标是 172.19.0.13，于是它知道："哦，这其实是要去访问 hedon.top"。
5. 远程解析：VPN 把"访问 hedon.top"这个指令发给远端的代理服务器，由远端服务器去解析真正的 IP 并传输数据。

sequenceDiagram
    autonumber
    participant App as 浏览器/App
    participant OS as 操作系统/DNS栈
    participant Clash as Clash (Fake IP)
    participant Remote as 远端代理服务器

    Note over App, Clash: 阶段一：DNS 欺骗 (极速响应)

    App->>OS: 域名解析请求: hedon.top
    OS->>Clash: 发送 UDP 53 包

    Note right of Clash: Clash 拦截请求<br>根本不去查互联网！
    Clash->>Clash: 1. 从 Fake IP 池选一个空闲 IP<br>比如 172.19.0.13
    Clash->>Clash: 2. 记账 (Mapping)<br>"172.19.0.13" = "hedon.top"

    Clash-->>App: 秒回: IP 是 172.19.0.13

    Note over App, Clash: 阶段二：建立连接 (偷梁换柱)

    App->>App: 以为拿到了真 IP<br>向 172.19.0.13 发起 TCP 连接
    App->>Clash: TCP SYN (Dst: 172.19.0.13)

    Note right of Clash: Clash 拦截 TCP 包<br>查账本：172.19.0.13 是谁？
    Clash->>Clash: 哦，原来是 hedon.top

    Clash->>Remote: 把"域名 hedon.top"发给远端<br>由远端服务器去解析真实 IP
    Remote->>Remote: 在海外解析并连接真实服务器

关键点：

1. 省时：DNS 响应是毫秒级的，因为根本不需要网络请求，Clash 直接从内存里扔一个 IP 给你。
2. 防污染：因为本地根本不进行真实的 DNS 解析，GFW 的 DNS 污染攻击直接无效。
3. 远端解析：真实的 IP 解析发生在远端代理服务器（比如在日本或美国的机房），那里解析出来的 IP 一定是离目标最近、最准确的（比如 Google 的 CDN 节点）。

为什么返回是全是 * * * 呢？

再看那个全是 * * * 的现象，就很容易理解了：

1. 执行：traceroute hedon.top。
2. Clash Mi 欺骗：给了 172.19.0.13。
3. 发包：traceroute 向 172.19.0.13 发送 UDP/ICMP 探测包。
4. 死胡同：
   • 这个 IP 在公网上是不存在的。
   • Clash 通常只代理浏览器的 TCP/UDP 数据流，它并没有义务去模拟路由器的 ICMP TTL 回显功能。
   • 所以探测包发给 Clash Mi 的虚拟网卡后，就像掉进了黑洞，没有任何设备回信"超时"。

注意事项

Fake IP 虽然爽，但对于写代码的人来说，有两个巨大的坑：

坑一：Docker/局域网冲突

如果 Clash Mi 用的 Fake IP 网段（如 172.19.0.0/16）恰好和你的 Docker 容器网段重叠。

• 现象：你要连本地的 Docker 数据库，结果流量被 Clash 吸走了，报"连接被拒绝"。
• 解法：始终确保 Fake IP 网段设置为 198.18.0.1/16。这是一个专门用于性能测试的保留网段，世界上没有公网机器用它，Docker 默认也不用它。

坑二：IP 缓存中毒 (DNS Cache Poisoning)

有些笨拙的软件（比如旧版的 Java 客户端、某些物联网设备 SDK）会缓存 DNS 结果。

1. 你开了 VPN，程序解析 hedon.top 拿到 172.19.0.13。
2. 程序把这个 IP 存到自己的内存缓存里，有效期 1 小时。
3. 你关了 VPN。
4. 程序再次发起请求，它不去解析 DNS 了，直接连 172.19.0.13。
5. 报错：因为 VPN 关了，操作系统不知道这个 IP 是谁，网络直接不可达。

解法：关 VPN 后，往往需要重启应用，甚至执行 ipconfig /flushdns (Windows) 或 sudo killall -HUP mDNSResponder (macOS)。

其他原因

除了 Fake IP 这种本地欺骗导致的全是星星外，在真实的互联网环境中，traceroute 出现 * * * 是非常普遍的现象。

从第一性原理来看，* * * 的本质含义只有一个：我发出了探测包，但在规定时间内（通常是 5 秒），我没有收到任何回信。

造成没有回信通常有以下四大类原因，我们按照出现的概率从高到低排列：

1. 中间路由器的高冷 (ICMP 限速或禁发)

表现：中间几行是星星，但最后能到达终点。

• 原理：路由器的核心 KPI 是转发数据包，而不是陪聊。当你发送 TTL 超时的探测包时，路由器需要暂停手头的工作，调用 CPU 生成一个 ICMP Time Exceeded 消息发回给你。这会消耗路由器的 CPU 资源。
• 策略：为了防止被 DDoS 攻击或节省性能，运营商（ISP）和骨干网路由器通常配置了 ICMP Rate Limiting (限速) 甚至 ICMP Silently Drop (静默丢弃)。
• 结论：如果中间全是星，但最后一行通了，完全不用担心，这是正常的网络现象。

2. 防火墙的黑洞策略 (DROP vs REJECT)

表现：从某一行开始全是星星，直到结束都连不上。

• 原理：当探测包撞上防火墙（可能是企业边缘防火墙、GFW、或者目标机器的 iptables）时，防火墙有两种处理方式：
  1. REJECT：明确告诉你"滚"。你会收到 Destination Unreachable。
  2. DROP (丢弃)：直接把包扔垃圾桶，不给任何回信。
• 为什么：出于安全考虑，管理员通常配置 DROP。因为回复错误信息会暴露防火墙的存在和 IP 地址，给黑客留下线索。
• Linux 的痛点：Linux traceroute 默认用 UDP 高端口探测。很多企业的防火墙策略是：只允许 Web (80/443) 流量进入，封禁所有未知 UDP 端口。这会导致你还没到终点就被拦截了。
• 解决方法：使用 traceroute -I (改用 ICMP) 或 traceroute -T (改用 TCP 80 端口) 通常能穿透更多层。

3. 进出路径不一致 (非对称路由 Asymmetric Routing)

表现：忽通忽断，或者全是星星。

• 原理：互联网非常复杂，"去程"和"回程"走的路往往是不一样的。
  • 去程：你 -> 路由器 A -> 路由器 B -> 目标。
  • 回程：目标 -> 路由器 C -> 路由器 D -> 你。
• 问题：
  • 如果你发出的探测包经过了路由器 B（它是有状态防火墙），它记录了"我发出了一个包"。
  • 但回信是路由器 C 试图发回来的。路由器 B（或者你这边的防火墙）一看："我没见过你 C 发过来的连接请求啊？你是谁？"
  • 于是回信被状态防火墙 (Stateful Firewall) 拦截了。
• 结论：虽然数据包可能真的到达了，但回音被杀死了。