Java 业务异常体系设计

Java 业务异常体系设计

一、核心概念

在 Spring Boot 项目中，异常分为两大类：

两者的本质区别在于：业务异常是"预期内的失败"，系统异常是"预期外的故障"。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、为什么要区分两种异常

如果不区分，会出现这些问题：

// 反面示例：全部用 RuntimeExceptionthrownewRuntimeException("手机号格式不正确");// 业务校验thrownewRuntimeException("Redis连接超时");// 系统故障

• 全局异常处理器无法区分该返回 400 还是 500
• 日志级别不好定——业务校验 warn 就够，系统异常要 error
• 前端不知道该展示错误提示还是"系统繁忙请重试"
• 监控报警会被大量业务校验失败淹没

三、异常类设计

3.1 基类

/** * 业务异常基类. */publicabstractclassBaseBusinessExceptionextendsRuntimeException{/** 错误码 */privateStringerrorCode;/** 给前端展示的消息 */privateStringdisplayMessage;publicBaseBusinessException(StringerrorCode,StringdisplayMessage){super(displayMessage);this.errorCode=errorCode;this.displayMessage=displayMessage;}publicStringgetErrorCode(){returnerrorCode;}publicStringgetDisplayMessage(){returndisplayMessage;}}

3.2 业务校验异常（CheckException）

用户操作不符合业务规则时抛出。消息是给用户看的。

/** * 业务校验异常 — 用户可感知、可处理的错误. * * 场景：参数校验失败、业务规则不满足、前置条件不具备 * HTTP 状态码：200（业务层面的失败，不是HTTP层面的错误） * 日志级别：WARN */publicclassCheckExceptionextendsBaseBusinessException{publicCheckException(StringerrorCode){super(errorCode,null);}publicCheckException(StringerrorCode,StringdisplayMessage){super(errorCode,displayMessage);}}

3.3 系统服务异常（ServerException）

系统内部出错或外部依赖不可用时抛出。消息是给开发排查用的。

/** * 系统服务异常 — 非预期的系统错误. * * 场景：外部接口调用失败、数据不一致、空指针前的主动抛出 * HTTP 状态码：200（统一返回结构，通过 success=false 标记） * 日志级别：ERROR */publicclassServerExceptionextendsBaseBusinessException{publicServerException(Stringmessage){super("SYSTEM_ERROR",message);}publicServerException(Stringmessage,Throwablecause){super("SYSTEM_ERROR",message);initCause(cause);}}

四、全局异常处理器

通过@RestControllerAdvice统一拦截异常，返回标准化响应：

@RestControllerAdvicepublicclassGlobalExceptionHandler{privatestaticfinalLoggerlog=LoggerFactory.getLogger(GlobalExceptionHandler.class);/** * 业务校验异常 — 返回错误提示给前端. */@ExceptionHandler(CheckException.class)publicRestControllerResult<?>handleCheckException(CheckExceptione){log.warn("业务校验失败: errorCode={}, message={}",e.getErrorCode(),e.getMessage());RestControllerResult<?>result=newRestControllerResult<>();result.setSuccess(false);result.setErrorMsg(resolveMessage(e));result.setErrCode(e.getErrorCode());returnresult;}/** * 系统异常 — 返回通用提示，详细信息记入日志. */@ExceptionHandler(ServerException.class)publicRestControllerResult<?>handleServerException(ServerExceptione){log.error("系统异常: {}",e.getMessage(),e);RestControllerResult<?>result=newRestControllerResult<>();result.setSuccess(false);result.setErrorMsg("系统繁忙，请稍后重试");result.setErrCode("SYSTEM_ERROR");returnresult;}/** * 兜底 — 未预期的异常. */@ExceptionHandler(Exception.class)publicRestControllerResult<?>handleException(Exceptione){log.error("未知异常",e);RestControllerResult<?>result=newRestControllerResult<>();result.setSuccess(false);result.setErrorMsg("系统繁忙，请稍后重试");returnresult;}/** * 解析错误消息：支持 i18n 资源 key 或直接文本. */privateStringresolveMessage(CheckExceptione){if(e.getDisplayMessage()!=null){returne.getDisplayMessage();}// 尝试从 i18n 资源文件解析 errorCode 对应的文本// 如 "xxx.delivery.confirm.install-time-empty" → "请选择安装时间"returnMessageSourceUtil.getMessage(e.getErrorCode());}}

五、i18n 国际化消息（CheckException 的 errorCode 模式）

当CheckException只传 errorCode 时，通过资源文件解析对应文案：

# messages.properties xxx.delivery.confirm.install-time-empty=请选择安装时间 xxx.delivery.confirm.install-time-too-early=安装时间不能早于当前时间1小时 xxx.check.warehouse.delivery.range.error=该仓库不在配送范围内 // 使用方式 — 只传 key throw new CheckException("xxx.delivery.confirm.install-time-empty"); // 前端收到: {"success":false, "errorMsg":"请选择安装时间"}

好处：

• 错误文案统一管理，修改不用改代码
• 支持多语言
• errorCode 可用于前端精确匹配特定错误做差异化处理

六、两种异常的使用场景对比

6.1 CheckException 适用场景

// 1. 参数校验if(StringUtils.isEmpty(orderCode)){thrownewCheckException("ORDER_CODE_EMPTY","订单号不能为空");}// 2. 业务规则校验if(stock<deliveryQty){thrownewCheckException("STOCK_NOT_ENOUGH","库存不足，当前库存："+stock);}// 3. 状态校验if(!Objects.equals(order.getStatus(),"WAIT_DELIVERY")){thrownewCheckException("ORDER_STATUS_ERROR","当前订单状态不允许发货");}// 4. 用 i18n key 的方式if(installTime.before(DateUtils.addHour(newDate(),1))){thrownewCheckException("stock.delivery.confirm.install-time-too-early");}

6.2 ServerException 适用场景

// 1. 外部服务调用失败RestControllerResult<?>result=orderFeign.getOrderInfo(orderId);if(!Boolean.TRUE.equals(result.getSuccess())){thrownewServerException("查询订单失败，orderId="+orderId+", msg="+result.getErrorMsg());}// 2. 数据一致性异常（不应该出现的情况）WaitDeliveryMastermaster=repository.findById(id);if(master==null){thrownewServerException("xxx主表数据不存在，id="+id);}// 3. 直接拼接错误信息（本次需求的用法）thrownewServerException(goodsNames+"缺少安装时间");

七、通用示例：一个完整的 Service 方法

@ServicepublicclassOrderServiceImplimplementsOrderService{@OverridepublicvoidsubmitOrder(SubmitOrderParamparam){// 1. 参数校验 → CheckExceptionif(param.getItems()==null||param.getItems().isEmpty()){thrownewCheckException("ORDER_ITEMS_EMPTY","请至少选择一件商品");}// 2. 业务规则校验 → CheckException (i18n key)if(param.getTotalAmount().compareTo(BigDecimal.ZERO)<=0){thrownewCheckException("order.submit.amount-invalid");}// 3. 调用外部服务 → ServerExceptionRestControllerResult<StockInfo>stockResult=stockFeign.checkStock(param.getItems());if(!Boolean.TRUE.equals(stockResult.getSuccess())){thrownewServerException("xx服务调用失败: "+stockResult.getErrorMsg());}// 4. 动态拼接的业务提示 → ServerExceptionList<String>noStockItems=findNoStockItems(stockResult.getData(),param.getItems());if(!noStockItems.isEmpty()){thrownewServerException(String.join(",",noStockItems)+" 库存不足");}// 5. 正常业务逻辑orderRepository.save(buildOrder(param));}}

八、总结