[C++][ProtoBuf][Proto3语法][一]详细讲解

---

1.字段规则

• 消息的字段可以⽤下⾯⼏种规则来修饰：
  • singular：消息中可以包含该字段零次或⼀次(不超过⼀次)
    • proto3语法中，字段默认使⽤该规则
  • repeated：消息中可以包含该字段任意多次(包括零次)，其中重复值的顺序会被保留
    • 可以理解为定义了⼀个数组
• 示例：表示一个通讯录里有多个人的信息

  message Contacts
  {repeated PeopleInfo contacts = 1;
  }
  

---

2.消息类型的定义与使用

1.定义

• 在单个.proto⽂件中可以定义多个消息体，且⽀持定义嵌套类型的消息(任意多层)
  • 每个消息体中的字段编号可以重复
• 更新contacts.proto，可以将phone_number提取出来，单独成为⼀个消息

  // -------------------------- 嵌套写法 -------------------------
  syntax = "proto3";
  package contacts;message PeopleInfo 
  {string name = 1; int32 age = 2; message Phone {string number = 1;}
  }
  // -------------------------- ⾮嵌套写法 ------------------------
  syntax = "proto3";
  package contacts;message Phone 
  {string number = 1;
  }message PeopleInfo 
  {string name = 1; int32 age = 2; 
  }
  

2.使用

• 消息类型可作为字段类型使用

  syntax = "proto3";
  package contacts;// 联系⼈
  message PeopleInfo 
  {string name = 1; int32 age = 2; message Phone {string number = 1; }repeated Phone phone = 3; 
  }
  

• 可导入其他.proto文件的消息并使用：import导入

  syntax = "proto3";
  package contacts;
  import "phone.proto"; // 使⽤ import 将 phone.proto ⽂件导⼊进来message PeopleInfo 
  {string name = 1; int32 age = 2; // 引⼊的⽂件声明了package，使⽤消息时，需要⽤ ‘命名空间.消息类型’ 格式 repeated phone.Phone phone = 3; 
  }
  

• 注意：在proto3⽂件中可以导⼊proto2消息类型并使⽤它们，反之亦然
• 说明：
  • 每个字段都有⼀个clear_⽅法，可以将字段重新设置回empty状态
  • 每个字段都有设置和获取的⽅法， 获取⽅法的⽅法名称与字段命名完全相同
    • 但如果是消息类型的字段，其设置⽅法为mutable_⽅法，返回值为消息类型的指针，这类⽅法会为用户开辟好空间，可以直接对这块空间的内容进⾏修改
      • mutable -> 访问和修改消息字段中的嵌套消息
  • 对于使⽤repeated修饰的字段，也就是数组类型，pb为用户提供：
    • add_⽅法来新增⼀个值
    • _size⽅法来判断数组存放元素的个数

---

3.enum类型

1.语法

• 语法：

  enum Type
  {}
  

• 注意：
  • 0值常量必须存在，且要作为第⼀个元素
    • 这是为了与proto2的语义兼容：第⼀个元素作为默认值，且值为0
  • 枚举类型可以在消息外定义，也可以在消息体内定义(嵌套)
  • 枚举的常量值在32位整数的范围内
    • 负值⽆效，所以不建议使⽤负值

2.定义时注意

• 将两个"具有相同枚举值名称"的枚举类型放在单个.proto⽂件下测试时，编译后会报错：某某某常量已经被定义，所以这⾥要注意：
  • 同级(同层)的枚举类型，各个枚举类型中的常量不能重名

    enum PhoneType 
    {MP = 0;TEL = 1;
    }
    enum PhoneTypeCopy 
    {MP = 0; // ERROR：MP 已经定义	
    }
    

  • 单个.proto⽂件下，最外层枚举类型和嵌套枚举类型，不算同级

    enum PhoneTypeCopy 
    {MP = 0; // ⽤法正确
    }message Phone 
    {string number = 1;enum PhoneType {MP = 0;TEL = 1;}
    }
    

  • 多个.proto⽂件下，若⼀个⽂件引⼊了其他⽂件，且每个⽂件都未声明package，每个proto⽂件中的枚举类型都在最外层，算同级

    // phone1.proto
    import "phone1.proto"
    enum PhoneType 
    {MP = 0; // ERROR：MP 已经定义TEL = 1; 
    }// phone2.proto
    enum PhoneTypeCopy 
    {MP = 0;
    }
    

  • 多个.proto⽂件下，若⼀个⽂件引⼊了其他⽂件，且每个⽂件都声明了package，不算同级

    // phone1.proto
    import "phone1.proto"
    package phone1;
    enum PhoneType 
    {MP = 0; // ⽤法正确TEL = 1;
    }// phone2.proto
    package phone2;
    enum PhoneTypeCopy 
    {MP = 0;
    }
    

3.代码

• 编译生成的CPP代码：

  // 新⽣成的 PeopleInfo_Phone_PhoneType 枚举类
  enum PeopleInfo_Phone_PhoneType : int 
  {PeopleInfo_Phone_PhoneType_MP = 0,PeopleInfo_Phone_PhoneType_TEL = 1,PeopleInfo_Phone_PhoneType_PeopleInfo_Phone_PhoneType_INT_MIN_SENTINEL_DO_NOT_USE_ = std::numeric_limits<int32_t>::min(),PeopleInfo_Phone_PhoneType_PeopleInfo_Phone_PhoneType_INT_MAX_SENTINEL_DO_NOT_USE_ = std::numeric_limits<int32_t>::max()
  };// 更新的 PeopleInfo_Phone 类
  class PeopleInfo_Phone final : public ::PROTOBUF_NAMESPACE_ID::Message 
  {
  public:typedef PeopleInfo_Phone_PhoneType PhoneType;static inline bool PhoneType_IsValid(int value) {return PeopleInfo_Phone_PhoneType_IsValid(value);}template<typename T>static inline const std::string& PhoneType_Name(T enum_t_value) {...}static inline bool PhoneType_Parse(::PROTOBUF_NAMESPACE_ID::ConstStringParam name, PhoneType* value) {...}// .contacts.PeopleInfo.Phone.PhoneType type = 2;void clear_type();::contacts::PeopleInfo_Phone_PhoneType type() const;void set_type(::contacts::PeopleInfo_Phone_PhoneType value);
  };
  

• 上述的代码中
  • 对于在.proto⽂件中定义的枚举类型，编译⽣成的代码中会含有
    • 与之对应的枚举类型
    • 校验枚举值是否有效的⽅法_IsValid
    • 以及获取枚举值名称的⽅法_Name
  • 对于使⽤了枚举类型的字段，包含设置和获取字段的⽅法，已经清空字段的⽅法clear_