尧图网页设计 
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.errorCodeerrorCode;this.displayMessagedisplayMessage;}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统一返回结构通过 successfalse 标记 * 日志级别ERROR */publicclassServerExceptionextendsBaseBusinessException{publicServerException(Stringmessage){super(SYSTEM_ERROR,message);}publicServerException(Stringmessage,Throwablecause){super(SYSTEM_ERROR,message);initCause(cause);}}四、全局异常处理器通过RestControllerAdvice统一拦截异常返回标准化响应RestControllerAdvicepublicclassGlobalExceptionHandler{privatestaticfinalLoggerlogLoggerFactory.getLogger(GlobalExceptionHandler.class);/** * 业务校验异常 — 返回错误提示给前端. */ExceptionHandler(CheckException.class)publicRestControllerResult?handleCheckException(CheckExceptione){log.warn(业务校验失败: errorCode{}, message{},e.getErrorCode(),e.getMessage());RestControllerResult?resultnewRestControllerResult();result.setSuccess(false);result.setErrorMsg(resolveMessage(e));result.setErrCode(e.getErrorCode());returnresult;}/** * 系统异常 — 返回通用提示详细信息记入日志. */ExceptionHandler(ServerException.class)publicRestControllerResult?handleServerException(ServerExceptione){log.error(系统异常: {},e.getMessage(),e);RestControllerResult?resultnewRestControllerResult();result.setSuccess(false);result.setErrorMsg(系统繁忙请稍后重试);result.setErrCode(SYSTEM_ERROR);returnresult;}/** * 兜底 — 未预期的异常. */ExceptionHandler(Exception.class)publicRestControllerResult?handleException(Exceptione){log.error(未知异常,e);RestControllerResult?resultnewRestControllerResult();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(stockdeliveryQty){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?resultorderFeign.getOrderInfo(orderId);if(!Boolean.TRUE.equals(result.getSuccess())){thrownewServerException(查询订单失败orderIdorderId, msgresult.getErrorMsg());}// 2. 数据一致性异常不应该出现的情况WaitDeliveryMastermasterrepository.findById(id);if(masternull){thrownewServerException(xxx主表数据不存在idid);}// 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. 调用外部服务 → ServerExceptionRestControllerResultStockInfostockResultstockFeign.checkStock(param.getItems());if(!Boolean.TRUE.equals(stockResult.getSuccess())){thrownewServerException(xx服务调用失败: stockResult.getErrorMsg());}// 4. 动态拼接的业务提示 → ServerExceptionListStringnoStockItemsfindNoStockItems(stockResult.getData(),param.getItems());if(!noStockItems.isEmpty()){thrownewServerException(String.join(,,noStockItems) 库存不足);}// 5. 正常业务逻辑orderRepository.save(buildOrder(param));}}八、总结维度CheckExceptionServerException语义业务规则不满足系统出了问题消息对象用户开发者消息内容i18n key 或用户友好文案带上下文的技术描述日志级别WARNERROR是否触发告警一般不是HTTP 状态码200 successfalse200 successfalse前端处理展示 errorMsg 给用户展示系统繁忙 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.errorCodeerrorCode;this.displayMessagedisplayMessage;}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统一返回结构通过 successfalse 标记 * 日志级别ERROR */publicclassServerExceptionextendsBaseBusinessException{publicServerException(Stringmessage){super(SYSTEM_ERROR,message);}publicServerException(Stringmessage,Throwablecause){super(SYSTEM_ERROR,message);initCause(cause);}}四、全局异常处理器通过RestControllerAdvice统一拦截异常返回标准化响应RestControllerAdvicepublicclassGlobalExceptionHandler{privatestaticfinalLoggerlogLoggerFactory.getLogger(GlobalExceptionHandler.class);/** * 业务校验异常 — 返回错误提示给前端. */ExceptionHandler(CheckException.class)publicRestControllerResult?handleCheckException(CheckExceptione){log.warn(业务校验失败: errorCode{}, message{},e.getErrorCode(),e.getMessage());RestControllerResult?resultnewRestControllerResult();result.setSuccess(false);result.setErrorMsg(resolveMessage(e));result.setErrCode(e.getErrorCode());returnresult;}/** * 系统异常 — 返回通用提示详细信息记入日志. */ExceptionHandler(ServerException.class)publicRestControllerResult?handleServerException(ServerExceptione){log.error(系统异常: {},e.getMessage(),e);RestControllerResult?resultnewRestControllerResult();result.setSuccess(false);result.setErrorMsg(系统繁忙请稍后重试);result.setErrCode(SYSTEM_ERROR);returnresult;}/** * 兜底 — 未预期的异常. */ExceptionHandler(Exception.class)publicRestControllerResult?handleException(Exceptione){log.error(未知异常,e);RestControllerResult?resultnewRestControllerResult();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(stockdeliveryQty){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?resultorderFeign.getOrderInfo(orderId);if(!Boolean.TRUE.equals(result.getSuccess())){thrownewServerException(查询订单失败orderIdorderId, msgresult.getErrorMsg());}// 2. 数据一致性异常不应该出现的情况WaitDeliveryMastermasterrepository.findById(id);if(masternull){thrownewServerException(xxx主表数据不存在idid);}// 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. 调用外部服务 → ServerExceptionRestControllerResultStockInfostockResultstockFeign.checkStock(param.getItems());if(!Boolean.TRUE.equals(stockResult.getSuccess())){thrownewServerException(xx服务调用失败: stockResult.getErrorMsg());}// 4. 动态拼接的业务提示 → ServerExceptionListStringnoStockItemsfindNoStockItems(stockResult.getData(),param.getItems());if(!noStockItems.isEmpty()){thrownewServerException(String.join(,,noStockItems) 库存不足);}// 5. 正常业务逻辑orderRepository.save(buildOrder(param));}}八、总结维度CheckExceptionServerException语义业务规则不满足系统出了问题消息对象用户开发者消息内容i18n key 或用户友好文案带上下文的技术描述日志级别WARNERROR是否触发告警一般不是HTTP 状态码200 successfalse200 successfalse前端处理展示 errorMsg 给用户展示系统繁忙