31-proto文件结构学习

.proto文件结构学习

基本的文件结构

syntax = "proto3";// 声明版本

option go_package = "hello_client/proto"; // go_package go代码import路径

package hello;// 包声明,client端必须与server端一致

// 定义服务
server HelloServer {
    // rpc: 定义rpc函数  入参：HelloRequest  出参: HelloResponse
    rpc SayHello (HelloRequest) returns (HelloResponse);
}

// 定义消息
message HelloRequest {
    string Name = 1;// 
}

message HelloResponse {
    string Msg = 1;
}

• 1. 字段规则，这里只学习3版本的

optional   可选字段(proto3默认)   string name=1 => optional string name = 1;
repeated   数组/列表              repeated  string tags = 4;
required   必填字段(proto3以移除)

• 2. 数据类型

类型                GO语言类型                说明
string              string                   UTF_*编码
int32               int32                    变长编码,推荐优先使用
double              float64                  双精度浮点数
bool                bool                     布尔值
bytes               []byte                   二进制数据

• 3. 字段编号

1. 必须唯一： 同一个消息(message)内不能重复
2. 1-15：占用一个字节(推荐高频字段)
3. 16-2047: 占用2个字节
4. 即使字段被废弃了: 也要保留编号(避免误用)

// 1. 保留字段编号(数字)
message User {
    // 保留下 2， [15,20] 15到20包含2边
    reserved 2, 15 to 20;
    // string a = 2; 被遗弃的字段保留一下
}

// 保留字段
message User1 {
    reserved "a", "b";// 保留 a b 2个字段
    // string a = 1;
}

// 混合保留字段
message User2 {
    reserved 2, 15 to 20, "a", "b";
}

高级特性

• 1. 嵌套类型

message User {
    message Address {
        string city = 1;
    }
    repeated Address addresses = 2;
}

• 2. 枚举类型

enum UserRole {
    GUEST = 0;// 必须从零开始
    MEMBER = 1;
    ADMIN = 2;
}

• 3. map类型

map<string, int32> scores = 1; //键必须是基础类型

• 4. Oneof 互斥字段
  • 运行时候只能设置其中的一个字段
  • 如: 适合支付方式等互斥场景

oneof auth_method {
    string pwd = 1;
    bytes  token = 2;
}

一个例子写高级特性

syntax = "proto3";

enum Status {
    PENDING = 0;
    PAID = 1;
    SHIPPEND = 2;
}

// 嵌套 + 枚举
message Order {
    message Item = {
        sting sku = 1;
        int32 quantity = 2;
    }

    string order_id = 1;
    repeat Item items = 2;// 嵌套信息作为数组
    Status status = 3;// 枚举字段
}

// 运行时候只能设置其中的一个字段
message Player {
    oneof method {
        string zms = 1;
        string kobe = 2;
        string jd   = 3;
    }
}

可以定义四种类型的服务方法：

• 普通 rpc: Unary RPCs
• 服务端流式 rpc: Server streaming RPCs
• 客户端流式 rpc: Client streaming RPCs
• 双向流式 rpc: Bidirectional streaming RPCs

server ChatService {
    // 简单的 rpc
    rpc SendMessage (Message1) returns (Response1);

    // 服务端流式
    rpc ServerStram (Message2) returnes (stream Response1);

    // 客户端流式
    rpc ClientStram (stream Message2) returnes (Response1);

    // 双向流式
    rpc BindirectStram (stream Message2) returnes (stream Response1);
}