Java 业务异常体系设计

发布时间：2026/10/28 7:09:31

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 给用户展示系统繁忙

相关新闻

VirtualMotionCapture：VR动作捕捉协议的开源实现与跨平台虚拟角色控制技术

VirtualMotionCapture：VR动作捕捉协议的开源实现与跨平台虚拟角色控制技术

VirtualMotionCapture：VR动作捕捉协议的开源实现与跨平台虚拟角色控制技术 【免费下载链接】VirtualMotionCapture VRゲーム中にモデルをコントロール 项目地址: https://gitcode.com/gh_mirrors/vi/VirtualMotionCapture VirtualMotionCapture（V…

2026/10/28 0:45:03 阅读更多 →
Krea 2 Identity Edit：用一句话就能精准编辑图片的AI神器，究竟有多强大？

Krea 2 Identity Edit：用一句话就能精准编辑图片的AI神器，究竟有多强大？

Krea 2 Identity Edit：用一句话就能精准编辑图片的AI神器，究竟有多强大？ 【免费下载链接】krea2-identity-edit 项目地址: https://ai.gitcode.com/hf_mirrors/conradlocke/krea2-identity-edit 还在为复杂的图片编辑软件头疼吗&…

2026/10/24 10:52:31 阅读更多 →
ComfyUI-WanVideoWrapper实战指南：高效构建AI视频生成工作流

ComfyUI-WanVideoWrapper实战指南：高效构建AI视频生成工作流

ComfyUI-WanVideoWrapper实战指南：高效构建AI视频生成工作流 【免费下载链接】ComfyUI-WanVideoWrapper 项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper ComfyUI-WanVideoWrapper是WanVideo系列模型在ComfyUI中的强大封装插件&…

2026/10/24 14:58:31 阅读更多 →

最新新闻

Electron桌面应用开发实战：从环境搭建到打包发布全流程

Electron桌面应用开发实战：从环境搭建到打包发布全流程

做前端这些年，我大部分时间都在跟浏览器标签页打交道，直到第一次把桌面应用跑起来，才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词，最开始是在某段时间频繁出现在同事的讨论里，一个用HTML…

2026/10/27 17:33:32 阅读更多 →
滑盖智能锁T109深度解析：结构原理、安装调试与故障排查

滑盖智能锁T109深度解析：结构原理、安装调试与故障排查

简介：亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档，主要面向智能锁安装人员、终端用户及售后维护者，帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件，大小4.37MB，内容结构清晰&#xff…

2026/10/27 4:06:49 阅读更多 →
PMSM弱磁控制原理与Simulink建模：高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模：高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统，整车要求空载跑到8m/s，电机转速已经拉到额定点，驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令，转速纹丝不动，三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/10/27 7:21:53 阅读更多 →
C++核心知识点：从内存管理到STL的实战指南

C++核心知识点：从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年，用它写过嵌入式驱动、做过游戏服务端，也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词，我其实挺感慨的——这门语言的难点从来不是语法多，而是知识点之间的耦合太深…

2026/10/27 18:20:50 阅读更多 →
T109滑盖智能锁怎么装？安装调试与故障排查全攻略

T109滑盖智能锁怎么装？安装调试与故障排查全攻略

简介：亚太天能T109滑盖智能锁产品说明书以PDF格式发布，适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开，先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能，再给出完整安装步骤&…

2026/10/27 6:20:47 阅读更多 →
LLM知识降熵：从信息垄断到理解权下放

LLM知识降熵：从信息垄断到理解权下放

你有没有过这种经历：翻开源码注释、论文摘要或者一份专业报告，每个字都认识，连在一起却像天书。想找人聊聊，身边要么没人懂，要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型，几秒钟之后&a…

2026/10/27 4:06:50 阅读更多 →

日新闻

周新闻

月新闻

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/27 13:55:19 阅读更多 →
Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/27 7:21:50 阅读更多 →
黑夜航拍船只数据集训练YOLOV5模型全流程解析

黑夜航拍船只数据集训练YOLOV5模型全流程解析

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/27 19:19:37 阅读更多 →