Java文件上传应封装FileUploadException为语义清晰的自定义异常，按场景分层设计FileSizeLimitExceededException、FileTypeNotAllowedException等，继承RuntimeException并保留异常链，在Controller精准捕获转换，配合@ControllerAdvice统一响应。
Java中文件上传失败抛出的 FileUploadException 是 Apache Commons FileUpload 库的运行时异常，本身不可捕获具体原因（比如大小超限、IO异常、编码错误等），直接暴露给上层容易泄露技术细节，也不利于统一错误处理。自定义封装的核心是：捕获原始异常 → 提取关键信息 → 包装成业务语义清晰、可分类响应的自定义异常。
明确自定义异常的职责边界
不要试图把所有上传问题都塞进一个异常类。建议按常见失败场景分层设计：
- FileSizeLimitExceededException：文件大小超过限制（如 10MB）
- FileTypeNotAllowedException：后缀或 MIME 类型不合法（如上传 .exe）
-
FileNameInvalidException：文件名含非法字符、路径遍历（如
../web.xml） - FileUploadInternalException：底层 IO 或解析异常（如磁盘满、临时目录不可写）
继承 RuntimeException 并保留原始异常链
自定义异常应继承 RuntimeException，避免强制 try-catch；同时通过构造函数传入原始 FileUploadException，确保日志和调试时能追溯根因：
public class FileSizeLimitExceededException extends RuntimeException {
private final long maxSize;
private final long actualSize;
public FileSizeLimitExceededException(long maxSize, long actualSize, Throwable cause) {
super("文件大小超出限制：" + actualSize + " bytes，最大允许 " + maxSize + " bytes", cause);
this.maxSize = maxSize;
this.actualSize = actualSize;
}
// getter 省略
}
在 Controller 层做精准捕获与转换
不要在 Service 或工具类里直接 throw 自定义异常，而应在接收请求的 Controller 中，针对不同子类型做差异化处理：
JavaStoryDevelop
下载
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
立即学习“Java免费学习笔记（深入）”；
- 捕获
SizeLimitExceededException→ 转为FileSizeLimitExceededException - 捕获
InvalidContentTypeException→ 转为FileTypeNotAllowedException - 捕获
FileUploadBase.IOFileUploadException→ 检查 errno 或 message 关键词（如 “No space left”、“Permission denied”）→ 转为FileUploadInternalException - 其他未识别的
FileUploadException→ 统一封装为FileUploadInternalException，并记录 warn 日志
配合全局异常处理器统一响应格式
用 @ControllerAdvice 拦截自定义异常，返回结构化 JSON（如 status、code、message），便于前端提示：
@ExceptionHandler(FileSizeLimitExceededException.class)
public ResponseEntity<ApiResponse> handleFileSizeLimit(FileSizeLimitExceededException e) {
return ResponseEntity.badRequest().body(
ApiResponse.error("FILE_SIZE_EXCEED")
.detail("最大支持 " + e.getMaxSize() + " 字节，当前 " + e.getActualSize() + " 字节")
);
}
其中 FILE_SIZE_EXCEED 是业务码，不暴露技术关键词（如 “SizeLimitExceededException”）。
