Protobuf 与服务定义
在 proto 中描述您的 API。
Protobuf 与服务定义 是 CoddyKit 上的免费 Learn Rust Coding 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Learn Rust Coding 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Learn Rust Coding 课程共包含 4 节课。
为什么使用 gRPC 和 Protobuf
gRPC 是构建在 HTTP/2 和协议缓冲区之上的高性能 RPC 框架。在 Rust 中，tonic crate 端到端地实现了 gRPC。
Protobuf 是接口定义语言（IDL）。您只需在一个 .proto 文件中描述消息和服务，代码生成器就会生成强类型的客户端和服务器存根。
.proto 文件的结构
每个 proto 文件都会声明语法版本和包。包可以为生成的类型划分命名空间，并避免名称冲突。
请在 tonic 中使用 proto3。生成后，包名称会映射为 Rust 模块路径。
syntax = "proto3";
package greeter.v1;定义消息
消息是一条有类型的记录。每个字段都有类型、名称，以及用于线路编码的唯一字段编号。
字段编号必须保持稳定：一旦数据存在，就绝不要重用或重新编号字段，否则会破坏兼容性。
message HelloRequest {
string name = 1;
int32 age = 2;
}标量类型与 Rust 映射
Protobuf 标量类型会通过 prost 映射为 Rust 类型。string 变为 String，int32 变为 i32，bool 变为 bool，而 bytes 变为 Vec<u8>。
在 proto3 中，每个标量都有默认值（空字符串、0、false）；除非特别标记，否则它们不是可选的。
message Metric {
string label = 1;
double value = 2;
bool active = 3;
}定义服务
service 会将 RPC 方法归为一组。每个 rpc 都声明方法名称、请求消息和响应消息。
tonic 会根据这个代码块生成服务器 trait 和客户端结构体。实现该 trait 就是提供行为的方式。
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloReply {
string message = 1;
}四种 RPC 方法类型
gRPC 支持四种流式形式：一元、服务器流式、客户端流式和双向流式。
在请求端、响应端或两端使用 stream 关键字，即可表示流。
service Chat {
rpc Unary (Msg) returns (Msg);
rpc ServerStream (Msg) returns (stream Msg);
rpc ClientStream (stream Msg) returns (Msg);
rpc BiDi (stream Msg) returns (stream Msg);
}Protobuf 中的枚举
枚举以整数作为底层表示。在 proto3 中，第一个值必须编号为 0，并作为默认值。
prost 会生成 Rust 枚举及其辅助函数，用于从底层 i32 转换而来，因为线路上传输的可能是未知值。
enum Status {
STATUS_UNKNOWN = 0;
STATUS_ACTIVE = 1;
STATUS_BANNED = 2;
}嵌套字段与重复字段
repeated 字段表示列表，在 Rust 中映射为 Vec<T>。消息可以嵌套，也可以通过名称引用。
这样，您无需额外的繁琐代码，就能对集合和复合负载进行建模。
message Order {
string id = 1;
repeated Item items = 2;
}
message Item {
string sku = 1;
int32 qty = 2;
}空类型与众所周知的类型
对于不接收或不返回任何内容的方法，请导入 google/protobuf/empty.proto 并使用 Empty。
其他众所周知的类型包括 Timestamp 和 Duration。tonic 自带这些定义，因此您可以在构建中导入它们。
import "google/protobuf/empty.proto";
service Health {
rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}使用包进行版本控制
将版本放入包中，例如 greeter.v1，可以让您安全地演进 API。破坏性变更可以放入 greeter.v2，同时继续提供 v1 服务。
这一约定能让生成的 Rust 模块保持整洁：greeter::v1 和 greeter::v2 可以共存。
package greeter.v1;
// later, a parallel file:
// package greeter.v2;字段兼容性规则
使用新的编号添加字段具有向后兼容性；旧客户端会忽略它。除非使用 reserve 保留字段编号和名称，否则删除字段存在风险。
保留操作可以防止他人重用已废弃的字段编号并破坏解码。
message User {
reserved 3, 5;
reserved "legacy_token";
string id = 1;
string email = 2;
}快速检查
检验您对 proto3 服务定义的理解。
回顾
您已经在 proto3 中定义了服务和消息：稳定的字段编号、标量到 Rust 的映射、枚举、重复字段和嵌套字段、四种 RPC 形式、众所周知的类型，以及通过包实现的版本控制。
接下来，您将使用 tonic-build 将这些定义转换为 Rust 代码。
用 AI 导师学习 Rust — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 39
- 课程
- 144
常见问题解答
「Protobuf 与服务定义」课时是免费的吗？
是的 — 「Protobuf 与服务定义」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Learn Rust Coding 课程的其余内容，请升级到 CoddyKit PRO。 Learn Rust Coding 课程共包含 4 节课。
「Protobuf 与服务定义」这节课中我会学到什么？
在 proto 中描述您的 API。 你通过在浏览器中直接运行的动手代码来练习 Learn Rust Coding，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Learn Rust Coding 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Learn Rust Coding 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。
「Protobuf 与服务定义」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Learn Rust Coding 课中编写并运行代码吗？
能。每节 Learn Rust Coding 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- Protobuf 与服务定义
- 使用 tonic-build 生成代码
- 实现 gRPC 服务器
- 从 gRPC 客户端调用