Etcd教程 — 第六章 Etcd之核心API V3_etcd v3 api操作手册

在 .proto 文件中添加注释：

message SearchRequest {
string query = 1;
int32 page_number = 2; // Which page number do we want?
int32 result_per_page = 3; // Number of results to return per page.
}

1.8 保留字段

如果是通过删除整个字段更新了消息类型，或者将整个字段其注释掉，未来在编写新的类型的时候能够复用这些注释掉的标识数字。然而，这会引起一些严重的问题，如果后来加载了同一个.proto的旧版，包括数据损坏，安全隐私bug等等。一个确保这种问题不会发生的办法是，保留要删除的字段的标识。Protocol buffer 编译器将会提示以后用户使用这些保留的字段标识。

message Foo {
reserved 2, 15, 9 to 11;
reserved “foo”, “bar”;
}

注意：不要混淆同一个保留语句中的字段名称和标识。

1.9 值类型

值类型的消息字段可以是一下类型中的一种——这个表格展示了可以在.proto文件中使用的类型，以及自动生成的相应语言的类型：

1.10 proto文件编译

一个 .proto 文件的编译之后，编译器会为你选择的语言生成代码。你在文件中描述的消息类型，包括获取和设置字段的值，序列化你的消息到一个输出流，以及从一个输入流中转换出你的消息。

• 对于 C++，编译器会为每个 .proto 文件生成一个 .h 和一个 .cc 的文件，为每一个给出的消息类型生成一个类。
• 对于 Java，编译器会生成一个java文件，其中为每一个消息类型生成一个类，还有特殊的用来创建这些消息类实例的Builder类，
• Python编译器生成一个模块，其中为每一个消息类型生成一个静态的描述器，在运行时，和一个 metaclass 一起使用来创建必要的 Python 数据访问类。
• 对于 Go，编译器为每个消息类型生成一个 .pb.go 文件。

2 gRPC 服务

发送到Etcd服务器的每个API请求都是一个gRPC远程过程调用。Etcd3 中的RPC接口根据功能分类来定义。

• 处理 Etcd 键值的重要服务包括：
• KV 服务，创建，更新，获取和删除键值对。
• 监视，监视键的更改。
• 租约，消耗客户端保持活动消息的基元。
• 锁，etcd 提供分布式共享锁的支持。
• 选举，暴露客户端选举机制。
  

2.1 请求

etcd3 中的所有 RPC 都遵循相同的格式。每个 RPC 都有一个函数名，该函数将 NameRequest 作为参数并返回 NameResponse 作为响应。例如，这是 Range RPC 描述：

service KV {
Range(RangeRequest) returns (RangeResponse)
…
}

2.2 响应

etcd API 的所有响应都有一个附加的响应标头，其中包括响应的集群元数据：

message ResponseHeader {
uint64 cluster_id = 1;
uint64 member_id = 2;
int64 revision = 3;
uint64 raft_term = 4;
}

• Cluster_ID ： 产生响应的集群的 ID。
• Member_ID ：产生响应的成员的 ID。
• Revision ： 产生响应时键值存储的修订版本号。
• Raft_Term ： 产生响应时，成员的 Raft 称谓。

应用服务可以通过 Cluster_ID 和 Member_ID 字段来分辨当前与之通信的正是预期的那个集群或者成员。

应用服务可以使用修订号字段来知悉当前键值存储库最新的修订号。当应用程序指定历史修订版进行查询并希望在请求时知道最新修订版时，此功能特别有用。

应用服务可以使用 Raft_Term 来检测集群何时完成一个新的 leader 选举。

3 键值对服务

3.1 KV service 定义

大多数对Etcd的请求通常是键值请求。KV service提供对键值对操作的支持。在 rpc.proto 文件中 KV service 定义如下：

//rpc.proto
service KV {
rpc Range(RangeRequest) returns (RangeResponse) {}

rpc Put(PutRequest) returns (PutResponse) {}

rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) {}

rpc Txn(TxnRequest) returns (TxnResponse) {}

rpc Compact(CompactionRequest) returns (CompactionResponse) {}
}

各个函数的介绍如下：

• Range：从键值存储中获取范围内的key；
• Put：设定key-value到Etcd键值存储，put 请求增加键值存储的修订版本并在事件历史中生成一个事件；
• DeleteRange：从键值存储中删除给定范围，删除请求增加键值存储的修订版本，并在事件历史中为每个被删除的key生成一个删除事件；
• Txn：在单个事务中处理多个请求，一个 txn请求增加键值存储的修订版本并为每个完成的请求生成带有相同修订版本的事件。不容许在一个txn中多次修改同一个key；
• Compact：压缩在etcd键值存储中的事件历史。键值存储应该定期压缩，否则事件历史会无限制的持续增长。

下面我们具体分析每个接口方法。

3.2 Range方法

Range 方法从键值存储中获取范围内的 key，定义如下：

rpc Range(RangeRequest) returns (RangeResponse) {}

需要注意的是没有操作单个 key 的方法，即使是存取单个 key，也需要使用 Range 方法。

请求的消息体 RangeRequest 如下所示：

message RangeRequest {
enum SortOrder {
NONE = 0; // 默认，不排序
ASCEND = 1; // 正序，低的值在前
DESCEND = 2; // 倒序，高的值在前
}
enum SortTarget {
KEY = 0;
VERSION = 1;
CREATE = 2;
MOD = 3;
VALUE = 4;
}

bytes key = 1;

// range_end 是请求范围的上限[key, range_end)
bytes range_end = 2;

// 请求返回的key的数量限制
int64 limit = 3;

int64 revision = 4;

// 指定返回结果的排序顺序
SortOrder sort_order = 5;

// 用于排序的键值字段
SortTarget sort_target = 6;

bool serializable = 7;

// 设置仅返回key而不需要value
bool keys_only = 8;

// 设置仅仅返回范围内key的数量
bool count_only = 9;
}

1. 在上面定义的请求结构体中，需要注意 key 是 range 的第一个 key【字段】。
2. range_end 如果没有给定，请求仅查找这个 key。range_end 代表请求的上限，如果 range_end 是 ‘\0’，范围是大于等于 key 的所有key；如果 range_end 比给定的 key 长一个 bit，那么 range 请求获取所有带有前缀(给定的 key)的 key；如果 key 和 range_end 都是’\0’，则范围查询返回所有key。
3. revision 修订版本作于 range 键值对存储的时间点。如果 revision 小于或等于零，范围是在最新的键值对存储上。如果修订版本已经被压缩，返回 ErrCompacted 作为应答。
4. serializable 设置 range 请求使用串行化成员本地读。range 请求默认是线性化的，线性化请求相比串行化请求有更高的延迟和低吞吐量，但是反映集群当前的一致性。为了更好的性能，以可能脏读为代价，串行化 range 请求在本地处理，无需和集群中的其他节点达到一致。

应答的消息体 RangeResponse 定义如下：

message RangeResponse {
ResponseHeader header = 1;

// kvs是匹配范围请求的键值对列表
// 当请求数量时是空的
repeated mvccpb.KeyValue kvs = 2;

// more代表在被请求的范围内是否还有更多的 key
bool more = 3;

// 被请求范围内 key 的数量
int64 count = 4;
}

header 就是在前面小结提及的通用响应头。其中 mvccpb.KeyValue 的消息体定义如下：

message KeyValue {
// key 是 bytes 格式的 key。不容许 key 为空
bytes key = 1;

// create_revision 是这个 key 最后创建的修订版本
int64 create_revision = 2;

// mod_revision 是这个 key 最后修改的修订版本
int64 mod_revision = 3;

int64 version = 4;

// value 是 key 持有的值，bytes 格式。
bytes value = 5;

int64 lease = 6;
}

version 是 key 的版本。删除会重置版本为 0，任何 key 的修改会增加它的版本。lease 是附加给 key 的租约 id。当附加的租约过期时，key 将被删除。如果 lease 为 0，则没有租约附加到 key。

3.3 Put 方法

Put 方法，用于存储给定 key-value 到数据库。Put 方法增加键值存储的修订版本并在事件历史中生成一个事件。

rpc Put(PutRequest) returns (PutResponse) {}

请求的消息体是 PutRequest：

message PutRequest {
// byte数组形式的key，用来放置到键值对存储
bytes key = 1;

// byte 数组形式的 value，在键值对存储中和 key 关联
bytes value = 2;

int64 lease = 3;

bool prev_kv = 4;
}

lease，在键值存储中和 key 关联的租约 id，0 代表没有租约。如果 prev_kv 被设置，etcd 获取改变之前的上一个键值对。上一个键值对将在 put 应答中被返回。

应答的消息体 PutResponse 定义如下：

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数Go语言工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则几千的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年Go语言全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Golang知识点，真正体系化！

由于文件比较大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且后续会持续更新

如果你觉得这些内容对你有帮助，可以添加V获取：vip1024b （备注Go）

一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Golang知识点，真正体系化！**

由于文件比较大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且后续会持续更新

如果你觉得这些内容对你有帮助，可以添加V获取：vip1024b （备注Go）
[外链图片转存中…(img-4hhILJpn-1712962961809)]

一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！