异常信息应包含“谁、在哪、为什么、怎么解”四要素，面向用户需脱敏简洁，面向开发者需保留技术细节，禁用空消息、万能消息及吞栈行为，推荐模板化构造提升一致性与可诊断性。
异常信息不是报错日志，而是给开发者或运维人员看的“诊断线索”。设计得好，能快速定位问题；设计得差，只会让人反复翻源码、查文档、抓头发。
异常消息要包含“谁、在哪、为什么、怎么解”四个要素
比如抛出 NullPointerException 时，只写“对象为空”是无效的。应明确指出：
-
谁：哪个变量/参数/字段为空（如
userId、config.cacheStrategy） -
在哪：发生位置（类名+方法+行号可选，但至少到方法级，如
UserServiceImpl.loadUserProfile()） - 为什么：上下文原因（如“上游未传 userId，且未配置默认值”“缓存策略未在 Spring 容器中注册”）
- 怎么解：可操作的建议（如“请检查 API 请求体是否包含 userId 字段”“确认 CacheStrategyImpl 是否加了 @Component 注解”）
区分用户可见提示与内部异常信息
面向前端或终端用户的提示语（如 HTTP 接口返回的 message）必须脱敏、简洁、无技术细节；而 Throwable.getMessage() 或日志中的异常信息则要保留技术细节。
错误做法：throw new IllegalArgumentException("userId is null");
这既暴露了变量名，又没说明业务含义，也不适合直接返回给前端。
推荐做法：throw new IllegalArgumentException("用户标识缺失：请求中未提供有效的 userId，请检查参数完整性");
再配合统一异常处理器，将该消息转为用户友好的提示（如“请重新登录”或“参数错误，请稍后重试”），同时记录完整堆栈和上下文到日志。
避免空消息、重复消息和“万能消息”
以下都是反模式：
ImageMagick 批处理处理器
下载
使用 ImageMagick 的 convert 和 mogrify 命令进行批量图像处理，支持调整大小、裁剪、水印和格式转换。与 libvips 集成以实现高性能缩略图生成。
立即学习“Java免费学习笔记（深入）”；
-
throw new RuntimeException("");—— 空字符串，等于没说 -
throw new ServiceException("系统异常");—— 所有错误都叫“系统异常”，失去区分度 -
catch (Exception e) { throw new RuntimeException(e.getMessage()); }—— 吞掉原始异常类型和堆栈，还可能丢失中文字符或格式
真正有用的异常信息，应该让看到的人一眼知道：这不是随机故障，而是某条路径上某个环节出了可预期的问题。
用模板化 + 上下文注入提升一致性
可封装一个异常构造工具，例如：
throw BizException.of("USER_NOT_FOUND")
.withParam("userId", userId)
.withCause("数据库查询返回空结果")
.withSuggestion("确认用户是否已注册，或检查 DB 连接与 user 表状态");
这样既能保证格式统一，又便于后续接入监控系统做关键词聚合（如按 USER_NOT_FOUND 统计频次）、国际化替换，甚至自动生成排查文档。
