语言指南 (proto 3) | Protocol Buffers 文档 - ProtoBuf 文档

简介

语言指南 (proto 3) 是 Protocol Buffers（ProtoBuf）官方文档中的一部分，地址为 https://protobuf.com.cn/programming-guides/proto3/。本指南介绍了如何在项目中使用 Protocol Buffers 语言的 proto3 版本，主要讲解如何使用协议缓冲区语言构建协议缓冲区数据，包括 .proto 文件语法，以及如何从 .proto 文件生成数据访问类。它是一份参考指南，涵盖了协议缓冲区语言的 proto3 版本；若需通过分步示例了解相关功能，可参阅所选语言的教程。

主要内容

定义消息类型

以搜索请求消息格式为例，需要在 .proto 文件首行指定使用 proto3 版本（syntax = "proto3";），且 edition 或 syntax 必须是文件的第一个非空、非注释行。消息定义中包含若干字段，每个字段有名称和类型。

指定字段类型

字段可以是标量类型（如整数、字符串），也可以是指定的枚举和复合类型（如其他消息类型）。

分配字段编号

• 每个字段编号须在 1 到 536,870,911 之间，且在消息内唯一。
• 编号 19,000 到 19,999 为实现保留，不能使用。
• 编号一旦使用不可更改，否则等同于删除并新建字段。
• 建议使用 1 到 15 的编号给最常设置的字段以节省线路空间。
• 字段编号不可重用，重用会导致解码歧义、数据损坏等后果。

指定字段基数

proto3 中消息字段可为：

• 单一（Singular）：包括 optional（推荐，可显式检查是否设置）和隐式（不推荐，非消息类型无法区分默认值是否设置）。
• repeated：可重复零次或多次，顺序保留；标量数字类型默认使用 packed 编码。
• map：键值对字段类型。
  消息类型字段本身已存在字段，加 optional 不改变其行为。

添加更多消息类型与注释

可在单个 .proto 文件中定义多个消息类型，但建议每个文件包含尽量少类型以避免依赖臃肿。注释支持 // 行尾注释与 /* ... */ 多行注释。

删除字段

删除字段须保留其编号与名称，将删除的字段编号和名称加入 reserved 列表，防止未来重用导致严重问题。

从 .proto 文件生成代码

运行 protocol buffer 编译器后，会按所选语言生成代码：

• C++：生成 .h 和 .cc 文件，每种消息类型对应一个类。
• Java：生成 .java 文件，含消息类与 Builder 类。
• Kotlin：额外生成 .kt 文件，提供 DSL、可空访问器等改进 API。
• Python：生成模块与静态描述符，配合元类使用。

其他涵盖主题

指南还包含标量值类型、字段默认值、枚举（含前缀、默认值、别名、保留值）、使用其他消息类型与导入、嵌套类型、更新消息类型（线路安全/非安全变更）、未知字段、Any、Oneof、映射、包（Packages）、定义服务、JSON 映射、选项（枚举值选项、自定义选项、保留等）以及生成类相关说明。

适用场景

本指南适用于需要在项目中采用 Protocol Buffers proto3 语法定义结构化数据、编写 .proto 文件并生成多语言数据访问类的开发者，可作为 proto3 语言语法与最佳实践的规范参考。