业务异常必须用 RuntimeException 子类，不可用 Exception 及其子类；否则强制调用方处理，混淆业务逻辑与错误处理，违背“谁出错谁负责”原则。
业务异常该用 RuntimeException 还是受检异常？
业务异常必须用 RuntimeException 子类，不能用 Exception 或其子类（如 IOException）。否则调用方被迫写一堆 try-catch 或向上抛，把业务逻辑和错误处理缠在一起，违背“谁出错谁负责”的边界原则。
常见错误现象：定义了 OrderException extends Exception，结果每个 service 方法签名都带 throws OrderException，最后 controller 里全是模板化 catch，根本没法区分是参数错、库存不足还是支付超时。
- 业务异常只在明确的业务规则断点抛出，比如
if (order.getAmount() - 所有业务异常统一继承自一个基类，如
BusinessException，方便全局捕获和统一响应格式 - 不要给业务异常塞技术细节（如堆栈、SQL语句），它只回答“为什么不能继续”——例如“优惠券已过期”，而不是“MySQL connection timeout”
技术异常怎么避免污染业务代码？
技术异常（如 SQLException、HttpClientErrorException）必须在最靠近资源的地方捕获并转换，绝不能让它穿透到 service 或 controller 层。
使用场景：调用第三方 HTTP 接口失败、数据库连接中断、Redis 写入超时。这些不是业务规则问题，而是基础设施不稳定，业务层不该也不需要知道重试几次、要不要降级。
立即学习“Java免费学习笔记（深入）”；
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- DAO 层或 client 层 catch
SQLException/RestClientException，转成对应的DatabaseAccessException或ThirdPartyServiceUnavailableException（二者都应是RuntimeException子类） - 转换时保留原始异常作 cause：
throw new DatabaseAccessException("failed to update order status", e);，便于排查但不暴露给前端 - 不要在 service 方法里直接
catch SQLException——这说明数据访问逻辑没封装好，DAO 层职责被架空
@ControllerAdvice 捕获时如何区分业务异常和技术异常？
全局异常处理器必须按类型分治，否则一个 @ExceptionHandler(Exception.class) 就会让所有错误返回 500，连参数校验失败都变服务器错误。
参数差异：业务异常走 4xx 状态码 + 业务提示；技术异常走 5xx + 日志告警 + 可选降级响应。
- 单独写
@ExceptionHandler(BusinessException.class)，返回HttpStatus.BAD_REQUEST或HttpStatus.CONFLICT，body 含code和message字段 - 另写
@ExceptionHandler(DatabaseAccessException.class)等具体技术异常，记录 error 日志，返回HttpStatus.SERVICE_UNAVAILABLE，body 中message固定为“系统繁忙，请稍后重试” - 兜底的
@ExceptionHandler(RuntimeException.class)只捕获未分类的RuntimeException，打 warn 日志并返回 500，防止漏掉新异常类型
日志里怎么一眼看出是业务卡点还是系统故障？
关键不是记多少条日志，而是让每条日志自带上下文标签。业务异常日志不打 ERROR 级别，技术异常不省略 traceId。
性能影响：过度打日志会拖慢高并发接口，但漏掉关键标识会让线上问题排查时间翻倍。
- 业务异常统一用
log.warn("business rule violated: {}", e.getMessage(), e)—— warn 级别+带 message，不带堆栈（除非要调试规则逻辑） - 技术异常必须
log.error("db access failed, orderId={}", orderId, e)—— error 级别+关键业务字段+完整堆栈 - 所有日志开头加 MDC 字段，如
MDC.put("traceId", request.getHeader("X-Trace-ID"))，否则分布式链路一断就找不到根因
真正难的是坚持——每次加新校验、调新接口时，都要下意识问一句：这个错，是用户能改的，还是得运维上机器看的？答错一次，后续补日志、改状态码、调监控，成本就远不止加一行 throw。
