彻底搞懂 etcd 系列文章（六）：etcd 核心 API v3

aoho求索

发布于 2020-07-28 15:38:29

5310

发布于 2020-07-28 15:38:29

文章被收录于专栏：aoho求索aoho求索

0 专辑概述

etcd 是云原生架构中重要的基础组件，由 CNCF 孵化托管。etcd 在微服务和 Kubernates 集群中不仅可以作为服务注册与发现，还可以作为 key-value 存储的中间件。

《彻底搞懂 etcd 系列文章》将会从 etcd 的基本功能实践、API 接口、实现原理、源码分析，以及实现中的踩坑经验等几方面具体展开介绍 etcd。预计会有 20 篇左右的文章，笔者将会每周持续更新，欢迎关注。

1 proto3

etcd v3 的通信基于 gRPC，proto 文件是定义服务端和客户端通讯接口的标准。即客户端该传什么样的参数，服务端该返回什么样子的参数，客户端该怎么调用，是阻塞还是非阻塞，是同步还是异步。在进行核心 API 的学习之前，gRPC 推荐使用 proto3，我们需要对 proto3 的基本语法有初步的了解。proto3 是原有 Protocol Buffer 2(被称为 proto2)的升级版本，删除了一部分特性，优化了对移动设备的支持，另外增加了对android和ios的支持，使得 gRPC 可以顺利的在移动设备上使用。

2 Protocol Buffer 是什么

Protocol buffer 是一个灵活、高效、自动化的结构化数据序列化机制--类似于 xml，但是更小、更快并且更简单。一旦定义好数据如何构造，就可以使用特殊生成的源代码轻松地在各种数据流中使用各种语言编写和读取结构化数据。甚至可以更新之前定义的数据结构而不打破已部署的使用"旧有"格式编译的程序。

2.1 定义消息类型

首先让我们来看一个非常简单的例子。假定我们有这样的需求，我们要定义一个搜索请求消息，每个消息都包含一个查询字符串，和你感兴趣的特定页面编号，以及每个页面的命中个数。

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

文件的第一行指定了你使用的是 proto3 的语法：如果你不指定，protocol buffer 编译器就会认为你使用的是proto2的语法。这个语句必须出现在.proto文件的非空非注释的第一行。
我们看到，搜索请求消息结构中定义指定了三个字段（name/value pairs）。每个字段都有一个名称和类型。

2.2 指定字段类型

在上述例子中，所有的字段都是值类型：两个整形(page_number and result_per_page) 和一个字符串 (query)。然而，你也可以指定你的字段的组合类型，包括枚举和其他消息类型。

2.3 分配标识——tag

消息中的每个字段都有一个唯一的数字标识。这些标识用来在消息的二进制格式中识别你的字段，并且，一旦你的消息投入使用，这些标识就不应该再被修改。

注意，标识是由1到15使用一个字节来编码，包括标识数字和字段类型（你可以在Protocol Buffer 编码中查看更多详细）。

标识16到2047占用两个字节。所以你应该保留1到15，用作出现最频繁的消息类型的标识。记得为将来会继续增加并可能频繁出现的元素留一点儿标识区间，也就是说，不要一下子把1—15全部用完，为将来留一点儿哦。

你可以指定的最小的标识数字是1，最大是228，或者536,870,911。你也不能使用19000 到 19999之间的数字(FieldDescriptor::kFirstReservedNumber through FieldDescriptor::kLastReservedNumber)，因为它们被Protocol Buffers保留使用——如果你在自己的.proto文件中使用了一个保留数字，protocol buffer 编译器将会提示。同样的，你不能使用任何之前保留的标识。

2.4 指定字段规则

消息字段可以是下边中的一种：

singular(单个)：符合语法规则的消息包含零个或者一个这样的字段（最多一个）。
repeated(重复)：一个字段在合法的消息中可以重复出现一定次数（包括零次）。重复出现的值的次序将被保留。在proto3中，重复出现的值类型字段默认采用压缩编码。

2.5 添加更多消息类型

多个消息类型可以定义在一个.proto文件中。这个在你定义多个关联的消息的时候非常有用，——这样，举个例子吧，如果你想定义你的搜索消息类型的响应消息格式，你可以在同一个.proto文件中添加如下的内容：

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

message SearchResponse {
 ...
}

2.6 添加注释

在你的 .proto 文件中添加注释, 使用C/C++-风格的 // 语法，像下边这样：

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.
}

2.7 保留字段

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

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

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

2.8 值类型

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

3 .proto 编译之后会生成什么

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

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