Java异常处理框架设计与实现详解

本文深入剖析了Java中构建高可用、易维护统一异常处理框架的完整实践方案，涵盖分层自定义异常体系（BaseException、BusinessException、SystemException、AuthException）、基于@ControllerAdvice的全局异常捕获与精准响应、标准化Result结构（code/msg/data）与模块化错误码规范、AOP驱动的上下文感知日志记录及敏感信息脱敏等核心设计，旨在彻底消除重复try-catch、保障错误语义清晰、响应可控、日志可溯，为微服务架构下的稳定性与可观测性提供坚实支撑。

Java中实现统一异常处理框架，核心是将异常的捕获、分类、转换与响应封装成可复用、易维护的结构，避免在每个Controller或Service中重复写try-catch，同时保证前后端交互语义清晰、错误信息可控、日志可追溯。

定义业务异常体系（继承RuntimeException）

不建议直接抛出Exception或throw new Exception("xxx")，应建立分层异常类： - 自定义基类 BaseException（含code、message、timestamp等通用字段） - 业务异常如 BusinessException（如参数校验失败、余额不足） - 系统异常如 SystemException（如DB连接超时、远程调用失败） - 权限异常如 AuthException（用于统一拦截未登录/无权限）

所有自定义异常均继承RuntimeException，避免强制try-catch干扰业务主流程；构造时支持链式传参，例如：

使用@ControllerAdvice + @ExceptionHandler全局捕获

创建一个配置类（如GlobalExceptionHandler），用@ControllerAdvice声明为全局异常处理器，再通过@ExceptionHandler指定处理哪些异常类型：

• @ExceptionHandler(BusinessException.class) → 返回标准JSON格式的错误响应（如{code: 1001, msg: "用户不存在", data: null}）
• @ExceptionHandler(MethodArgumentNotValidException.class) → 提取@Valid校验失败的字段和提示，组装成统一错误结构
• @ExceptionHandler(Exception.class) → 捕获未被显式处理的运行时异常，记录完整堆栈，返回通用系统错误码（如50000），但不暴露敏感信息

注意：不同异常对应不同HTTP状态码（如400对应参数异常，401对应认证失败，403对应权限拒绝，500对应服务异常）。

配合AOP记录异常日志并脱敏

异常发生时，仅打印堆栈不够——需记录请求上下文（URL、method、入参、用户ID、traceId）便于排查。可用@Around切面在异常抛出后执行日志记录逻辑：

• 捕获异常前记录请求快照（排除密码、token等敏感字段）
• 异常被捕获后，记录error级别日志，包含异常类型、业务code、traceId、简要message
• 对SQLException、RedisConnectionException等底层异常做归因包装，转为更友好的SystemException

日志中避免打印完整request body或stack trace到前端响应体，防止信息泄露。

前端友好响应结构与错误码规范

统一返回类（如Result）必须包含三个核心字段：code（整型错误码）、msg（面向用户的提示语）、data（正常时返回数据，异常时为null）。错误码按模块划分：

• 1000–1999：用户模块（1001=用户不存在，1002=手机号已注册）
• 2000–2999：订单模块（2001=库存不足，2002=订单已支付）
• 5000–5999：系统级（5001=数据库异常，5002=第三方服务不可用）

code必须全局唯一且含义明确，禁止用“0”表示失败、“1”表示成功这类模糊设计；msg由后端拼装完成，不依赖前端翻译，也不含变量占位符（如"{name}不存在" → "张三不存在"）。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~