有打赏功能的网站,免费网站推荐软件,信息产业部网站备案,丽水做企业网站的地方基本映射
1. 基本类型映射
Protobuf 类型JSON 类型示例#xff08;Protobuf → JSON#xff09;说明int32, sint32, uint32数字123直接映射为 JSON 数字#xff0c;范围在 -2^31 到 2^32-1 之间。int64, sint64, uint64字符串9223372036854775807必须用字符串…基本映射
1. 基本类型映射
Protobuf 类型JSON 类型示例Protobuf → JSON说明int32, sint32, uint32数字123直接映射为 JSON 数字范围在 -2^31 到 2^32-1 之间。int64, sint64, uint64字符串9223372036854775807必须用字符串表示避免 JavaScript 等语言中的精度丢失安全范围为 ±2^53-1。float, double数字3.14浮点数直接映射为 JSON 数字。booltrue/falsetrue布尔值直接映射。string字符串helloUTF-8 编码的字符串。bytes字符串Base64SGVsbG8gd29ybGQ二进制数据使用标准 Base64 编码。
2. 枚举类型enum
枚举类型可以映射为两种形式
2.1 数值形式默认
Protobufenum Status { ACTIVE 0; INACTIVE 1; }JSON{ status: 0 } 或 { status: 1 }
2.2 字符串形式需配置
通过设置 json_format 选项可将枚举值映射为字符串
import google/protobuf/descriptor.proto;extend google.protobuf.EnumValueOptions {string json_name 50000;
}enum Status {ACTIVE 0 [(json_name) active];INACTIVE 1 [(json_name) inactive];
}JSON{ status: active } 或 { status: inactive }
3. 消息类型message
Protobufmessage Person {string name 1;int32 age 2;
}JSON{name: Alice,age: 30
}字段命名转换Protobuf 的蛇形命名如 user_name会自动转换为 JSON 的驼峰命名如 userName可通过 json_name 选项自定义。
4. 重复字段repeated
Protobufmessage Person {repeated string hobbies 1;
}JSON{hobbies: [reading, coding]
}5. 映射字段map
Protobufmessage Person {mapstring, string metadata 1;
}JSON{metadata: {role: admin,level: expert}
}6. 特殊类型google.protobuf 包
6.1 Timestamp
Protobufimport google/protobuf/timestamp.proto;message Event {google.protobuf.Timestamp time 1;
}JSONISO 8601 格式的字符串{time: 2023-01-01T12:00:00Z
}6.2 Duration
Protobufimport google/protobuf/duration.proto;message Task {google.protobuf.Duration timeout 1;
}JSON带单位的字符串{timeout: 3600s // 或 1h、1.5h 等
}6.3 Any
用于包装任意 Protobuf 消息
Protobufimport google/protobuf/any.proto;message Response {google.protobuf.Any data 1;
}JSON{data: {type: type.googleapis.com/your.package.MessageType,field1: value1,field2: value2}
}6.4 Struct
动态结构类似 JSON 对象
Protobufimport google/protobuf/struct.proto;message Config {google.protobuf.Struct settings 1;
}JSON直接嵌套 JSON 对象{settings: {debug: true,timeout: 3000}
}7. 空值处理
默认值未设置的字段在 JSON 中可以省略如 int32 默认为 0string 默认为空字符串。显式空值通过 google.protobuf.NullValue 类型表示 nullimport google/protobuf/wrappers.proto;message OptionalField {google.protobuf.StringValue name 1; // 允许 null
}{name: null
}特殊映射
1. 超出 JavaScript 安全范围的数值类型
Protobuf 类型JSON 类型原因int64, sint64字符串范围为 -2^63 到 2^63-1超过 JavaScript 的安全整数范围 ±2^53-1。uint64字符串范围为 0 到 2^64-1同样超出 JavaScript 安全范围。fixed64, sfixed64字符串64 位固定宽度整数也会被转为字符串。
2. 二进制类型
Protobuf 类型JSON 类型原因bytes字符串Base64JSON 无法直接表示二进制数据需通过 Base64 编码转换为字符串。
3. Google Protobuf 标准类型
Protobuf 类型JSON 类型示例格式google.protobuf.Timestamp字符串2023-01-01T12:00:00ZISO 8601 格式google.protobuf.Duration字符串3600s、1.5h、5m30s带单位的字符串google.protobuf.Any对象{ type: ..., field: value }包含类型信息google.protobuf.Struct对象直接映射为 JSON 对象用于动态结构google.protobuf.Value任意类型根据实际值类型如 { numberValue: 123 }google.protobuf.ListValue数组JSON 数组用于动态列表
4. 其他特殊情况
4.1 枚举类型
默认映射为 数值如 { status: 1 }。可通过 json_name 选项配置为 字符串如 { status: ACTIVE }。
4.2 空值Null
使用 google.protobuf.NullValue 表示 null{optionalField: null
}4.3 浮点特殊值
NaN、Infinity、-Infinity 在 JSON 中通常用字符串表示如 NaN但具体实现可能因语言而异。
为什么这些类型需要特殊处理
跨语言兼容性JavaScript、Python 等语言的数值类型范围与 Protobuf 不匹配需要通过字符串避免精度丢失。格式标准化时间、持续时间等类型通过固定格式如 ISO 8601确保不同系统间正确解析。类型信息保留Any 类型需要在 JSON 中保留原始消息的类型信息通过 type 字段。
总结
gRPC 的 JSON 映射规则在保持 Protobuf 强类型特性的同时通过特殊转换确保与 JSON 弱类型系统的兼容性。这些规则是跨平台 API 开发的基础特别是在处理跨语言数据交换时尤为重要。
