1. 课程导论：为什么需要统一的错误处理骨架？参数校验与业务异常分层的核心价值
在企业级业务系统中，错误处理往往是最容易被低估、却对系统稳定性影响最大的环节。一个没有统一错误处理骨架的系统，通常表现为：接口返回格式混乱、异常信息泄露内部实现、前端无法统一解析错误、排查问题需要翻阅多个服务日志。这些问题直接导致开发效率下降、线上故障定位困难、API 契约形同虚设。
本课程的核心目标，是构建一套参数校验与业务异常分层的通用骨架，让错误处理从“被动救火”转变为“主动防御”。
1.1 没有统一骨架的痛点
以下表格总结了缺乏统一错误处理时，系统各层面常见的典型问题：
| 层面 | 典型问题 | 后果 |
|---|---|---|
| 接口层 | 不同接口返回的 error code 格式不一致，有的返回字符串，有的返回数字 | 前端需要为每个接口单独编写解析逻辑 |
| 业务层 | 业务异常直接抛出 RuntimeException，未区分“可预知”与“不可预知” | 无法针对不同异常做差异化处理（如重试、降级、告警） |
| 校验层 | 参数校验散落在业务代码中，重复且容易遗漏 | 脏数据穿透到核心逻辑，引发数据不一致 |
| 日志层 | 异常堆栈打印不完整，或敏感信息（如数据库连接串）被写入日志 | 排查效率低，且存在安全合规风险 |
核心洞察： 错误处理不是“异常捕获 + 返回错误码”这么简单。它需要从架构层面定义一套分层契约，让每一层只关心自己职责范围内的异常，并将错误信息以统一格式向上传递。
1.2 参数校验与业务异常分层的核心价值
本课程提出的骨架，围绕两个核心支柱展开：参数校验与业务异常分层。它们各自解决不同维度的问题，又相互配合形成完整闭环。
- 参数校验：在请求进入业务逻辑之前，拦截格式错误、边界溢出、类型不匹配等低级错误。这是系统的第一道防线，能过滤掉约 60% 的无效请求。
- 业务异常分层：将异常按照“系统异常”、“业务异常”、“校验异常”三个维度进行划分，每一层有明确的处理策略和返回格式。这是系统的第二道防线，确保业务逻辑的异常不会污染系统底层。
以下 SVG 图展示了分层骨架的整体架构：
1.3 分层设计带来的直接收益
采用参数校验与业务异常分层后，企业系统可以获得以下可量化的收益：
- 接口契约标准化：所有 API 返回格式统一，前端 SDK 可以做到一次接入、全局生效。
- 故障定位效率提升：通过 traceId 和分层异常码，5 分钟内即可定位到具体是校验层、业务层还是系统层的问题。
- 代码可维护性增强：业务代码中不再混杂 try-catch 和 if-else 校验，核心逻辑清晰可读。
- 安全合规：系统异常不会暴露堆栈和敏感信息，业务异常只返回用户可理解的提示。
实践建议： 在项目初期就引入统一错误处理骨架，比在后期重构时再引入，成本至少降低 70%。骨架一旦建立，后续所有新模块的开发都可以直接复用，无需重复设计。
1.4 本课程覆盖的核心模块
为了帮助你完整掌握这套骨架，课程将按以下模块展开：
| 模块 | 核心内容 | 产出物 |
|---|---|---|
| 参数校验 | 声明式校验、自定义校验注解、分组校验、国际化错误消息 | 可复用的校验框架 |
| 异常分层 | 系统异常 / 业务异常 / 校验异常的定义与继承体系 | 异常类层次结构 |
| 全局处理器 | Spring Boot 全局异常拦截、统一响应体封装 | @RestControllerAdvice 实现 |
| 错误码设计 | 错误码分段规则、枚举定义、文档自动生成 | 错误码规范文档 |
| 日志与监控 | 异常日志结构化输出、告警阈值配置 | 日志模板 + 监控看板 |
接下来的章节，我们将从参数校验的具体实现开始，逐步搭建起这套完整的错误处理骨架。