统一捕获异常的核心是在网关层建立集中式、可扩展、解耦的错误封装体系，通过GlobalFilter+自定义GatewayException实现响应式异常处理，并标准化返回JSON结构含code、message、requestId和timestamp。
在微服务网关中统一捕获异常的核心思路
网关（如 Spring Cloud Gateway）本身不直接运行业务逻辑，但它是所有请求的入口，适合做全局异常拦截和标准化错误响应。Java 封装的关键不是写一个“万能工具类”，而是利用 Spring 的异常处理机制，在网关层建立集中式、可扩展、与业务解耦的错误封装体系。
用 @ControllerAdvice + 自定义异常完成统一捕获
虽然网关基于 WebFlux（响应式），但 Spring Cloud Gateway 2.4+ 默认使用 Spring Boot 2.6+，支持在网关模块中添加 @ControllerAdvice 配合 @ExceptionHandler 处理部分同步异常（如 Filter 中抛出的 RuntimeException）。更推荐的方式是结合全局过滤器（GlobalFilter）+ 自定义异常类型：
- 定义标准异常基类，如 GatewayException，含
code（业务码）、message（用户提示）、details（调试信息）字段 - 在自定义 GlobalFilter 中对下游服务返回的 4xx/5xx、超时、连接失败等场景，主动封装为 GatewayException
- 编写一个 ExceptionHandlingFilter（实现 GlobalFilter），在 chain.filter() 后 catch 异常，并调用统一错误构造器生成 JSON 响应体
标准化错误响应体结构设计
避免返回原始堆栈或 Spring 默认错误页。推荐结构简洁、前后端约定清晰：
{
"code": "GATEWAY_TIMEOUT",
"message": "请求下游服务超时，请稍后重试",
"requestId": "a1b2c3d4",
"timestamp": "2024-06-15T10:22:33.123Z"
}
- code：字符串枚举（如 GATEWAY_SERVICE_UNAVAILABLE），不暴露内部 HTTP 状态码，便于前端 i18n 和埋点
- message：面向用户的友好提示，非技术描述
- requestId：从请求头透传或自动生成，用于全链路日志追踪
- 不强制包含 data 字段，错误响应默认无业务数据
适配响应式流，避免阻塞式异常处理
Spring Cloud Gateway 基于 Project Reactor，异常需在 Mono/Flux 链中处理，不能依赖传统 try-catch：
立即学习“Java免费学习笔记（深入）”；
- 在 GlobalFilter 的 filter 方法中，用 exchange.getResponse().setStatusCode() 设置状态码
- 用 Mono.error(new GatewayException(...)) 中断流程，再通过 onErrorResume 或全局 error handler 转为标准响应体
- 借助 DataBufferFactory 写入 JSON 响应体，注意设置 Content-Type 为
application/json;charset=UTF-8 - 避免在 filter 中调用
block()，否则破坏响应式特性
补充建议：日志与可观测性对齐
统一异常封装不只是改返回格式，更是可观测性的起点：
- 每次抛出 GatewayException 时，记录 ERROR 日志，包含 requestId、code、上游服务名、耗时、原始异常 cause
- 将 code 上报至监控系统（如 Prometheus），按 code 分组统计错误率
- 对高频 code（如 GATEWAY_DOWNSTREAM_503）配置告警，而非只盯 HTTP 503
- 前端根据 code 做差异化处理（如自动重试、跳转登录、展示离线页）
