如何优雅地处理SpringBoot中的异常

下午两点生产环境挂了。原因是某个服务的API接口在传入非法参数时抛出了一个null指针异常没有做任何处理SpringBoot默认的“whitelabel error page”直接返回了一段丑陋的500 HTML。前端收到的不是JSON而是堆栈信息导致客户端解析失败用户界面白屏。更糟的是日志里只有一行“500 error”连具体哪个参数出问题都查不到。优雅地处理异常从来不是“顺便做做”的锦上添花而是一个生产级应用的基本素养。我们太容易把异常处理写成if-else的垃圾堆了。最常见的手法是在每个Controller方法里写try-catchcatch住一大坨Exception然后返回一个Map。代码变得像一锅粥每个接口都要重复写同样的错误响应逻辑一旦响应格式变化就得改遍所有方法。这种“防御性编程”实际上是在制造技术债它让异常处理变成了代码的毒瘤而不是盾牌。从“到处抓”到“抓一次”——全局异常处理的降维打击SpringBoot给了我们一把利器ControllerAdvice配合ExceptionHandler。你只需要定义一个全局异常处理器就能接管所有Controller抛出的异常。这就好比把散落在各个接口的灭火器集中到一个消防站不仅管理方便还统一了响应格式。看一个基本实现RestControllerAdvice public class GlobalExceptionHandler { ExceptionHandler(Exception.class) public Result handleException(Exception e) { log.error(未预期异常, e); return Result.error(500, 服务器内部错误); } }注意这里用了RestControllerAdvice而非ControllerAdvice它直接帮我们干了ResponseBody的活。一旦出现任何未被具体定义的异常都会落入这个兜底方法。但要小心这个方法不能随便写如果所有异常都走这里你就失去了对业务错误的精细控制。所以更好的做法是把常见的系统异常先拦截掉再把未知的推给兜底。自定义异常体系——拒绝“万能异常”很多团队用一个BusinessException打天下里面塞一个errorCode和message。结果导致所有业务错误都抛出同一个类前端只能根据message做判断一旦message变了前端逻辑就炸了。优雅的做法是为每种错误类型定义专属异常比如参数校验异常、数据不存在异常、权限不足异常、业务规则冲突异常等。我们可以构建一个异常基类public abstract class BaseException extends RuntimeException { private final int code; private final String message; public BaseException(int code, String message) { super(message); this.code code; this.message message; } // getters... }然后派生出具体的异常UserNotFoundException extends BaseException、InvalidParamException extends BaseException、ForbiddenException extends BaseException。这样做的好处是在全局异常处理器中你可以通过异常类型精确地设置HTTP状态码和错误响应前端也能根据异常类型做不同的处理策略而不是去解析message字符串。统一响应体——给异常穿上标准制服没有统一响应体的异常处理就像军队没有统一的军装。你的接口可能返回{code: 200, data: ...}但异常时可能返回{error:bad request}或者直接500页面。前端需要写两份解析逻辑这是灾难源头。定义一个标准的API返回类让成功和失败都穿同一件衣服。Data public class ApiResultT { private int code; private String message; private T data; private long timestamp; public static T ApiResultT success(T data) { return new ApiResult(200, success, data); } public static T ApiResultT error(int code, String message) { return new ApiResult(code, message, null); } }在全局异常处理器中所有异常都被转化为ApiResult.error()。前端只需要判断code是否为200即可。注意这里的code不是HTTP状态码而是业务状态码。200表示业务成功其他表示具体错误。HTTP状态码可以保持200对于业务错误但对于真正的系统错误比如500、403建议让前端通过HTTP状态码来感知这就需要我们在ExceptionHandler中设置response的status。异常与HTTP状态码的精准映射HTTP状态码是网络层的语义业务状态码是应用层的语义两者需要协同。例如用户请求了一个不存在的资源HTTP状态码应该是404而业务状态码可以是10001。在全局处理器中我们可以根据异常类型来设置响应状态ExceptionHandler(ResourceNotFoundException.class) public ApiResult handleNotFound(ResourceNotFoundException e, HttpServletResponse response) { response.setStatus(HttpStatus.NOT_FOUND.value()); return ApiResult.error(e.getCode(), e.getMessage()); }切忌把所有异常都返回200然后在body里放错误码。这违反了HTTP协议的语义而且会让网关、负载均衡器的健康检查变得困难。但也要注意对于同一种错误比如参数错误前端期望的往往是明确的业务错误码而非HTTP 400因为400比较笼统。所以更推荐的做法是业务错误统一返回200并在code中区分系统错误则映射对应的HTTP状态码。这需要团队达成共识但无论如何一致性比固执己见更重要。请求验证异常——别让Valid抛出的异常裸奔Spring Boot的Valid或Validated配合NotBlank、NotNull等注解在校验失败时会抛出MethodArgumentNotValidException或ConstraintViolationException。如果不处理默认返回的是400加上一个复杂的BindingResult结构前端难以解析。优雅的做法是在全局异常处理器中捕获这些异常并提取出友好的错误信息。ExceptionHandler(MethodArgumentNotValidException.class) public ApiResult handleValidation(MethodArgumentNotValidException e) { ListFieldError fieldErrors e.getBindingResult().getFieldErrors(); String message fieldErrors.stream() .map(f - f.getField() : f.getDefaultMessage()) .collect(Collectors.joining(; )); return ApiResult.error(40001, message); }这里有个细节建议仅返回第一个错误而不是所有字段错误因为处理多个错误反而让前端更迷惑。另外对于ConstraintViolationException参数在非Controller层校验也要提前捕获避免掉入兜底逻辑。国际化与错误码——让你的API走出国门如果你的服务需要支持多语言那么异常消息就不能硬编码在代码里。Spring Boot天然支持i18n我们可以把错误消息放到messages.properties中通过语言locale来动态获取。优雅的做法是异常类中只携带错误码不携带具体消息在全局处理器中根据错误码和用户语言来装配消息。// 在GlobalExceptionHandler中 Autowired private MessageSource messageSource; ExceptionHandler(BusinessException.class) public ApiResult handleBusiness(BusinessException e, Locale locale) { String message messageSource.getMessage(error. e.getCode(), e.getArgs(), locale); return ApiResult.error(e.getCode(), message); }错误码设计也需要讲究建议按模块场景分层比如1001表示用户模块-账号不存在2001表示订单模块-库存不足。这样即便message翻译变了前端依然可以根据code做逻辑判断。同时错误码最好在文档中有详细说明形成团队的“错误码圣经”。在Service层抛异常还是处理——一个经典抉择很多新手纠结于Service层是直接抛异常让Controller统一处理还是自己在Service里try-catch然后返回Result我的建议是Service层应该只专注于业务逻辑遇到违反业务规则的情况直接抛出自定义的业务异常让全局异常处理器来接管。这样Controller就变得极薄只负责接收请求和返回响应不需要再写try-catch。但也有例外如果你的Service需要处理非业务异常比如远程调用超时你可以捕获它并包装成业务异常再抛出或者直接抛出一个系统级异常。关键是保持分层清晰Controller中的try-catch除了全局处理器的兜底外不应该存在。如果你发现某个Controller里写了catch块那很可能全局处理器没有覆盖到该异常。日志记录与监控——异常处理的最后防线优雅地处理异常不只是返回好看的结构还包括妥善的记录和监控。在全局异常处理器中一定要区分日志级别对于业务异常例如用户输入错误、资源不存在用warn或info级别记录避免日志爆满对于系统异常空指针、数据库连接失败、第三方服务不可用用error级别并打印完整堆栈。此外引入一些监控指标如Micrometer对每种异常类型进行计数当某种异常突然增多时能及时报警。ExceptionHandler(DataAccessException.class) public ApiResult handleDB(DataAccessException e, HttpServletResponse response) { // 打印完整堆栈并统计到监控系统 log.error(数据库异常, e); counterService.increment(exception.db); response.setStatus(HttpStatus.INTERNAL_SERVER_ERROR.value()); return ApiResult.error(50000, 数据服务异常请稍后重试); }日志中要包含请求的唯一标识traceId便于快速关联上下游调用。如果你没有引入链路追踪至少要在入口处添加UUID并传递给异常处理器。这样运维人员就能根据traceId快速定位问题。最佳实践清单——把套路变成规范总结下来优雅处理SpringBoot异常应该遵循以下原则全局统一拦截所有异常都走RestControllerAdviceController不写try-catch。精准抛出使用自定义异常而不是RuntimeException让异常类型说明意图。统一响应体成功和失败都返回相同的JSON结构字段包括code、message、data、timestamp。合理利用HTTP状态码系统错误映射正确状态码业务错误可以统一200业务码。参数验证统一处理捕获MethodArgumentNotValidException返回简洁的提示信息。异常信息国际化错误码对应资源文件支持多语言。分层日志业务异常warn系统异常error并带堆栈。监控告警对高频异常进行计数设置阈值触发告警。隔离第三方异常将框架或中间件的异常如Feign、Redis包装成自己的异常避免泄露内部实现。不要吞异常全局兜底方法不能只是return Result.error()而不记录至少要把异常打印出来。当心“优雅陷阱”——过度设计也是一种灾难我见过一些团队为了“优雅”搞出了几十种异常类对应几十个错误码全局处理器里写了十几个ExceptionHandler方法。导致每次新增一个错误都要加类、加状态码、加处理器方法反而拖累了开发效率。优雅不是越多越好而是恰到好处。我的建议是先覆盖最常见的几类异常参数校验、资源不存在、权限不足、业务冲突、系统错误再根据业务复杂度逐步扩展。如果有非常多的相似错误可以考虑使用枚举异常码动态消息的方式而非创建大量类。比如public class BusinessException extends BaseException { public BusinessException(ErrorCode errorCode, Object... args) { super(errorCode.getCode(), formatMessage(errorCode, args)); } }其中ErrorCode是一个枚举包含code和默认消息模板。这样既能类型化又不需要为每个错误单独创建类。关键是要保持平衡让代码可维护且不过度抽象。回到开头那个线上事故。修复方案很简单添加一个全局异常处理器并把所有可能出现空指针的地方用明确的业务异常替代。但更重要的是团队意识到异常处理不是面向debug的而是面向用户体验的。前端不再看到白屏运维不再靠猜开发不用在每个接口加catch。这就是优雅的代价——一点点设计上的投入换来持续的生产力回报。真正优雅的SpringBoot异常处理不是把异常藏起来而是让异常变得可预期、可追溯、可管理。当你听到生产环境告警时能根据错误码和traceId迅速定位而不是面朝log大海发呆你就成功了。