4.键值操作核心技能

在上一章中，我们通过 etcdctl 完成了最基础的键值读写操作，迈出了与 etcd 交互的第一步。然而，在真实的应用场景中，单个键的读写往往无法满足复杂业务的需求。我们经常需要处理一系列相关的键，或者需要确保多个操作的原子性，甚至需要在特定条件下才执行某些操作。

本章将深入探讨 etcd 键值操作的核心技能，这些技能是构建分布式系统协调逻辑的基石。我们将从如何高效地查询一段连续的数据开始，学习如何通过前缀来管理配置项，掌握批量删除数据的技巧，最后还将初步接触能够保证数据一致性的事务操作。掌握这些技能，你将能够更加灵活和安全地操控 etcd 中的数据。

范围查询操作

在实际应用中，数据往往不是孤立存在的。例如，一个服务的配置可能包含多个子项（/service/app/host, /service/app/port），或者一个用户可能有多条相关信息（/users/123/name, /users/123/email）。如果每次都需要单独查询每一个键，效率会非常低下。etcd 提供了强大的范围查询功能，允许我们一次性获取一个键区间内的所有数据。

理解键的字典序

etcd 内部存储键值对时，是按照键（Key）的字节顺序（byte order）进行排序的。这意味着 a 排在 b 之前，aa 排在 ab 之前，1 排在 2 之前。范围查询正是利用了这种排序特性，通过指定一个起始键（key）和一个结束键（range_end）来定义一个左闭右开的区间 [key, range_end)。

这个区间包含 key，但不包含 range_end。这与很多编程语言中数组切片的处理方式类似。

使用 etcdctl 进行范围查询

我们可以通过 etcdctl get 命令配合 --range 标志来执行范围查询。让我们通过一些例子来具体看看。

假设我们有以下数据已经存储在 etcd 中：

etcdctl put config/database/host "db.example.com"
etcdctl put config/database/port "5432"
etcdctl put config/database/username "admin"
etcdctl put config/api/endpoint "api.example.com"
etcdctl put config/api/token "secret-token"

现在，我们想获取所有数据库相关的配置。数据库配置的键都以 config/database/ 开头。我们可以将起始键设为 config/database/，结束键设为比这个前缀“大一点”的值。

在 etcd 中，一个常见的技巧是将结束键设置为前缀本身加上一个空字节（\0）。在字典序中，\0 是最小的字节，所以 config/database/\0 比任何以 config/database/ 开头的键都要大，但又不会包含其他前缀（如 config/api/）的数据。

# 查询 config/database/ 到 config/database/\0 之间的所有键
etcdctl get config/database/ config/database/\0

执行结果：

config/database/host
db.example.com
config/database/port
5432
config/database/username
admin

可以看到，config/api/ 的数据没有被包含进来，因为我们定义的范围是精确的。

编程方式实现范围查询

在应用程序中，我们通常使用 etcd 的客户端库来实现范围查询。以 Go 语言的官方客户端 clientv3 为例，我们使用 Get 方法，并传入一个 WithRange 选项。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.etcd.io/etcd/client/v3"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"localhost:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// 准备一些示例数据
	cli.Put(ctx, "user/1/name", "Alice")
	cli.Put(ctx, "user/1/email", "alice@example.com")
	cli.Put(ctx, "user/2/name", "Bob")
	cli.Put(ctx, "user/2/email", "bob@example.com")

	// 定义范围查询的区间
	// 我们想查询 user/1 的所有信息
	// 起始键: user/1/
	// 结束键: user/1/ 后面跟一个空字节
	startKey := "user/1/"
	endKey := "user/1/\x00"

	resp, err := cli.Get(ctx, startKey, clientv3.WithRange(endKey))
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("范围查询结果:")
	for _, kv := range resp.Kvs {
		fmt.Printf("Key: %s, Value: %s\n", kv.Key, kv.Value)
	}
}

代码讲解:

1. 我们首先建立了一个到 etcd 的连接，并准备了一些测试数据，模拟一个用户 user/1 和 user/2 的信息。
2. startKey 被设置为 "user/1/"，endKey 被设置为 "user/1/\x00"。这里的 \x00 是 Go 语言中表示空字节的方式。这个组合定义了一个左闭右开区间 [user/1/, user/1/\x00)。
3. cli.Get(ctx, startKey, clientv3.WithRange(endKey)) 这行代码是核心。它告诉 etcd 服务器：“请返回所有键大于等于 user/1/ 且小于 user/1/\x00 的键值对”。
4. 最后，我们遍历返回的 Kvs 切片，打印出所有匹配的键和值。

这个例子清晰地展示了如何通过编程方式精确地获取一个键区间内的数据，这对于处理具有层级结构的数据模型非常有用。

前缀匹配查询

范围查询虽然强大，但语法稍显复杂。在很多场景下，我们更关心的是“所有以某个字符串开头的键”，这正是前缀匹配查询的用武之地。例如，查询一个服务下的所有实例，或者获取一个目录下的所有文件。

etcd 的 etcdctl 工具和客户端库都为前缀查询提供了专门的优化选项，它本质上是范围查询的一种语法糖，但使用起来更加直观。

使用 --prefix 进行查询

继续使用上一节的例子，如果我们想获取所有数据库相关的配置，使用前缀查询会更加简单。

etcdctl get --prefix config/database/

执行结果：

config/database/host
db.example.com
config/database/port
5432
config/database/username
admin

这个命令会返回所有键以 config/database/ 开头的键值对。它等价于我们之前使用的 etcdctl get config/database/ config/database/\0，但显然更易于记忆和使用。

客户端库中的前缀查询

在 Go 客户端中，WithPrefix() 选项提供了同样的功能。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.etcd.io/etcd/client/v3"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"localhost:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// 准备一些示例数据
	cli.Put(ctx, "services/web/1", "192.168.1.10")
	cli.Put(ctx, "services/web/2", "192.168.1.11")
	cli.Put(ctx, "services/db/1", "192.168.1.20")
	cli.Put(ctx, "cache/redis", "127.0.0.1")

	// 查询所有服务实例
	resp, err := cli.Get(ctx, "services/web/", clientv3.WithPrefix())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("前缀查询结果 (services/web/):")
	for _, kv := range resp.Kvs {
		fmt.Printf("Key: %s, Value: %s\n", kv.Key, kv.Value)
	}
}

代码讲解:

1. 我们创建了几个不同前缀的键，模拟服务注册的场景。
2. clientv3.WithPrefix() 是这里的魔法。它会自动计算出正确的 range_end。对于前缀 services/web/，它会将其转换为范围 [services/web/, services/web0)（注意，这里 0 是比 / 大的字符），从而囊括所有以 services/web/ 开头的键。
3. 查询结果只包含了 services/web/1 和 services/web/2，而 services/db/1 和 cache/redis 被正确地排除了。

前缀查询是 etcd 中最常用的操作之一，它极大地简化了对树形或层级数据结构的管理。

删除键值数据

与写入和读取一样，删除也是数据管理的基本操作。etcd 不仅支持删除单个键，同样支持范围删除和前缀删除，这在清理过期数据或重置配置时非常有用。

删除单个键

删除单个键非常简单，使用 etcdctl del 命令即可。

# 先写入一个键
etcdctl put temp_key "temporary_value"

# 删除这个键
etcdctl del temp_key

执行 del 命令后，它会返回一个数字，表示成功删除的键的数量。

范围删除

与范围查询类似，etcdctl del 也支持指定一个起始键和一个结束键来删除一个区间内的所有数据。

假设我们有以下数据：

etcdctl put logs/2023-10-01 "log data 1"
etcdctl put logs/2023-10-02 "log data 2"
etcdctl put logs/2023-10-03 "log data 3"
etcdctl put logs/2023-10-04 "log data 4"

现在，我们想删除 10 月 2 日和 3 日的日志（logs/2023-10-02 和 logs/2023-10-03）。

etcdctl del logs/2023-10-02 logs/2023-10-04

这个命令会删除从 logs/2023-10-02 开始，到但不包含 logs/2023-10-04 的所有键。执行后，logs/2023-10-02 和 logs/2023-10-03 会被删除，而 logs/2023-10-01 和 logs/2023-10-04 会保留。

前缀删除

前缀删除是清理数据的利器。例如，要删除一个服务的所有注册信息，或者清空一个目录下的所有配置。

# 假设我们有以下数据
etcdctl put staging/config/timeout "30s"
etcdctl put staging/config/retry "3"

# 删除所有 staging 环境的配置
etcdctl del --prefix staging/

--prefix 标志告诉 etcdctl 删除所有以 staging/ 开头的键。这比手动指定范围要方便得多。

客户端库中的删除操作

在 Go 客户端中，删除操作通过 Delete 方法实现，它同样支持 WithRange 和 WithPrefix 选项。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.etcd.io/etcd/client/v3"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"localhost:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// 准备数据
	cli.Put(ctx, "cache/session/1", "data1")
	cli.Put(ctx, "cache/session/2", "data2")
	cli.Put(ctx, "cache/user/1", "data3")

	// 使用前缀删除所有 cache/session 数据
	resp, err := cli.Delete(ctx, "cache/session/", clientv3.WithPrefix())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("删除了 %d 个键\n", resp.Deleted)

	// 验证删除结果
	getResp, _ := cli.Get(ctx, "cache/", clientv3.WithPrefix())
	fmt.Println("删除后剩余的键:")
	for _, kv := range getResp.Kvs {
		fmt.Printf("Key: %s\n", kv.Key)
	}
}

代码讲解:

1. 我们创建了几个不同路径的键。
2. cli.Delete(ctx, "cache/session/", clientv3.WithPrefix()) 这行代码执行了前缀删除。它会删除所有以 cache/session/ 开头的键。
3. resp.Deleted 字段会返回实际被删除的键的数量。
4. 最后，我们再次查询 cache/ 前缀下的所有键，以验证 cache/session/1 和 cache/session/2 已被删除，而 cache/user/1 依然存在。

批量操作技巧

在很多情况下，我们需要将多个操作（如 Put, Delete, Get）组合在一起，作为一个整体来执行。虽然 etcd 的客户端库允许我们在一个循环中依次发送多个请求，但这不仅效率低下，而且无法保证这些操作的原子性。如果在执行到一半时网络中断或客户端崩溃，系统就会处于一个不一致的中间状态。

etcd 提供了两种机制来应对批量操作的需求：一种是简单的客户端批量提交，另一种是强大的事务（Transaction）机制。本节我们先讨论前者，事务将在下一节深入探讨。

客户端批量提交

客户端批量提交指的是在客户端侧，将多个独立的请求通过并发或流水线的方式发送给 etcd 服务器。这可以显著提高吞吐量，但不提供原子性保证。

以 Go 客户端为例，我们可以使用 etcdctl 的批处理能力，或者在代码中使用 go 协程并发执行多个 Put 或 Get 操作。

package main

import (
	"context"
	"fmt"
	"log"
	"sync"
	"time"

	"go.etcd.io/etcd/client/v3"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"localhost:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// 模拟批量写入场景：初始化一批用户数据
	userData := map[string]string{
		"users/101/name":   "Alice",
		"users/101/status": "active",
		"users/102/name":   "Bob",
		"users/102/status": "inactive",
		"users/103/name":   "Charlie",
		"users/103/status": "active",
	}

	var wg sync.WaitGroup
	errors := make(chan error, len(userData))

	fmt.Println("开始并发写入数据...")
	startTime := time.Now()

	// 使用协程并发写入
	for key, value := range userData {
		wg.Add(1)
		go func(k, v string) {
			defer wg.Done()
			_, err := cli.Put(ctx, k, v)
			if err != nil {
				errors <- fmt.Errorf("failed to put %s: %v", k, err)
			}
		}(key, value)
	}

	wg.Wait()
	close(errors)

	// 检查是否有错误
	hasError := false
	for err := range errors {
		log.Println(err)
		hasError = true
	}

	if !hasError {
		fmt.Printf("批量写入完成，耗时: %v\n", time.Since(startTime))
	}

	// 验证数据
	fmt.Println("\n验证写入的数据:")
	resp, err := cli.Get(ctx, "users/", clientv3.WithPrefix())
	if err != nil {
		log.Fatal(err)
	}
	for _, kv := range resp.Kvs {
		fmt.Printf("%s: %s\n", kv.Key, kv.Value)
	}
}

代码讲解:

1. 我们定义了一个 userData map，包含了需要写入的键值对。
2. 使用 sync.WaitGroup 和协程（go func）来并发执行 Put 操作。每个协程负责写入一个键值对。
3. 通过 errors channel 收集所有协程可能产生的错误。
4. wg.Wait() 会阻塞直到所有协程都执行完毕。
5. 这种方式可以充分利用网络带宽和 etcd 的处理能力，比在一个循环中顺序执行 Put 操作要快得多。

重要提示：这种客户端批量提交方式不保证原子性。如果写入过程中部分成功、部分失败，系统数据将处于不一致状态。它只适用于对性能要求高，且能容忍部分失败或后续进行数据一致性校验的场景。对于需要强一致性的操作，必须使用事务。

事务基础概念

事务是 etcd 提供的最强大的功能之一，它允许你将多个操作打包成一个原子性的单元。这意味着要么所有操作都成功执行，要么在遇到任何问题时所有操作都不会生效，系统会回滚到事务开始前的状态。这对于实现锁、选举、比较并交换（Compare-and-Swap）等分布式协调原语至关重要。

事务的三要素：If, Then, Else

etcd 的事务模型可以被理解为一个 If-Then-Else 的逻辑结构：

1. If (比较条件)：这是一个或多个对键值状态的检查。例如，“检查键 /lock 是否不存在”或者“检查键 /config/version 的值是否为 1”。只有当所有比较条件都为真时，事务才会进入 Then 分支。
2. Then (成功操作)：如果 If 中的所有比较条件都为真，则执行这里定义的一系列操作（如 Put, Delete, Get）。这些操作会被作为一个原子性的单元应用到 etcd 中。
3. Else (失败操作)：如果 If 中有任何一个比较条件为假，则执行这里定义的一系列操作。这个分支是可选的，可以为空。

使用 etcdctl 体验事务

etcdctl 提供了一个 txn 命令，我们可以用它来交互式地体验事务。这对于理解事务的工作流程非常有帮助。

假设我们想实现一个简单的分布式锁：只有当锁（/mylock）不存在时，才能获取它（写入自己的标识）。

场景： 两个客户端尝试获取同一个锁。

客户端 1 的操作：

# 以交互模式启动事务
etcdctl txn --interactive

# 1. 定义比较条件 (If)
# 检查 /mylock 是否不存在 (create_revision 为 0 表示键不存在)
compares:
value("/mylock") = "non-exist"  # 这里我们用一个不存在的值来模拟，更常见的是用 version 或 create_revision

# 2. 定义成功操作 (Then)
# 如果 /mylock 不存在，则创建它并写入 "client-1"
success requests (get, put, delete):
put /mylock "client-1"

# 3. 定义失败操作 (Else)
# 如果 /mylock 已存在，则获取当前的持有者信息
failure requests (get, put, delete):
get /mylock

客户端 1 的执行结果：

SUCCESS

这表示事务成功了，If 条件满足（因为我们假设 /mylock 不存在），Then 分支被执行，/mylock 被创建。

客户端 2 尝试获取锁：

etcdctl txn --interactive

compares:
value("/mylock") = "non-exist"

success requests (get, put, delete):
put /mylock "client-2"

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

客户端 2 的执行结果：

FAILURE

这表示事务失败了。因为 If 条件不满足（/mylock 的值是 "client-1"，不是 "non-exist"），所以 Then 分支被跳过，Else 分支被执行。Else 分支中的 get /mylock 操作被执行，并返回了当前锁的持有者信息。

客户端库中的事务实现

在 Go 客户端中，事务通过 Txn 方法实现。它接收一个 If 条件列表，然后可以链式调用 Then 和 Else 方法。

让我们用代码来实现上面的分布式锁获取逻辑。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.etcd.io/etcd/client/v3"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"localhost:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	lockKey := "/mylock"

	// 模拟客户端 1 获取锁
	fmt.Println("客户端 1 尝试获取锁...")
	txn1 := cli.Txn(ctx)
	txn1.If(clientv3.Compare(clientv3.Version(lockKey), "=", 0)). // 如果键的版本为0（表示不存在）
		Then(clientv3.OpPut(lockKey, "client-1")).
		Else(clientv3.OpGet(lockKey))

	resp1, err := txn1.Commit()
	if err != nil {
		log.Fatal(err)
	}

	if resp1.Succeeded {
		fmt.Println("客户端 1: 成功获取锁!")
	} else {
		fmt.Println("客户端 1: 获取锁失败，锁已被占用。")
		for _, op := range resp1.Responses {
			getResp := op.GetResponseRange()
			if getResp != nil && len(getResp.Kvs) > 0 {
				fmt.Printf("当前锁持有者: %s\n", getResp.Kvs[0].Value)
			}
		}
	}

	// 模拟客户端 2 获取锁
	fmt.Println("\n客户端 2 尝试获取锁...")
	txn2 := cli.Txn(ctx)
	txn2.If(clientv3.Compare(clientv3.Version(lockKey), "=", 0)).
		Then(clientv3.OpPut(lockKey, "client-2")).
		Else(clientv3.OpGet(lockKey))

	resp2, err := txn2.Commit()
	if err != nil {
		log.Fatal(err)
	}

	if resp2.Succeeded {
		fmt.Println("客户端 2: 成功获取锁!")
	} else {
		fmt.Println("客户端 2: 获取锁失败，锁已被占用。")
		for _, op := range resp2.Responses {
			getResp := op.GetResponseRange()
			if getResp != nil && len(getResp.Kvs) > 0 {
				fmt.Printf("当前锁持有者: %s\n", getResp.Kvs[0].Value)
			}
		}
	}
}

代码讲解:

1. clientv3.Compare(clientv3.Version(lockKey), "=", 0) 创建了一个比较条件：检查 lockKey 的版本号是否等于 0。如果键不存在，其版本号就是 0。
2. .Then(clientv3.OpPut(lockKey, "client-1")) 定义了成功时要执行的操作：Put 一个键值对。
3. .Else(clientv3.OpGet(lockKey)) 定义了失败时要执行的操作：Get 这个键的当前值。
4. txn.Commit() 将整个事务提交给 etcd 服务器执行。
5. resp.Succeeded 布尔值告诉我们事务是走了 Then 分支还是 Else 分支。
6. resp.Responses 是一个切片，包含了事务中执行的操作的返回结果。我们需要根据操作的顺序和类型来解析这些结果。

这个例子完美地展示了事务如何保证操作的原子性：在客户端 1 成功创建锁之后，客户端 2 的事务会因为比较失败而不会执行 Then 分支的 Put 操作，从而避免了并发写入导致的数据覆盖问题。

本章小结

本章我们深入探索了 etcd 键值操作的核心技能，这些技能是构建健壮分布式应用的基础。

我们学习了如何通过范围查询和前缀查询来高效地读取连续或相关的数据，这对于管理层级配置和批量获取信息至关重要。我们还掌握了使用 etcdctl 和客户端库进行批量删除的技巧，这在数据清理和重置场景中非常实用。

最后，我们初步接触了 etcd 最强大的特性之一——事务。通过 If-Then-Else 模型，etcd 允许我们将多个操作打包成一个原子性的单元，从而保证了在并发环境下的数据一致性。我们通过一个简单的分布式锁示例，展示了事务在解决竞争条件问题上的威力。

掌握了这些核心技能，你已经具备了处理更复杂数据操作的能力。在下一章中，我们将对 etcd 的键值 API 进行更深度的解析，探讨更复杂的事务语义和高级查询模式，让你对 etcd 的能力有更全面的认识。