受检异常在分布式系统中必须在服务边界转化，以避免序列化失败、解除上下游耦合、保留链路可观测性；转化需按业务/系统异常分层归一为错误码或标准化非受检异常，并通过网关、rpc拦截器统一落地。
受检异常（Checked Exception）在分布式系统中不应直接跨服务传播，必须在边界处完成转化——这是避免序列化失败、解耦上下游、保障链路可观测性的关键动作。
为什么必须转化受检异常
Java 的受检异常要求调用方显式处理，但在分布式场景下，它会带来三重风险：
- 序列化兼容性问题：自定义受检异常类若未实现 Serializable 或字段不满足反序列化要求，RPC（如 Dubbo、gRPC）调用将直接失败
- 强耦合契约：下游服务被迫感知上游的异常类型体系，违背“服务自治”原则
- 链路信息丢失：原始堆栈和业务上下文常被截断或包装成通用异常（如
RemoteException），导致根因难定位
转化的核心原则
转化不是简单地“把 Exception 换成 RuntimeException”，而是按语义分层归一：
-
业务异常 → 统一业务错误码 + 结构化响应体：例如将
InsufficientBalanceException转为 HTTP 400 响应，body 含{"code":"BALANCE_INSUFFICIENT","message":"余额不足","trace_id":"xxx"} -
系统异常 → 标准化非受检异常子类：如封装为
ServiceUnavailableException或TimeoutException，继承RuntimeException，并携带service、upstream、duration_ms等 MDC 上下文 -
禁止向上抛出原始受检异常：无论 Feign、OpenFeign 还是 Spring Cloud Gateway，拦截器层必须捕获并转化；RPC 框架（如 Dubbo）需配置全局
ExceptionFilter
落地关键点
转化策略要嵌入到架构分层中，而非仅靠开发自觉：
-
网关层统一拦截：Spring Cloud Gateway 或 API 网关中，对后端返回的异常响应做标准化映射（如将 5xx →
SystemFailureException，4xx →BizValidationException） -
RPC 客户端透明适配：Dubbo 的
GenericFilter或 gRPC 的ServerInterceptor中，将服务端抛出的受检异常统一转为状态码+元数据（status.code和status.details） -
日志与指标联动：转化后的异常必须注入
trace_id和错误分类标签（如error_category=network），确保可被后续异常转化流水线识别并生成离散指标
不推荐的做法
这些看似“能跑通”的方式，长期会腐蚀系统稳定性：
- 在 service 层 catch 后 throw new RuntimeException(e)，丢失业务语义
- 让 DTO 或 VO 类继承受检异常，试图绕过序列化限制（违反分层隔离）
- 依赖客户端自行解析响应体中的 error 字段，缺乏统一契约和校验
