gRPC 与 Protocol Buffers 在跨语言服务间的工程实践

微服务拆到一定规模，跨语言调用一定会出现：Go 写的网关要调 Python 的推荐服务，Java 的风控又要被 Node 的 BFF 调用。HTTP + JSON 在这种场景下会暴露三类问题：契约漂移、类型丢失、序列化开销。gRPC 用 IDL 强约束契约、用 Protobuf 二进制编码消除前三者，但它不是免费的午餐。本文给出可落地的工程约定与踩坑清单。

一、Protobuf 字段的兼容纪律

Protobuf 的向后兼容建立在"字段编号"而非"字段名"上。三条纪律：

1. 字段编号一旦上线永不复用，删除字段用 reserved 占位；
2. 新增字段必须是 optional 语义（proto3 默认即为可选），且服务端要有零值兜底逻辑；
3. 不要用枚举值 0 表示业务有效状态，0 是未设置的默认值。

syntax = "proto3";
package order.v1;

message Order {
  reserved 4, 7;
  reserved "coupon_id", "legacy_status";

  string order_no = 1;
  int64  user_id  = 2;
  repeated OrderItem items = 3;
  OrderStatus status = 5;
  optional string remark = 6;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_CREATED = 1;
  ORDER_STATUS_PAID = 2;
}

optional 关键字（proto3.15+）的意义在于区分"未传"与"传了零值"，做部分更新接口时几乎是必需的。

二、Go 服务端的标准骨架

type OrderServer struct {
	pb.UnimplementedOrderServiceServer
	repo OrderRepo
}

func (s *OrderServer) GetOrder(ctx context.Context, req *pb.GetOrderRequest) (*pb.Order, error) {
	o, err := s.repo.Find(ctx, req.GetOrderNo())
	if errors.Is(err, sql.ErrNoRows) {
		return nil, status.Errorf(codes.NotFound, "order %s not found", req.GetOrderNo())
	}
	if err != nil {
		return nil, status.Errorf(codes.Internal, "load order: %v", err)
	}
	return toProto(o), nil
}

关键约定：业务错误必须映射到 gRPC codes，而不是把 error 字符串塞进 Internal。客户端靠 codes.NotFound 决定是否重试，靠 codes.InvalidArgument 决定要不要弹窗。

服务端选项里两个参数最容易被忽略：

grpc.NewServer(
	grpc.MaxRecvMsgSize(16 << 20),
	grpc.KeepaliveParams(keepalive.ServerParameters{
		Time:    2 * time.Minute,
		Timeout: 20 * time.Second,
	}),
	grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
		MinTime:             1 * time.Minute,
		PermitWithoutStream: true,
	}),
)

不设 keepalive，服务经过 LB 或 NAT 时空闲连接会被静默掐断，表现为偶发 transport is closing。

三、Metadata 与拦截器：把横切关注点抽出

鉴权、trace 透传、请求 ID 一律走 metadata + 拦截器，不要污染业务方法签名。

func ServerAuth(ctx context.Context) (context.Context, error) {
	md, ok := metadata.FromIncomingContext(ctx)
	if !ok {
		return ctx, status.Error(codes.Unauthenticated, "missing metadata")
	}
	tok := md.Get("authorization")
	if len(tok) == 0 {
		return ctx, status.Error(codes.Unauthenticated, "missing token")
	}
	claims, err := Verify(tok[0])
	if err != nil {
		return ctx, status.Error(codes.PermissionDenied, err.Error())
	}
	return WithClaims(ctx, claims), nil
}

一元拦截器与流拦截器要成对写，很多人只注册了 unary，流式接口直接裸奔。

四、超时、重试与 deadline 传播

gRPC 最重要的心智模型是 deadline 随调用链传播。客户端设置的 timeout 会通过 grpc-timeout header 传到下游，剩余时间被各服务共享。

工程做法：入口设总预算，每跳按比例收敛。

func CallRecommend(ctx context.Context, req *pb.Req) (*pb.Resp, error) {
	if dl, ok := ctx.Deadline(); !ok {
		var cancel context.CancelFunc
		ctx, cancel = context.WithTimeout(ctx, 300*time.Millisecond)
		defer cancel()
	} else {
		var cancel context.CancelFunc
		ctx, cancel = context.WithTimeout(ctx, time.Until(dl)/2)
		defer cancel()
	}
	return client.Recommend(ctx, req)
}

重试只在幂等方法上开，用 service config 声明而不是自己写循环：

{
  "methodConfig": [{
    "name": [{"service": "order.v1.OrderService"}],
    "retryPolicy": {
      "maxAttempts": 3,
      "initialBackoff": "0.1s",
      "maxBackoff": "1s",
      "backoffMultiplier": 2,
      "retryableStatusCodes": ["UNAVAILABLE"]
    }
  }]
}

五、常见坑清单

| 现象 | 根因 | 处理 | |---|---|---| | 偶发 Unavailable: transport is closing | LB 空闲断连 | 配 keepalive 双侧 | | 大列表接口报 received message larger than max | 默认 4MB 上限 | 分页，或调 MaxRecvMsgSize | | 客户端超时但服务端日志显示成功 | deadline 传播，下游继续跑 | 服务端每步检查 ctx.Err() | | 字段改了但不生效 | 生成码未重新生成 | Makefile 里 codegen 作为 build 前置 | | 网关转 gRPC 后 header 丢失 | grpc-gateway 未注册 metadata 白名单 | metadata.NewIncomingContextMatcher |

小结

gRPC 的收益来自契约前置与二进制编码，成本是链路调试门槛升高。落地的关键是三件事：Protobuf 字段编号纪律、错误映射到标准 codes、deadline 全链传播。把这四点写进团队规范，跨语言调用会比 JSON 时代稳定得多。配套建议：接 grpcurl + reflection 服务，调试体验能追平 curl。