2. Protocol Buffers 入门：Protobuf 语法基础

Protocol Buffers（简称 Protobuf）是 gRPC 的契约语言，所有服务接口与数据结构都通过 .proto 文件定义。本章从语法基础出发，覆盖 message 定义、字段类型与编号、import 与 package 机制，为后续 gRPC 服务契约审计打下语法根基。

2.1 Protobuf 语法版本与文件结构

每个 .proto 文件必须以 syntax 声明开头，指定使用的 Protobuf 版本。目前主流版本为 proto3，与 gRPC 原生兼容。

syntax = "proto3";

package user.v1;

option go_package = "github.com/example/protos/user/v1;userv1";

import "common/timestamp.proto";

message User {
  string id = 1;
  string name = 2;
  int32 age = 3;
  common.Timestamp created_at = 4;
}

2.2 message 定义与字段类型

message 是 Protobuf 的核心结构体，用于定义序列化数据的字段集合。每个字段由 类型、字段名 和 编号 三部分组成。

message Address {
  string street = 1;
  string city = 2;
  string zip_code = 3;
}

message Employee {
  string employee_id = 1;
  string full_name = 2;
  repeated string phone_numbers = 3;       // 列表
  map<string, string> attributes = 4;      // 映射
  oneof contact {
    string email = 5;
    string mobile = 6;
  }
  Address home_address = 7;                // 嵌套 message
}

2.3 字段编号规则与最佳实践

每个字段必须分配一个唯一的数字编号，用于二进制编码时的字段标识。编号范围与编码效率直接相关。

• 1 ~ 15：占用 1 字节编码，应分配给最频繁使用的字段。
• 16 ~ 2047：占用 2 字节编码，分配给次频繁字段。
• 19000 ~ 19999：保留编号，禁止使用（Protobuf 内部预留）。
• 最大编号：2^29 - 1（536,870,911），但建议不超过 2^16 - 1。

message Product {
  reserved 2, 15, 20 to 30;   // 明确保留已删除字段的编号
  reserved "old_name", "legacy_field";  // 保留已删除字段名

  string product_id = 1;
  string title = 3;           // 编号 2 已被保留，不可复用
  double price = 4;
}

2.4 package 与 import 机制

package 用于避免不同 .proto 文件之间的命名冲突，import 用于引用外部定义的类型。两者共同构成 Protobuf 的模块化体系。

// file: finance/v1/currency.proto
syntax = "proto3";
package finance.v1;

option go_package = "github.com/example/protos/finance/v1;financev1";

message Currency {
  string code = 1;   // e.g., "USD", "CNY"
  string symbol = 2;
}

// file: order/v1/order.proto
syntax = "proto3";
package order.v1;

option go_package = "github.com/example/protos/order/v1;orderv1";

import "finance/v1/currency.proto";

message OrderItem {
  string item_id = 1;
  finance.v1.Currency currency = 2;   // 通过 package 路径引用
  int64 amount_cents = 3;
}

2.5 Protobuf 契约结构总览

下图展示了一个典型 gRPC 项目中 .proto 文件的模块组织与依赖关系：

2.6 审计基线速查表

2.7 常见审计发现与修复