4. gRPC 错误模型：状态码、错误详情与自定义错误

在分布式系统中，错误不仅仅是“成功”或“失败”的二元结果。gRPC 定义了一套结构化的错误模型，将错误从简单的整数码升级为携带丰富上下文的协议级对象。理解这套模型，是构建可观测、可调试的中间件事务边界的基础。

4.1 gRPC 状态码（Status Code）详解

gRPC 状态码是错误模型的顶层标识，每个 RPC 调用最终都会落在一个状态码上。与 HTTP 状态码不同，gRPC 状态码数量少、语义精确，专为远程过程调用设计。

4.2 错误详情（Error Details）结构

仅有状态码远远不够。gRPC 在 google.rpc.Status 消息中定义了标准化的错误详情结构，允许服务端返回结构化的错误上下文，而不仅仅是“错误消息字符串”。

// google/rpc/status.proto
message Status {
  int32 code = 1;               // gRPC 状态码数值
  string message = 2;           // 人类可读的错误描述
  repeated google.protobuf.Any details = 3; // 可扩展的错误详情列表
}

details 字段使用 google.protobuf.Any 类型，可以携带任意 protobuf 消息。Google 预定义了一组标准错误详情类型，覆盖了最常见的错误场景：

4.3 自定义错误信息

当标准错误详情无法满足业务需求时，gRPC 允许服务端在 details 中嵌入自定义 protobuf 消息。这是中间件扩展错误语义的核心能力。

4.3.1 定义自定义错误消息

// 自定义错误详情 proto
syntax = "proto3";
package transaction;

message TransactionError {
  string transaction_id = 1;
  string failed_step = 2;
  int32 retry_attempt = 3;
  map<string, string> context = 4;
}

4.3.2 服务端返回自定义错误

// Java 示例：在 gRPC 拦截器中附加自定义错误详情
Status status = Status.ABORTED.withDescription("事务冲突，步骤2失败");
TransactionError detail = TransactionError.newBuilder()
    .setTransactionId("txn-2024-001")
    .setFailedStep("deduct_balance")
    .setRetryAttempt(2)
    .putContext("account_id", "acc-12345")
    .build();

// 将自定义消息包装为 google.protobuf.Any
Any anyDetail = Any.pack(detail);
responseObserver.onError(status.asRuntimeException(anyDetail));

4.3.3 客户端解析自定义错误

// Java 客户端解析
try {
    stub.someRpcCall(request);
} catch (StatusRuntimeException e) {
    Status status = e.getStatus();
    if (status.getCode() == Status.Code.ABORTED) {
        for (Any detail : status.getDetails()) {
            if (detail.is(TransactionError.class)) {
                TransactionError txnErr = detail.unpack(TransactionError.class);
                System.out.println("事务ID: " + txnErr.getTransactionId());
                System.out.println("失败步骤: " + txnErr.getFailedStep());
                System.out.println("重试次数: " + txnErr.getRetryAttempt());
            }
        }
    }
}

4.4 错误模型在中间件中的完整流程

下图展示了 gRPC 错误模型从服务端产生到客户端消费的完整链路，以及中间件如何介入每个环节：

4.5 错误模型与事务边界的映射策略

在事务边界中间件中，不同的错误类型对应不同的处理策略。下表总结了常见映射关系：