键值操作

import (
    "context"
    "time"

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

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

// 最简单写入
resp, err := cli.Put(ctx, "/config/db/host", "192.168.1.100")

// 带租约写入（Key 会在 TTL 到期后自动删除）
resp, err := cli.Put(ctx, "/service/host1", "10.0.0.1:8080", clientv3.WithLease(leaseID))

type PutResponse struct {
    Header *ResponseHeader  // 集群元信息（ClusterID, MemberID, Revision, RaftTerm）
    PrevKv *mvccpb.KeyValue // 写入前的旧值（需 WithPrevKV）
}

fmt.Printf("写入成功，revision=%d\n", resp.Header.Revision)

// 原子比较与交换（CAS）—— 只在特定条件下写入
// 如果 /lock 不存在（CreateRevision == 0），则写入
resp, err := cli.Txn(ctx).
    If(clientv3.Compare(clientv3.CreateRevision("/lock"), "=", 0)).
    Then(clientv3.OpPut("/lock", "owner1", clientv3.WithLease(leaseID))).
    Commit()

// 检查写入后的实际 revision
if resp.Succeeded {
    fmt.Println("锁获取成功")
} else {
    fmt.Println("锁已被占用")
}

// 精确获取
resp, err := cli.Get(ctx, "/config/db/host")
if err != nil {
    log.Fatal(err)
}
if len(resp.Kvs) == 0 {
    fmt.Println("key 不存在")
} else {
    fmt.Printf("%s = %s\n", resp.Kvs[0].Key, resp.Kvs[0].Value)
}

type GetResponse struct {
    Header *ResponseHeader
    Kvs    []*mvccpb.KeyValue  // 匹配的 key-value 列表
    Count  int64               // 匹配总数（即使受 limit 限制只返回了部分）
    More   bool                // 是否还有更多结果（配合 WithLimit 做分页）
}

type KeyValue struct {
    Key            []byte
    Value          []byte
    CreateRevision int64  // 此 Key 被创建时的 revision
    ModRevision    int64  // 此 Key 最后一次修改时的 revision
    Version        int64  // 此 Key 被修改过的次数（1 表示创建后未修改）
    Lease          int64  // 绑定的租约 ID（0 表示无租约）
}

// 1. 精确匹配
resp, _ := cli.Get(ctx, "/config/db/host")

// 2. 前缀匹配 — 最常用
resp, _ := cli.Get(ctx, "/config/", clientv3.WithPrefix())

// 3. 范围匹配 [start, end)
resp, _ := cli.Get(ctx, "/a", clientv3.WithRange("/z"))

// 4. 从某个 Key 开始到末尾
resp, _ := cli.Get(ctx, "/b", clientv3.WithFromKey())

// 5. 读取历史版本（快照读）
resp, _ := cli.Get(ctx, "/foo", clientv3.WithRev(100))

// 6. 只取 Key
resp, _ := cli.Get(ctx, "/config/", clientv3.WithPrefix(), clientv3.WithKeysOnly())

// 7. 只取数量
resp, _ := cli.Get(ctx, "/config/", clientv3.WithPrefix(), clientv3.WithCountOnly())
fmt.Printf("匹配 %d 个 key\n", resp.Count)

// 8. 按创建时间降序排列（最新的在前）
resp, _ := cli.Get(ctx, "/service/", clientv3.WithPrefix(),
    clientv3.WithSort(clientv3.SortByCreateRevision, clientv3.SortDescend))

// 9. Serializable 读 — 低延迟，可能不最新
resp, _ := cli.Get(ctx, "/metric/", clientv3.WithPrefix(), clientv3.WithSerializable())

// etcd 原生分页：从上一页最后一个 Key 之后继续
func listAllKeys(cli *clientv3.Client, prefix string) ([]*mvccpb.KeyValue, error) {
    var result []*mvccpb.KeyValue
    opts := []clientv3.OpOption{
        clientv3.WithPrefix(),
        clientv3.WithSort(clientv3.SortByKey, clientv3.SortAscend),
        clientv3.WithLimit(100),
    }

    // rangeEnd 记录本页最后一个 Key，用于下一页的起始
    rangeEnd := prefix + "\x00" // 前缀查询的起始
    initialKey := prefix

    for {
        optsWithStart := append(opts, clientv3.WithFromKey())
        resp, err := cli.Get(ctx, initialKey, optsWithStart...)
        if err != nil {
            return nil, err
        }
        result = append(result, resp.Kvs...)
        if !resp.More {
            break
        }
        // 下一页从最后一个 Key + "\x00" 开始
        lastKey := resp.Kvs[len(resp.Kvs)-1].Key
        initialKey = string(append(lastKey, 0))
    }
    return result, nil
}

// 精确删除
resp, err := cli.Delete(ctx, "/obsolete/key")

// 前缀删除（删除整个子树）
resp, err := cli.Delete(ctx, "/old-config/", clientv3.WithPrefix())

// 范围删除
resp, err := cli.Delete(ctx, "/a", clientv3.WithRange("/z"))

// 返回被删除的内容
resp, err := cli.Delete(ctx, "/foo", clientv3.WithPrevKV())
for _, kv := range resp.PrevKvs {
    fmt.Printf("已删除: %s = %s\n", kv.Key, kv.Value)
}

// 获取删除数量
fmt.Printf("删除了 %d 个 key\n", resp.Deleted)

type DeleteResponse struct {
    Header  *ResponseHeader
    Deleted int64              // 删除了多少个 key
    PrevKvs []*mvccpb.KeyValue // 被删除的 key-value（需 WithPrevKV）
}

// 模式一：先 Get 记住 revision，再 Watch 不丢事件
getResp, _ := cli.Get(ctx, "/service/", clientv3.WithPrefix())
startRev := getResp.Header.Revision + 1

// 处理当前已有数据
for _, kv := range getResp.Kvs {
    handleService(kv)
}

// 从 startRev 开始监听，不会丢事件
watchChan := cli.Watch(ctx, "/service/",
    clientv3.WithPrefix(),
    clientv3.WithRev(startRev),
)

// 模式二：乐观并发控制
// 读取当前值及其 ModRevision
getResp, _ := cli.Get(ctx, "/counter")
modRev := getResp.Kvs[0].ModRevision
val := string(getResp.Kvs[0].Value)

// 原子更新：仅当 ModRevision 未变时才写入
txnResp, _ := cli.Txn(ctx).
    If(clientv3.Compare(clientv3.ModRevision("/counter"), "=", modRev)).
    Then(clientv3.OpPut("/counter", increment(val))).
    Else(clientv3.OpGet("/counter")).
    Commit()

if txnResp.Succeeded {
    fmt.Println("更新成功")
} else {
    fmt.Println("并发冲突，需要重试")
}