proto3语法记录

protobuf 是谷歌的语言无关，平台无关，可扩展的，高效的结构化数据序列化机制，比xml和json的序列化的速度更快，此处记录一下 proto3 的语法，防止以后忘记。

注意：proto3 语法需要注意的事项，见下方代码中的注释

syntax = "proto3"; // 定义这个文件的语法是proto3、默认情况下是proto2 这个指定语法行必须是文件的非空非注释的第一个行。

// 申明一个包
package com.huan.proto;
option java_package = "com.huan.proto"; // 申明一个在 java 中使用的包，如果没有申明这个，则使用外层的 package 申明
option java_outer_classname = "PersonWrapper"; // 表示最后生成java的类名

// 定义一个消息体
// 1、下方每个字段后后面都有一个唯一的标识符，1,2,3,4....，这些标识符是用来在消息的二进制的识别各个字段的，一段开始使用就不可再次改变。
// 2、其中[1,15]的标识符在编码的时候会占一个字节，[16,2047]的标识符会占2个字节，因此我们应该为常用的字段的标识符在[1,15]之内。[19000－19999]为预留的标识符不可使用
// 默认值
// 1、对于strings，默认是一个空string
// 2、对于bytes，默认是一个空的bytes
// 3、对于bools，默认是false
// 4、对于数值类型，默认是0
// 5、对于枚举，默认是第一个定义的枚举值，必须为0;
// 6、对于消息类型（message），域没有被设置，确切的消息是根据语言确定的，

message Person {
    // 对应 java 中的 String 数据类型
    string personName = 1;
    // 对应 java 中的 int 数据类型
    int32 age = 2;
    // 对应 java 中的 double 数据类型
    double salary = 3;
    // 对应 java 中的 float 数据类型
    float weight = 4;
    // 对应 java 中的 boolean 数据类型
    bool isMarry = 5;
    // 对应 java 中的 long 数据类型
    sint64 createTime = 6;
    // 对应 java 中的 byte 数据类型
    bytes content = 7;
    // 对应 java 中的 枚举 数据类型
    SexEnum sex = 8;
    // 对应 java 中的 List 集合
    repeated string friends = 9;
    // 对应 java 中的 map 类型 [deprecated = true]表示这个字段已经被废弃了
    map<string, string> ext = 10 [deprecated = true];

    // 定义一个枚举,不建议在枚举中使用负数，因为枚举值是采用可变编码方式的。
    enum SexEnum {
        option allow_alias = true; // 当打开这个配置时，可以实现将不同的枚举常量指定为相同的值，比如下方的 WOMEN和NOT_KONWN
        MAN = 0; // 在枚举中，第一个值必须是 0
        WOMEN = 1;
        NOT_KNOWN = 1;
    }

    // oneof 表示的字段中，表示只有一个字段有值，那么在此处OnlyOneFieldHasValue下的三个字段同一时刻，只有一个字段有值，如果多次赋值，那么后面的值会覆盖前面的值
    oneof OnlyOneFieldHasValue {
        string username = 11;
        Person person = 12;
        SexEnum personSex = 13;
    }

    // reserved 标识的为保留字段，标识不可用，比如前期使用了数字 10，但是现在删除了，后期别人不知道又使用了数字10，那么这个时候是有问题的，应该预留出来，表示不可用
    reserved 30, 20, 21;
    reserved "could not use field", "myFirends";
}

// 定义一个查询的消息体
message SearchRequest {
    string username = 1;
}

// 定义一个RPC服务
service PersonService {

    // 定义rpc方法
    rpc findPerson1 (SearchRequest) returns (Person);
    rpc findPerson2 (stream SearchRequest) returns (Person);
    rpc findPerson3 (SearchRequest) returns (stream Person);
    rpc findPerson4 (stream SearchRequest) returns (stream Person);
}

// 有了以上 proto 文件，如何生成对应的 java 代码
// protoc --proto_path=import_path_dir --java_out=java_file_out_put_dir path/to/dest_proto_file.proto
// proto_path:表示使用了 import 后，import 的 proto文件所在的目录。如果忽略该值，那么默认是当前目录，如果存在多个目录可以多次使用 --proto_path
// java_out:表示在这个目录中生成java代码
// path/to/dest_proto_file.proto:表示我们需要生成的proto文件所在的位置

有了以上proto文件，那么如何生成 java 代码呢？

语法：protoc --proto_path=为import命令时proto文件所在的路径，如果存在多个，可以写多个--proto_path  --java_out=表示生成的java文件的路径  然后接需要生成proto文件的路径。

举例：

需要引入的jar包依赖：

<dependency>
      <groupId>com.google.protobuf</groupId>
      <artifactId>protobuf-java</artifactId>
      <version>3.6.1</version>
</dependency>

proto编译器下载地址：

https://github.com/protocolbuffers/protobuf/releases/tag/v3.6.1