第 4 章 写入之旅：文档 API 与并发控制
文档摘要
第 4 章 · 写入之旅：文档 API 与并发控制 章节摘要：一条写入请求从客户端出发，被协调节点按路由公式派往某个主分片，在那里经历内存缓冲、事务日志、刷新成段的全过程。本章沿这条路径讲三组能力：写入与自动生成 id、单文档的读取更新删除、批量写入与乐观并发控制。写路径是理解集群行为（黄色状态、近实时、段合并）的地基，第 8 章的所有"为什么"都能在本章找到起点。 学习目标 阅读完本章，你应当能够： 手算一条文档的路由结果，说出指定 id 与自动生成 id 在路由与写入语义上的差别。 按需求选用读取、存在性检查、局部更新、删除四类单文档操作，并说明各自的代价。 用批量接口组织混合操作流，解释其换行分隔的报文格式与部分失败的读法。
第 4 章 · 写入之旅：文档 API 与并发控制
章节摘要：一条写入请求从客户端出发，被协调节点按路由公式派往某个主分片，在那里经历内存缓冲、事务日志、刷新成段的全过程。本章沿这条路径讲三组能力：写入与自动生成 id、单文档的读取更新删除、批量写入与乐观并发控制。写路径是理解集群行为（黄色状态、近实时、段合并）的地基，第 8 章的所有"为什么"都能在本章找到起点。
学习目标
阅读完本章，你应当能够：
- 手算一条文档的路由结果，说出指定 id 与自动生成 id 在路由与写入语义上的差别。
- 按需求选用读取、存在性检查、局部更新、删除四类单文档操作，并说明各自的代价。
- 用批量接口组织混合操作流，解释其换行分隔的报文格式与部分失败的读法。
- 用序列号与主项实现"读后写"的乐观并发控制，避免更新互相覆盖。
- 复述写路径的六个步骤，从协调节点到刷新成段，标注每步的持久化边界。
核心概念速览
金句：写路径的每一步都在回答同一个问题——此刻掉电，哪些数据必须还在，哪些可以晚点可见。
子章节导航
4.1 写入：Index API 与分片路由
写入请求发出后的完整旅程：路由公式的推导、指定 id 与自动 id 的分野、写路径六步里每步的持久化语义。这一节是全册"分片之旅"主线的核心一站。
4.2 读取、更新与删除：单文档生命周期
单文档的四件套：按 id 取原文、轻量存在性检查、脚本驱动的局部更新、打标记式删除。顺带说清一个反直觉事实——更新从来不是原地修改，而是删除加重写。
4.3 批量写入与乐观并发控制
一次搬运一千条文档的正确姿势：批量接口的报文格式、部分失败的处理纪律；再给并发更新装上护栏——序列号做版本判官，谁持有旧号谁被拒。
子章节之间的逻辑关系
三节按"一、单、批"的组织逻辑递进：先吃透一条文档的完整写入路径，再看单文档的读改删如何复用同一条路径，最后扩展到批量与并发场景。4.3 的并发控制依赖 4.1 写入返回的序列号，4.2 的更新语义依赖 4.1 的"删除加重写"模型——顺序阅读，每一节都站在前一节的肩膀上。
4.1 写入与路由 ──► 4.2 单文档读改删 ──► 4.3 批量与并发 │ │ │ └─► 第8章 refresh └─► 第5章 读取与_source └─► 第9章 数据搬运与同步
本章考核清单
| 考核点 | 达标标准 | 对应小节 |
|---|---|---|
| 手算路由 | 给定文档 id 与主分片数，算出目标分片并说出公式的三个输入 | 4.1 |
| 选 id 策略 | 对"工单同步"与"日志采集"两类数据各选对 id 方案并说明理由 | 4.1 |
| 复述写路径 | 按顺序说出写路径六步，标出每步的持久化与可见性边界 | 4.1 |
| 四件套选型 | 对取、探针、改、删四类需求各写出正确的接口 | 4.2 |
| 批量纪律 | 写出合规的批量报文，并演示从响应里找出部分失败条目 | 4.3 |
| 并发护栏 | 用序列号指纹演示一次冲突被拒，并说明外部版本的适用面 | 4.3 |
易错点速查
- 拿时间戳当文档 id：同毫秒碰撞之外还制造路由热点，有天然主键用主键，没有就用自动 id。
- 把更新当行级修改评估容量：更新的成本约等于重写整条文档，大文档高频小改是吞吐杀手。
- 批量响应不逐条核对：整体成功就当全部成功，被拒的条目悄悄丢失，数据对不上才追查。
前置知识与后续延伸
- 前置知识：第 1 章的路由公式雏形；第 3 章的映射登记（写入第一步就是校验映射）；能读懂 JSON 请求与响应。
- 后续延伸：本章写路径中的 refresh 与事务日志在 8.3 展开成近实时机制；批量写入是第 9 章数据管道的日常形态；乐观并发是第 9 章数据库与搜索引擎双向同步的冲突解法。