微服务统一全局异常处理的核心是建立可复用、跨服务一致的规范体系，涵盖分层异常类定义、starter封装的统一处理器、非Controller层兜底机制及跨服务错误传播与可观测性对齐。
在微服务架构中做统一全局异常处理，核心不是“写一个处理器”，而是建立一套可复用、可收敛、跨服务一致的规范体系。它既要解决单个服务内的异常捕获与响应标准化，又要应对分布式调用链中的错误透传、日志对齐和监控归一问题。
定义分层业务异常体系
每个微服务应统一继承同一套基础异常类（如来自公共依赖包），避免各服务自行 new Exception("xxx")。推荐结构：
- BaseException：含 code（业务码）、message（用户提示）、detail（调试用，生产脱敏）、timestamp
- BusinessException：参数校验失败、余额不足、状态非法等——HTTP 状态码建议 400
- AuthException：未登录、token 过期、权限不足——对应 401 / 403
- SystemException：DB 连接超时、Feign 调用失败、线程池满——对应 500 或 503
- ResourceNotFoundException：明确标识资源缺失——固定返回 404
统一异常处理器 + 公共 Starter 封装
不建议每个服务重复写 @RestControllerAdvice 类。正确做法是：
Java注释规范Skills
下载
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- 将 GlobalExceptionHandler、Result 响应体、常用异常类打包为 common-exception-starter（Spring Boot AutoConfigure 模块）
- 各微服务引入该 starter，并在 application.yml 中启用：exception.handler.enabled: true
- starter 内自动注册 @RestControllerAdvice Bean，支持按需 exclude 特定异常类型
- 提供配置项控制是否打印完整堆栈、是否返回 detail 字段、敏感字段自动掩码（如手机号、身份证号）
覆盖非 Controller 层异常场景
@ControllerAdvice 只管 Web 层抛出的异常，微服务中还有大量“逃逸”场景需要兜底：
立即学习“Java免费学习笔记（深入）”；
- @Scheduled 定时任务：用 @Async + 自定义 TaskDecorator 包裹异常，再交由统一异常处理器转化
- FeignClient 远程调用失败：通过 Feign 的 ErrorDecoder 统一转为对应 SystemException，并携带 traceId
- 消息队列消费者（如 RocketMQListener）：在 onMessage 方法外层 try-catch，记录 error 日志并抛出 RuntimeException 触发重试或死信
- 全局未捕获异常：在启动类 main 方法首行注册 Thread.setDefaultUncaughtExceptionHandler，仅用于记录告警和 traceId 上报，不构造 HTTP 响应
跨服务错误传播与可观测性对齐
当 A 服务调用 B 服务失败，B 的错误不应被吞掉或模糊成 “Remote service unavailable”。要做到：
- B 服务返回标准 ErrorResponse（含 code/message/traceId），且 HTTP 状态码语义准确（如 400/401/403/404/500）
- A 服务 Feign Client 解析响应时，根据 status code 和 body.code 主动 throw 对应的 BusinessException 或 SystemException
- 所有异常日志必须携带当前 spanId / traceId，并输出到统一日志平台；message 字段不暴露数据库表名、路径、IP 等敏感信息
- 监控大盘按 error_code 分组统计，而非只看 HTTP 5xx，便于快速定位是哪类业务逻辑出错
