proto 语法

概述

Protocol buffers 是 Google 的语言中立、平台中立、可扩展的结构化数据序列化机制——像 XML，但更小、更快、更简单。您定义了一次数据的结构化方式，然后您可以使用特殊生成的源代码轻松地将结构化数据写入各种数据流并使用各种语言从中读取结构化数据。

proto 语法 - 图1注意

在 go-zero 框架开发中，我们使用 《Language Guide (proto3)》 版本。

快速入门

示例 1. 编写最简单的 rpc 服务

  1. // 声明 proto 语法版本，固定值
  2. syntax = "proto3";
  4. // proto 包名
  5. package greet;
  7. // 生成 golang 代码后的包名
  8. option go_package = "example/proto/greet";
  10. // 定义请求体
  11. message SayHelloReq {}
  12. // 定义响应体
  13. message SayHelloResp {}
  15. // 定义 Greet 服务
  16. service Greet {
  17.   // 定义一个 SayHello 一元 rpc 方法，请求体和响应体必填。
  18.   rpc SayHello(SayHelloReq) returns (SayHelloResp);
  19. }

示例 2. 编写流式请求服务示例

  1. // 声明 proto 语法版本，固定值
  2. syntax = "proto3";
  4. // proto 包名
  5. package greet;
  7. // 生成 golang 代码后的包名
  8. option go_package = "example/proto/greet";
  10. // 定义结构体
  11. message SayHelloReq {}
  13. message SayHelloResp {}
  15. message SendMessageReq{
  16.   string message = 1;
  17. }
  18. message SendMessageResp{
  19.   int32 status = 1;
  20. }
  22. message GetMessageReq{
  23.   int32 id = 1;
  24. }
  25. message GetMessageResp{
  26.   string message = 1;
  27. }
  29. // 定义 Greet 服务
  30. service Greet {
  31.   // 定义客户端流式 rpc
  32.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  33.   // 定义服务端流式 rpc
  34.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResp);
  35.   // 定义双向流式 rpc
  36.   rpc PushMessage(stream SendMessageReq) returns (stream GetMessageResp);
  37. }

示例 3. 编写 rpc 分组示例

rpc 分组主要通过 service 名称来区分。

  1. // 声明 proto 语法版本，固定值
  2. syntax = "proto3";
  4. // proto 包名
  5. package greet;
  7. // 生成 golang 代码后的包名
  8. option go_package = "example/proto/greet";
  10. // 定义结构体
  11. message SendMessageReq{
  12.   string message = 1;
  13. }
  14. message SendMessageResp{
  15.   int32 status = 1;
  16. }
  18. message GetMessageReq{
  19.   int32 id = 1;
  20. }
  21. message GetMessageResp{
  22.   string message = 1;
  23. }
  25. // 定义 Greet 服务
  26. service Greet {
  27.   // 定义客户端流式 rpc
  28.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  29.   // 定义服务端流式 rpc
  30.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResp);
  31.   // 定义双向流式 rpc
  32.   rpc PushMessage(stream SendMessageReq) returns (stream GetMessageResp);
  33. }
  35. // 定义 Greet 服务
  36. service Greet {
  37.   rpc SayHello(SayHelloReq) returns (SayHelloResp);
  38. }
  40. // 定义 Message 服务
  41. service Message {
  42.   // 定义客户端流式 rpc
  43.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  44.   // 定义服务端流式 rpc
  45.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResp);
  46.   // 定义双向流式 rpc
  47.   rpc PushMessage(stream SendMessageReq) returns (stream GetMessageResp);
  48. }

示例 4. message 示例

  1. // 声明 proto 语法版本，固定值
  2. syntax = "proto3";
  4. // proto 包名
  5. package greet;
  7. // 生成 golang 代码后的包名
  8. option go_package = "example/proto/greet";
  10. // 定义枚举
  12. enum Status{
  13.   UNSPECIFIED = 0;
  14.   SUCCESS = 1;
  15.   FAILED = 2;
  16. }
  18. // 定义结构体
  20. message Base{
  21.   int32 code = 1;
  22.   string msg = 2;
  23. }
  25. message SendMessageReq{
  26.   string message = 1;
  27. }
  29. message SendMessage{
  30.   // 使用枚举
  31.   Status status = 1;
  32.   // 数组
  33.   repeated string array = 2;
  34.   // map
  35.   map<string,int32> map = 3;
  36.   // 布尔类型
  37.   bool boolean = 4;
  38.   // 序列号保留
  39.   reserved 5;
  40. }
  42. message SendMessageResp{
  43.   Base base = 1;
  44.   SendMessage data = 2;
  45. }
  47. // 定义 Greet 服务
  48. service Greet {
  49.   // 定义客户端流式 rpc
  50.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  51. }

示例 5. proto 文件引入

假设我们有如下环境：

  1. 工作路径：/usr/local/workspace
  2. base.proto 路径及内容：/usr/local/workspace/base/base.proto
  1. syntax = "proto3";
  3. // proto 包名
  4. package base;
  6. // 生成 golang 代码后的包名
  7. option go_package = "example/proto/base";
  9. message Base{
  10.   int32 code = 1;
  11.   string msg = 2;
  12. }

现在需要新建 /usr/local/workspace/greet/greet.proto 文件，且需要引用 /usr/local/workspace/base/base.proto 文件中的 Base 结构体，我们来看一下简单的引用示例：

  1. // 声明 proto 语法版本，固定值
  2. syntax = "proto3";
  4. // proto 包名
  5. package greet;
  7. // 生成 golang 代码后的包名
  8. option go_package = "example/proto/greet";
  10. import "base/base.proto";
  12. enum Status{
  13.   UNSPECIFIED = 0;
  14.   SUCCESS = 1;
  15.   FAILED = 2;
  16. }
  18. message SendMessageReq{
  19.   string message = 1;
  20. }
  22. message SendMessage{
  23.   // 使用枚举
  24.   Status status = 1;
  25.   // 数组
  26.   repeated string array = 2;
  27.   // map
  28.   map<string,int32> map = 3;
  29.   // 布尔类型
  30.   bool boolean = 4;
  31.   // 序列号保留
  32.   reserved 5;
  33. }
  35. message SendMessageResp{
  36.   base.Base base = 1;
  37.   SendMessage data = 2;
  38. }
  40. // 定义 Greet 服务
  41. service Greet {
  42.   // 定义客户端流式 rpc
  43.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  44. }
proto 语法 - 图2温馨提示

goctl 根据 proto 生成 gRPC 代码时：

  1. service 中的 Message（入参&出参） 必须要在 main proto 文件中，不支持引入的文件
  2. 引入的 Message 只能嵌套在 main proto 中的 Message 中使用
  3. goctl 生成 gRPC 代码时，不会生成被引入的 proto 文件的 Go 代码，需要自行预先生成

参考文献