RPC调用失败时应设计分层可序列化异常：RemoteCallException为基类，按超时、网络、服务端错误细分子类，业务错误走Result<T>返回；构造时固化traceId、服务名、方法名、协议错误码等元数据，确保日志、监控、链路、熔断精准协同。
RPC 调用失败时，自定义异常不能只包装错误消息，而要承载可识别的分类、可追溯的上下文、可恢复的语义。重点不是“抛出一个异常”，而是让这个异常在客户端能被准确识别、在日志中能快速定位、在监控里能自动告警、在重试或降级逻辑中能精准响应。
分层设计异常继承结构
避免所有远程错误都塞进一个 RemoteCallException。推荐三层结构：
-
RemoteCallException：抽象基类，继承
RuntimeException，含traceId、service、method、errorCode、timestamp等通用字段 - RemoteTimeoutException、RemoteNetworkException、RemoteServerException：按失败原因细分，便于熔断器（如 Sentinel 或 Hystrix）识别并触发对应策略
- 业务语义错误（如
UserNotFoundException）不作为子类，而是通过统一响应体（如Result<T>）携带错误码和消息返回，由调用方自行判断是否转为业务异常
构造时注入关键链路元数据
异常一旦抛出，就脱离原始调用上下文。必须在构造阶段固化以下信息：
-
traceId：从 MDC 或 OpenTracing 中获取，确保日志、监控、链路追踪对齐 - 服务名与接口名（如
"order-service"、"OrderService::create"），不写死字符串，建议从 RPC 上下文动态提取 - 原始错误码（如 Dubbo 的
CODE_TIMEOUT，gRPC 的Status.Code.DEADLINE_EXCEEDED），保留协议层语义 - 可选：超时毫秒数、序列化后的响应头摘要（调试开关控制，生产环境默认关闭）
示例构造方式：
JavaStoryDevelop
下载
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
立即学习“Java免费学习笔记（深入）”；
throw new RemoteTimeoutException("调用订单服务超时", traceId, "order-service", "OrderService::create", 3000L);保证异常链完整且可跨语言透传
RPC 异常常需序列化后跨进程甚至跨语言传输，设计时要注意：
- 所有字段声明为
transient或确保可序列化；禁止存放ThreadLocal、Connection等不可序列化对象 - 若使用 Protobuf/gRPC，不直接传 Java 异常类，而是将错误建模为标准
ErrorDetailmessage，再在客户端映射为本地异常 - Spring Cloud 场景下，可在
@ControllerAdvice中将RemoteCallException映射为 HTTP 状态码，但仅用于网关层适配，RPC 内部仍应走自有错误码体系
客户端统一拦截与解包处理
消费端收到异常后，不能只看外层消息。必须逐层调用 getCause() 还原根因：
- 使用
ExceptionUtils.getRootCause()（Apache Commons Lang）或手动循环解包，避免只取一层 cause 就止步 - 在拦截器中统一做三件事：记录带
traceId的完整堆栈（WARN 或 ERROR 级）、根据errorCode触发熔断/重试/降级、封装为前端友好的响应体（不含堆栈、不暴露技术细节） - 日志格式建议：
log.error("RPC failed [{}], service={}, method={}, traceId={}", ex.getErrorCode(), ex.getService(), ex.getMethod(), ex.getTraceId(), ex);
