RemoteCallException 是 RPC 调用失败的顶层异常，应按“可识别、可分类、可追溯、可恢复”设计，采用三层继承结构，注入 traceId 等元数据，兼容序列化与跨语言传输，并在客户端拦截器中统一转换、封装与熔断处理。
RemoteCallException 是 RPC 调用失败时的顶层异常，自定义设计时应聚焦于“可识别、可分类、可追溯、可恢复”四个核心目标，而不是简单包装 RuntimeException。
明确异常分层与继承关系
不要让所有远程异常都直接继承 Exception 或 RuntimeException。推荐采用三层结构：
- RemoteCallException：抽象基类，继承 RuntimeException（RPC 多数场景不强制捕获），含通用字段如 traceId、service、method、timestamp、errorCode
- RemoteTimeoutException、RemoteNetworkException、RemoteServerException：按失败原因细分的子类，便于监控告警和熔断策略识别
-
业务语义异常（如 UserNotFoundException）：这类属于远程服务返回的“业务错误”，应通过统一错误码 + 错误信息反序列化，不作为 RemoteCallException 的子类，而应封装在 Result
或自定义响应体中
携带关键上下文信息
构造异常时必须注入调用链路元数据，否则无法定位问题：
- traceId（来自 MDC 或 OpenTracing 上下文）
- 被调用服务名（如 "user-service"）、接口名（如 "UserService::getById"）
- 原始错误码（如 Dubbo 的 CODE_TIMEOUT、gRPC 的 Status.Code.DEADLINE_EXCEEDED）
- 可选：序列化后的原始响应头或 error detail（用于调试，生产环境可开关）
示例构造方式：
立即学习“Java免费学习笔记（深入）”；
throw new RemoteTimeoutException(
"timeout calling user-service/UserService::getById",
traceId,
"user-service",
"UserService::getById",
5000L
);
兼容序列化与跨语言传输
RPC 框架（如 Dubbo、gRPC、Spring Cloud OpenFeign）常需将异常序列化后透传。注意：
- 避免在异常字段中存放不可序列化对象（如 ThreadLocal、Connection）
- 所有字段声明为
transient或使用serialVersionUID显式控制版本 - 若使用 Protobuf/gRPC，建议将错误信息建模为标准 ErrorDetail message，而非 Java 异常类本身
- 对 Spring Cloud，可通过
@ResponseStatus或全局@ControllerAdvice将 RemoteCallException 映射为 HTTP 状态码，但不要依赖它做 RPC 内部异常传递
客户端统一拦截与降级处理
异常设计要服务于容错逻辑。建议在 RPC 客户端拦截器中完成三件事：
- 捕获底层通信异常（SocketTimeout、ConnectException），转换为对应 RemoteCallException 子类
- 解析远程服务返回的业务错误响应（如 JSON 中的 code=404），封装为非异常形式的 Result
，不抛出 RemoteCallException - 记录日志并触发熔断器（如 Sentinel 或 Resilience4j）统计，依据异常类型差异化计数（例如只对 RemoteNetworkException 触发熔断）
