CoderTools

Protocol Buffers 工具

编码、解码和验证 Protocol Buffers 消息

Proto 模式

示例模式:

输入

解析模式并选择消息类型以生成表单字段

输出

Protocol Buffers 文档

什么是 Protocol Buffers？

Protocol Buffers（Protobuf）是由 Google 开发的一种语言无关、平台无关的可扩展序列化结构化数据机制。在数据序列化方面，它比 XML 和 JSON 更小、更快、更简单。

主要特性

  • 语言无关、平台无关
  • 比 XML/JSON 更小更快
  • 通过模式定义实现强类型
  • 向前和向后兼容
  • 自动代码生成
  • 高效的二进制编码

如何使用此工具

  1. 在模式编辑器中输入您的 .proto 模式定义
  2. 点击【解析模式】来验证和解析模式
  3. 选择您要操作的消息类型
  4. 编码时：输入 JSON 数据，点击【编码】
  5. 解码时：输入二进制数据，点击【解码】
  6. 使用【原始解码】在没有模式的情况下分析二进制数据

工具功能

编码

将 JSON 数据转换为 Protocol Buffers 二进制格式。支持基于表单的输入，便于数据录入和类型验证。

解码

将 Protocol Buffers 二进制数据转换回可读的 JSON 格式。支持 Base64、十六进制和 C 风格十六进制输入格式。

原始解码

无需模式即可分析 protobuf 二进制数据。适用于调试、逆向工程或分析未知消息。

表单输入

友好的表单界面，根据您的模式自动生成输入表单。支持嵌套消息、枚举和重复字段。

Proto 语法参考

Protocol Buffers 使用简单的语法来定义消息类型：

syntax = "proto3";

message Person {
    string name = 1;
    int32 id = 2;
    string email = 3;
    
    enum PhoneType {
        MOBILE = 0;
        HOME = 1;
        WORK = 2;
    }
    
    message PhoneNumber {
        string number = 1;
        PhoneType type = 2;
    }
    
    repeated PhoneNumber phones = 4;
}
  • syntax: 指定 protobuf 版本（proto2 或 proto3）
  • message: 定义包含字段的消息类型
  • field: 每个字段都有类型、名称和唯一编号
  • enum: 定义枚举类型
  • repeated: 将字段标记为重复（数组/列表）
  • optional: 将字段标记为可选（proto3）

标量类型

Protocol Buffers 支持多种标量类型：

类型 描述 默认值
int32, int64有符号整数（变长编码）0
uint32, uint64无符号整数0
sint32, sint64使用 ZigZag 编码的有符号整数（对负数高效）0
fixed32, fixed64固定宽度无符号整数（4 或 8 字节）0
sfixed32, sfixed64固定宽度有符号整数（4 或 8 字节）0
float, double浮点数（32 或 64 位）0.0
bool布尔值（true/false）false
stringUTF-8 编码的文本字符串""
bytes任意二进制数据empty

线类型

Protobuf 使用线类型来确定如何从二进制数据中读取值：

线类型 含义 适用类型
0Varintint32, int64, uint32, uint64, sint32, sint64, bool, enum
164-bitfixed64, sfixed64, double
2Length-delimitedstring, bytes, embedded messages, packed repeated
532-bitfixed32, sfixed32, float

最佳实践

  • 新项目使用 proto3 语法 - 更简单且支持更广泛
  • 保持字段编号稳定 - 永远不要重用或更改现有字段的编号
  • 使用有意义的字段名称来清楚描述数据
  • 为常用字段保留编号 1-15（它们只使用 1 个字节）
  • 使用 'repeated' 关键字表示数组/列表
  • 为具有固定可能值集合的字段定义枚举

常见问题解答

proto2 和 proto3 有什么区别？

Proto3 简化了语法，移除了必需字段 - 所有字段默认为可选。它还更改了默认值并移除了标量类型的字段存在检测。新项目推荐使用 Proto3。

我可以在没有模式的情况下解码 protobuf 吗？

可以！使用【原始解码】功能在没有模式的情况下分析二进制数据。字段名称将显示为编号（field_1、field_2 等），某些类型信息可能不明确。

为什么我的编码数据与预期不同？

Protobuf 编码是确定性的，但默认值（0、false、空字符串）在 proto3 中通常不会被编码以节省空间。此外，JSON 中的字段顺序不影响二进制编码。

如何处理嵌套消息？

在模式中定义嵌套消息并使用嵌套的 JSON 对象。在表单模式下，点击嵌套字段按钮可打开对话框编辑嵌套数据。

常见用例

  • 微服务间通信（gRPC）
  • 数据存储和缓存
  • 配置文件
  • 网络协议和 API

参考资料