本文是 gRPC企业级实战与面试精讲 的分章阅读版。
syntax = "proto3";
package com.example.order;
option java_multiple_files = true;
option java_outer_classname = "OrderProto";
option java_package = "com.example.order.grpc";
// ==================== 枚举定义 ====================
enum OrderStatus {
ORDER_STATUS_UNSPECIFIED = 0; // proto3枚举必须以0开头
ORDER_STATUS_PENDING = 1;
ORDER_STATUS_PAID = 2;
ORDER_STATUS_SHIPPED = 3;
ORDER_STATUS_CANCELLED = 4;
}
// ==================== 服务定义(四种RPC模式) ====================
service OrderService {
// Unary: 一问一答,最常用
rpc GetOrder(GetOrderRequest) returns (OrderResponse);
// Server Streaming: 服务端持续推送
rpc ListOrders(ListOrdersRequest) returns (stream OrderResponse);
// Client Streaming: 客户端批量上传
rpc UploadOrders(stream CreateOrderRequest) returns (BatchResult);
// Bidirectional Streaming: 双向流
rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}
// ==================== 请求消息 ====================
message GetOrderRequest {
string order_id = 1;
}
message ListOrdersRequest {
string user_id = 1;
int32 page_number = 2; // 分页页码
int32 page_size = 3; // 每页数量
OrderStatus status_filter = 4; // 按状态过滤
}
message CreateOrderRequest {
string user_id = 1;
repeated OrderItem items = 2; // 嵌套消息,repeated=列表
}
message ChatMessage {
string sender = 1;
string content = 2;
int64 timestamp = 3;
}
// ==================== 响应消息 ====================
message OrderResponse {
string order_id = 1;
string user_id = 2;
double amount = 3;
OrderStatus status = 4; // 枚举类型字段
repeated OrderItem items = 5; // 订单明细列表
string remark = 6;
int64 created_at = 7;
reserved 8, 9 to 11; // 已删除字段编号必须保留
reserved "old_field_a", "old_field_b"; // 保留字段名
}
message OrderItem {
string product_id = 1;
string product_name = 2;
int32 quantity = 3;
double unit_price = 4;
}
message BatchResult {
int32 success_count = 1;
int32 fail_count = 2;
repeated string failed_ids = 3;
}
// ==================== oneof示例:支付方式三选一 ====================
message PaymentInfo {
string order_id = 1;
oneof payment_method {
CreditCardPayment credit_card = 2;
AlipayPayment alipay = 3;
WechatPayment wechat = 4;
}
}
message CreditCardPayment {
string card_number = 1;
string cvv = 2;
}
message AlipayPayment {
string account = 1;
}
message WechatPayment {
string open_id = 1;
}
关键设计要点:
java_multiple_files = true:每个message/service生成独立的Java类,而非内部类reserved:已删除字段必须保留编号和名称,防止新代码复用旧编号导致反序列化异常repeated:对应Java的List类型oneof:类似C语言的union,一组字段最多同时设置一个