Proto3 约定

定义消息与服务

以下仅示意 Proto 结构，package 与 go_package 应替换为应用实际路径：

syntax = "proto3";
package example.v1;
option go_package = "example.com/project/api/example/v1;examplev1";

message GetBookRequest {
  string name = 1;
}
message Book {
  string name = 1;
  string title = 2;
}
service Books {
  rpc GetBook(GetBookRequest) returns (Book);
}

RPC 的完整 selector 由 package、服务名和方法名构成，例如 example.v1.Books.GetBook；Gateway/OpenAPI 配置必须使用相同 selector。

字段与兼容

字段编号是二进制协议的一部分，上线后不重新编号，也不复用已删除字段的编号。删除字段时同时保留编号与名称：

message Book {
  reserved 3;
  reserved "legacy_title";
  string name = 1;
  string title = 2;
}

保留名称用于避免后续误复用，并不意味着删除字段后所有历史 JSON 都继续被接受。新增字段也需核对 HTTP JSON、校验规则和旧客户端行为；二进制兼容不等于业务语义兼容。

需要区分未设置和零值时明确设计字段 presence；不要用“空字符串一定表示未传”作为更新协议。枚举首项采用 0 的 UNSPECIFIED/UNKNOWN 语义，处理未知枚举值。跨语言调用时验证 int64 JSON、时间与 bytes 编码，不照搬 Go 原生 JSON 行为。

生成与评审

通过协议与生成流程更新生成文件。评审同时覆盖字段编号、HTTP 映射、错误状态、权限和兼容测试。详细语法见 Proto3 官方指南；本页不是完整语言手册。