5.高级键值 API 深度解析

在 etcd 的设计理念中，所有对键值存储的修改操作（Put、Delete）和读取操作（Range）本质上都是独立的 gRPC 调用。虽然 etcd 通过 Raft 算法保证了单个操作的原子性，但在处理多个相关联的操作时，如果简单地将它们组合在一起，就可能面临竞态条件（Race Condition）的风险。

想象一个场景：你需要读取一个配置项，根据其值决定是否更新它。如果在读取和写入之间，另一个客户端修改了这个配置项，你的操作就会基于过时的信息进行，这可能导致数据不一致。为了解决这类问题，etcd 提供了 事务（Transaction）。

事务在 etcd 中被实现为一个原子性的 If/Then/Else 构造。它允许我们将一组操作捆绑在一起，只有在满足特定条件（If）时，才会执行“成功”分支（Then）的操作；否则，执行“失败”分支（Else）的操作。整个过程是原子的，这意味着在事务执行期间，其他客户端无法看到中间状态，要么看到事务开始前的状态，要么看到事务完成后的最终状态。

事务的结构

一个 etcd 事务请求（TxnRequest）主要由三部分组成：

1. 比较（Compare）：相当于 If 子句。它是一个或多个条件的列表，这些条件会检查存储中特定键的当前状态（如版本号、修改修订号、值等）。只有当列表中所有的比较条件都为真时，事务才会进入 success 分支。
2. 成功操作（Success）：相当于 Then 子句。这是一个操作列表，当 Compare 中的所有条件都满足时，这些操作将被按顺序执行。
3. 失败操作（Failure）：相当于 Else 子句。这也是一个操作列表，当 Compare 中有任何一个条件不满足时，这些操作将被按顺序执行。

etcdctl 中的事务操作

etcdctl 提供了 txn 命令来与事务 API 交互。它有两种模式：交互式模式和非交互式模式。对于学习和调试，交互式模式非常直观。

让我们通过一个经典的“比较并交换”（Compare-and-Swap, CAS）场景来理解事务：只有当键 /lock 的值为 free 时，才将其修改为 locked。

首先，初始化这个键：

etcdctl put /lock free

现在，我们尝试通过事务来执行这个原子性的修改：

etcdctl txn --interactive

compares:
value("/lock") = "free"

success requests (get, put, delete):
put /lock locked

failure requests (get, put, delete):
get /lock

执行过程解析：

1. 输入比较条件：value("/lock") = "free"。事务会检查 /lock 这个键当前的 value 是否确实等于 "free"。
2. 输入成功操作：put /lock locked。如果比较成功，就执行这个写入操作。
3. 输入失败操作：get /lock。如果比较失败（例如，/lock 的值已经是 locked 或者键不存在），就执行这个读取操作，以便了解当前状态。

输出结果：

SUCCESS

ResponseHeader:
cluster_id: 12585971608760269493
member_id: 13847567121247652255
revision: 2
raft_term: 2

responses:
0:
response_put:
header:
revision: 2

输出中的 SUCCESS 表明 Compare 条件成立，并且 success 分支的操作已经执行。revision: 2 变成了 revision: 3，表明存储状态已更新。

如果我们再次运行同样的事务，由于 /lock 的值现在是 locked，比较将会失败：

etcdctl txn --interactive

compares:
value("/lock") = "free"

success requests (get, put, delete):
put /lock locked

failure requests (get, put, delete):
get /lock

输出结果：

FAILURE

ResponseHeader:
cluster_id: 12585971608760269493
member_id: 13847567121247652255
revision: 3
raft_term: 2

responses:
0:
response_range:
header:
revision: 3
kvs:
- key: /lock
  create_revision: 2
  mod_revision: 3
  version: 2
  value: locked
count: 1

这次输出是 FAILURE，并且执行了 failure 分支的 get /lock 操作，返回了当前的键值信息。

比较并交换操作

“比较并交换”（Compare-and-Swap, CAS）是并发控制中的一种原子操作模式，它在分布式系统中至关重要。其核心思想是：仅当共享变量的当前值与预期值相等时，才更新该变量。这可以有效防止在读-改-写过程中被其他线程或进程打断。

etcd 的事务 API 是实现 CAS 的完美工具。它不仅支持基于值的比较，还支持基于版本、创建修订号和修改修订号的比较，这为构建复杂的并发控制逻辑提供了强大的基础。

CAS 的核心要素

一个完整的 CAS 操作包含三个要素：

1. 目标键（Key）：要操作的键。
2. 预期状态（Condition）：目标键当前应该处于的状态。
3. 新状态（New Value）：如果预期状态匹配，则将目标键更新为的新状态。

使用 etcdctl 实现 CAS

etcdctl txn 命令是实现 CAS 的直接方式。我们来看一个更复杂的例子：假设我们有一个任务队列 /task_queue/next_task，多个工作节点都在监听这个键。当一个节点获取任务时，它需要原子性地完成两件事：

1. 读取任务内容。
2. 删除 /task_queue/next_task 键，以便其他节点可以获取下一个任务。

如果这两个操作不是原子的，可能会出现一个节点读取了任务但还没来得及删除，另一个节点也读取了同一个任务，导致任务被重复处理。

使用事务可以完美解决这个问题：

# 假设任务队列中已经有一个任务
etcdctl put /task_queue/next_task "process_data_job"

# 现在，一个工作节点尝试原子性地获取并删除任务
etcdctl txn --interactive

compares:
key("/task_queue/next_task")

success requests (get, put, delete):
get /task_queue/next_task
delete /task_queue/next_task

failure requests (get, put, delete):

执行过程解析：

1. 比较条件：key("/task_queue/next_task")。这个比较检查 /task_queue/next_task 这个键是否存在。key 比较是一种特殊的比较，它只检查键的存在性，不关心值。
2. 成功操作：如果键存在，就按顺序执行两个操作：先 get 获取任务内容，然后 delete 删除该键。
3. 失败操作：这里留空，表示如果键不存在，什么都不做。

输出结果：

SUCCESS

ResponseHeader:
cluster_id: 12585971608760269493
member_id: 13847567121247652255
revision: 4
raft_term: 2

responses:
0:
response_range:
header:
revision: 4
kvs:
- key: /task_queue/next_task
  create_revision: 2
  mod_revision: 2
  version: 1
  value: process_data_job
count: 1
1:
response_delete_range:
header:
revision: 4
deleted: 1

输出清晰地展示了事务的成功执行：responses 列表包含了 get 操作返回的键值对，以及 delete 操作删除的键数量。整个过程在一个修订号（revision: 4）内完成，保证了原子性。

比较类型详解

etcd 的 Compare 消息提供了丰富的比较目标（target）和比较结果（result）：

• 比较目标（CompareTarget）：

  • VERSION：比较键的版本号（version）。每次修改都会使版本号+1，创建时为1。
  • CREATE：比较键的创建修订号（create_revision）。一个键一旦创建，其创建修订号就固定了。
  • MOD：比较键的最后修改修订号（mod_revision）。
  • VALUE：比较键的值（value）。
  • LEASE：比较键关联的租约ID（lease）。

• 比较结果（CompareResult）：

  • EQUAL (=)
  • GREATER (>)
  • LESS (<)
  • NOT_EQUAL (!=)

通过组合这些目标和结果，可以构建出非常精细的条件逻辑。例如，mod_revision 常用于实现乐观锁：客户端读取一个键时记录其 mod_revision，在更新时，通过事务比较 mod_revision 是否与之前读取的一致，如果一致则更新，否则说明在期间有其他客户端修改了该键，更新失败。

批量操作实现

在实际应用中，我们经常需要一次性处理多个键值对，例如批量写入配置、批量删除过期数据等。虽然可以循环调用单个的 Put 或 Delete API，但这样做效率较低，且无法保证所有操作的原子性（每个操作都是独立的事务）。

etcd 的事务 API 提供了一种高效的批量操作实现方式。在一个事务的 success 或 failure 分支中，可以包含多个 RequestOp，每个 RequestOp 可以是一个 PutRequest、DeleteRangeRequest 或 RangeRequest。这些操作在同一个事务中被原子性地执行。

批量写入（原子性更新）

假设我们需要一次性更新多个应用的配置状态：

etcdctl txn --interactive

compares:
value("/app/serviceA/status") = "active"

success requests (get, put, delete):
put /app/serviceA/status "maintenance"
put /app/serviceB/status "maintenance"
put /app/serviceC/status "maintenance"

failure requests (get, put, delete):

这个事务首先检查 /app/serviceA/status 是否为 active。如果是，则原子性地将 A、B、C 三个服务的状态都更新为 maintenance。如果 A 的状态不是 active，则整个批量更新都不会执行。

批量删除（原子性删除范围）

DeleteRangeRequest 本身就支持范围删除，这可以看作是一种特殊的批量操作。通过事务来执行范围删除，可以使其成为更复杂逻辑的一部分。

例如，我们想在满足某个条件时，原子性地删除一个前缀下的所有键：

# 假设存在 /session/active/u1, /session/active/u2 等键
etcdctl txn --interactive

compares:
key("/session/lock")

success requests (get, put, delete):
delete /session/active/ --prefix

failure requests (get, put, delete):

这个事务检查 /session/lock 键是否存在。如果存在，就删除所有以 /session/active/ 为前缀的键。这在实现会话清理或资源回收时非常有用。

批量读取（原子性范围查询）

在事务中执行 RangeRequest 可以保证在事务上下文中读取到的数据是一致的。虽然在 success 分支中执行 get 操作通常只是为了获取信息（因为 get 不会改变存储状态），但它确保了读取操作与同一事务中的写入操作是在同一个修订号快照下进行的。

例如，一个复杂的业务逻辑可能需要先读取一批数据，根据这些数据决定写入什么内容：

etcdctl txn --interactive

compares:
value("/config/global/enable_batch") = "true"

success requests (get, put, delete):
get /batch/items/ --prefix
put /batch/last_run_time "2023-10-27T10:00:00Z"

failure requests (get, put, delete):

这个事务首先检查全局配置是否开启了批处理模式。如果开启，它会一次性读取所有 /batch/items/ 下的键，然后更新最后运行时间。虽然 get 的结果不会直接用于后续的 put，但它确保了在检查配置和读取数据之间，存储状态没有被其他事务改变。

高级查询模式

除了基础的键值读取，etcd 的 RangeRequest 提供了多种高级查询模式，这些模式在构建复杂应用时非常强大。

1. 分页查询（Limit）

当一个前缀查询可能返回大量结果时，一次性获取所有数据会消耗大量网络带宽和客户端内存。limit 字段允许服务器在返回指定数量的键后停止，客户端可以通过后续请求（使用 key 和 range_end 或 revision）来获取剩余数据。

# 假设有 /users/1 到 /users/10
# 获取前3个用户
etcdctl get --prefix --limit=3 /users/

2. 排序查询（Sort）

RangeRequest 可以对返回的结果进行排序。这在需要按特定顺序处理数据时非常有用，例如按创建时间处理任务。

排序由两个字段控制：

• sort_target：指定按哪个字段排序（KEY, VERSION, CREATE, MOD, VALUE）。
• sort_order：指定排序顺序（NONE, ASCEND, DESCEND）。

etcdctl 提供了 --order-by 和 --sort-by 标志来简化排序操作。

# 按键名升序排列
etcdctl get --prefix /config/ --order-by KEY --sort-by ASCEND

# 按最后修改时间降序排列，获取最新的修改
etcdctl get --prefix /logs/ --order-by MOD --sort-by DESCEND

3. 修订号范围过滤（Revision Filtering）

除了通过 --rev 指定查询的时间点，RangeRequest 还允许在查询时对结果集进行过滤，只返回创建修订号或修改修订号在特定范围内的键。

• min_mod_revision / max_mod_revision：过滤修改修订号。
• min_create_revision / max_create_revision：过滤创建修订号。

这在实现“查找最近被修改过的键”或“查找某个时间段内创建的键”这类需求时非常高效。

# 查找修改修订号大于等于100的键
etcdctl get --prefix / --min-mod-revision 100

# 查找创建修订号在50到100之间的键
etcdctl get --prefix / --min-create-revision 50 --max-create-revision 100

4. 仅获取元数据（Keys Only / Count Only）

有时我们只关心某个范围内的键是否存在，或者有多少个键，而不需要获取具体的值。这在处理海量数据时可以极大地减少数据传输量。

• keys_only：只返回键，不返回值。
• count_only：只返回匹配键的数量，不返回任何键或值。

# 只列出所有以 /service/ 开头的键
etcdctl get --prefix /service/ --keys-only

# 统计 /users/ 目录下有多少个用户
etcdctl get --prefix /users/ --count-only

5. 串行化读（Serializable Reads）

默认情况下，etcdctl get 执行的是线性化读（Linearizable Read），它通过 Raft 共识保证了数据的强一致性，但会带来一定的延迟。在某些场景下（例如监控仪表盘、非关键状态检查），我们可以接受读取到稍旧的数据以换取更高的性能和可用性。

通过设置 serializable 标志，读取请求将直接由处理请求的 etcd 节点本地响应，而无需经过 Raft 共识过程。

# 执行一次串行化读，可能会读到旧数据，但速度更快
etcdctl get --prefix /metrics/ --serializable

键值 API 完整参考

为了方便查阅，以下是 etcd v3 键值 API 核心消息的字段和语义的快速参考。这些定义源自 etcd 的 gRPC Proto 文件。

KeyValue 消息

这是 etcd 存储的基本单元，代表一个键值对及其元数据。

字段	类型	描述
key	bytes	键。
create_revision	int64	该键被创建时的全局修订号。
mod_revision	int64	该键最后一次被修改时的全局修订号。
version	int64	键的版本号。创建时为1，每次修改（Put）会递增。删除后重置为0。
value	bytes	值。
lease	int64	关联到该键的租约ID。0表示没有租约。

RangeRequest 消息

用于读取键值对。

字段	类型	描述
key	bytes	起始键。
range_end	bytes	结束键。查询范围为 [key, range_end)。如果为空，则只查询 key。如果为 \0，则查询所有大于等于 key 的键。如果为 key + 1，则查询所有以 key 为前缀的键。
limit	int64	返回结果的最大数量。0表示无限制。
revision	int64	查询的修订号。0或负数表示查询最新版本。
sort_order	SortOrder	排序顺序（NONE, ASCEND, DESCEND）。
sort_target	SortTarget	排序目标（KEY, VERSION, CREATE, MOD, VALUE）。
serializable	bool	是否使用串行化读（本地读）。
keys_only	bool	是否只返回键。
count_only	bool	是否只返回数量。
min_mod_revision	int64	过滤：最小修改修订号。
max_mod_revision	int64	过滤：最大修改修订号。
min_create_revision	int64	过滤：最小创建修订号。
max_create_revision	int64	过滤：最大创建修订号。

PutRequest 消息

用于写入键值对。

字段	类型	描述
key	bytes	要写入的键。
value	bytes	要写入的值。
lease	int64	要关联的租约ID。
prev_kv	bool	是否在响应中返回修改前的键值对。
ignore_value	bool	是否忽略请求中的 value 字段，仅更新 lease。
ignore_lease	bool	是否忽略请求中的 lease 字段，仅更新 value。

DeleteRangeRequest 消息

用于删除键值对。

字段	类型	描述
key	bytes	起始键。
range_end	bytes	结束键。删除范围为 [key, range_end)。
prev_kv	bool	是否在响应中返回被删除的键值对。

TxnRequest 消息

用于执行事务。

字段	类型	描述
compare	Compare 列表	If 条件列表。所有条件都为真时，执行 success。
success	RequestOp 列表	Then 操作列表。
failure	RequestOp 列表	Else 操作列表。

Compare 消息

事务中的比较条件。

字段	类型	描述
result	CompareResult	比较操作（EQUAL, GREATER, LESS, NOT_EQUAL）。
target	CompareTarget	比较的目标字段（VERSION, CREATE, MOD, VALUE, LEASE）。
key	bytes	要比较的键。
target_union	oneof	用于比较的值（version, create_revision, mod_revision, value, lease）。
range_end	bytes	支持对一个范围内的所有键进行相同的比较。

RequestOp 消息

事务中要执行的操作。

字段	类型	描述
request	oneof	可以是 RangeRequest, PutRequest, DeleteRangeRequest 或嵌套的 TxnRequest。

---

本章深入探讨了 etcd 键值 API 的高级特性，特别是事务和高级查询模式。这些功能是构建健壮、高并发分布式应用的基石。通过原子性的事务，我们可以轻松实现复杂的协调逻辑，而无需担心竞态条件。高级查询模式则提供了强大的数据检索能力，使我们能够高效地处理和分析存储在 etcd 中的数据。

掌握了这些高级 API，我们已经具备了操作 etcd 核心数据模型的能力。接下来，我们将目光转向 etcd 的另一个强大特性：Watch API。它提供了一种事件驱动的机制，让应用能够实时监听数据的变化，而不是被动地轮询。这在构建响应式系统和服务发现等场景中至关重要。