Protocol Buffers

Protocol Buffers（Protobuf） 是 gRPC 的 IDL 与序列化格式：用 .proto 定义 message 与 service，编译器生成各语言类型。契约先于实现，适合微服务协作。

学习目标

• 编写 message、enum、service 基本语法
• 理解 field number、optional/repeated 规则
• 为 CodeRoadMap lab 定义 TrackService 契约（不改动 REST DTO）

核心内容

最小 .proto 示例

src/main/proto/track.proto：

syntax = "proto3";

package coderoadmap.track.v1;

option java_package = "com.coderoadmap.track.v1";
option java_multiple_files = true;

message Track {
  string slug = 1;
  string title = 2;
  string level = 3;
}

message GetTrackRequest {
  string slug = 1;
}

message GetTrackResponse {
  Track track = 1;
}

service TrackService {
  rpc GetTrack(GetTrackRequest) returns (GetTrackResponse);
  rpc ListTracks(ListTracksRequest) returns (ListTracksResponse);
}

message ListTracksRequest {}
message ListTracksResponse {
  repeated Track tracks = 1;
}

与 REST GET /tracks/{slug} 语义对齐，但 wire 格式是二进制，浏览器不能直接消费——故生产仍 REST。

语法要点

概念	说明
= 1 field number	wire 标识，不可复用已废弃编号
repeated	列表，等价 JSON 数组
optional	proto3 显式可选字段
package	命名空间，防冲突

.proto 是 单一事实来源；Java 实体（spring-boot-essentials JPA）在 Service 层做映射，勿让 JPA 注解污染 .proto。

与 OpenAPI / GraphQL 对照

• REST：OpenAPI 描述 JSON 形状（本站 /tracks）
• GraphQL：SDL Schema（gql-schema）
• gRPC：.proto + protoc 生成 stub

三者可描述同一 Track，但 CodeRoadMap 权威对外契约是 REST；gRPC .proto 仅 lab 微服务间使用。

练习

• 为 增加 message（、、）