解决Spring Boot上传默认限制文件大小和完善超限异常(若依框架)

文章目录

  • 报错信息
  • 问题分析
  • 技术原理
  • 解决方法
    • [1️⃣调整 Spring Boot 配置文件](#1️⃣调整 Spring Boot 配置文件)
    • [2️⃣检查内嵌 Tomcat 配置(可选)](#2️⃣检查内嵌 Tomcat 配置(可选))
    • [3️⃣ 代码自定义配置(覆盖配置文件)](#3️⃣ 代码自定义配置(覆盖配置文件))
  • 全局异常处理代码

报错信息

bash 复制代码
org.springframework.web.multipart.MaxUploadSizeExceededException: 
Maximum upload size exceeded] with root cause
org.apache.tomcat.util.http.fileupload.impl.FileSizeLimitExceededException:
The field file exceeds its maximum permitted size of 1048576 bytes.
at org.apache.tomcat.util.http.fileupload.impl.FileItemStreamImpl$1.raiseError(FileItemStreamImpl.java:117)
at org.apache.tomcat.util.http.fileupload.util.LimitedInputStream.checkLimit(LimitedInputStream.java:76)
at org.apache.tomcat.util.http.fileupload.util.LimitedInputStream.read(LimitedInputStream.java:135)

问题分析

  • 日志显示 FileSizeLimitExceededException,表明上传文件大小超过 Spring Boot 默认的 **1MB(1048576 字节)**限制。这是 Spring Boot 对文件上传的安全保护机制,需通过配置调整解决。

技术原理

  • Spring Multipart 机制:通过 MultipartResolver 解析上传请求,默认依赖 Tomcat 的 commons-fileupload 组件。
  • 异常链路:DispatcherServlet → MultipartResolver → Tomcat文件流限制触发异常。
  • 优先级:代码配置 > 配置文件 > 框架默认值。

解决方法

1️⃣调整 Spring Boot 配置文件

  • 在 application.properties 或 application.yml 中修改以下参数。

    java 复制代码
    # 单个文件大小上限(示例设置为 10MB)
    spring.servlet.multipart.max-file-size=10MB  
    # 整个请求(含多文件)大小上限(示例设置为 100MB)
    spring.servlet.multipart.max-request-size=100MB  
    xml 复制代码
    spring:
      servlet:
        multipart:
          max-file-size: 10MB # 单个文件大小上限(示例设置为 10MB)
          max-request-size: 100MB # 整个请求(含多文件)大小上限(示例设置为 100MB)

2️⃣检查内嵌 Tomcat 配置(可选)

  • 若上传文件极大(如超过 2GB),需额外调整 Tomcat 的请求体限制

    java 复制代码
    server.tomcat.max-swallow-size=2GB  
    xml 复制代码
    server:
      tomcat:
        max-swallow-size: 2GB 

3️⃣ 代码自定义配置(覆盖配置文件)

  • 若通过代码配置了 MultipartConfigElement,需在 Bean 中显式设置限制

    java 复制代码
    @Bean 
    public MultipartConfigElement multipartConfigElement() {
        MultipartConfigFactory factory = new MultipartConfigFactory();
        factory.setMaxFileSize(DataSize.ofMegabytes(10)); 
        factory.setMaxRequestSize(DataSize.ofMegabytes(100)); 
        return factory.createMultipartConfig(); 
    }

全局异常处理代码

  • 推荐存放位置:

    bash 复制代码
    src/main/java/com/share/common/core/exception/handler/FileUploadExceptionHandler.java  
java 复制代码
import org.springframework.http.HttpStatus; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.ControllerAdvice; 
import org.springframework.web.bind.annotation.ExceptionHandler; 
import org.springframework.web.multipart.MaxUploadSizeExceededException; 
import com.share.common.core.exception.file.FileUploadException; 
 
@ControllerAdvice 
public class FileUploadExceptionHandler {
 
    /**
     * 捕获 Spring 原生文件大小超限异常 
     * 将其转换为您的业务异常体系 
     */
    @ExceptionHandler(MaxUploadSizeExceededException.class) 
    public ResponseEntity<String> handleSpringSizeLimit(MaxUploadSizeExceededException ex) {
        // 将 Spring 异常包装为业务自定义异常(保留原始异常栈)
        FileUploadException customEx = new FileUploadException("文件大小超出系统限制", ex.getCause()); 
        return handleBusinessException(customEx);
    }
 
    /**
     * 统一处理业务层的文件上传异常 
     */
    @ExceptionHandler(FileUploadException.class) 
    public ResponseEntity<String> handleBusinessException(FileUploadException ex) {
        String userFriendlyMsg = "上传失败:" + ex.getMessage(); 
        // 可根据 ex.getCause()  类型细化不同错误提示 
        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE) 
               .body(userFriendlyMsg);
    }
}
特性 原始 Spring 方案 适配后方案
异常类型 MaxUploadSizeExceededException FileUploadException
错误消息来源 框架默认提示 自定义业务提示
异常链保留 仅 Spring 异常栈 嵌套原始异常(ex.getCause() )
状态码控制 固定为 413 可动态调整(根据业务规则)
代码侵入性 直接处理框架异常 通过异常转换解耦业务与框架实现
相关推荐
绝无仅有11 小时前
某短视频大厂的真实面试解析与总结(一)
后端·面试·github
JavaGuide11 小时前
中兴开奖了,拿到了SSP!
后端·面试
绝无仅有12 小时前
腾讯MySQL面试深度解析:索引、事务与高可用实践 (二)
后端·面试·github
IT_陈寒12 小时前
SpringBoot 3.0实战:这套配置让我轻松扛住百万并发,性能提升300%
前端·人工智能·后端
熙客12 小时前
Java8:Lambda表达式
java·开发语言
小咕聊编程12 小时前
【含文档+PPT+源码】基于java web的篮球馆管理系统系统的设计与实现
java·开发语言
JaguarJack12 小时前
开发者必看的 15 个困惑的 Git 术语(以及它们的真正含义)
后端·php·laravel
后端小张12 小时前
【JAVA 进阶】Mybatis-Plus 实战使用与最佳实践
java·spring boot·spring·spring cloud·tomcat·mybatis·mybatis plus
崎岖Qiu12 小时前
【设计模式笔记07】:迪米特法则
java·笔记·设计模式·迪米特法则
Victor35613 小时前
Redis(91)Redis的访问控制列表(ACL)是如何工作的?
后端