解决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 可动态调整(根据业务规则)
代码侵入性 直接处理框架异常 通过异常转换解耦业务与框架实现
相关推荐
代码充电宝40 分钟前
LeetCode 算法题【简单】49. 字母异位词分组
java·算法·leetcode·面试·哈希算法
摸鱼的老谭1 小时前
Java学习之旅第一季-28:Java基础语法测试题
java·java基础测试
ruleslol1 小时前
SpringBoot12-JSON Web Token(JWT)
spring boot
Brookty1 小时前
深入解析Java类加载与实例化流程
java·开发语言·学习
Terio_my1 小时前
Spring Boot 缓存集成实践
spring boot·后端·缓存
karry_k2 小时前
JMM与Volatitle
后端
YSRM2 小时前
Leetcode+Java+图论+岛屿问题
java·算法·leetcode·图论
数字化顾问2 小时前
“AMQP协议深度解析:消息队列背后的通信魔法”之核心概念与SpringBoot落地实战
开发语言·后端·ruby
codecrafter1232 小时前
MATLAB中的while循环:从入门到精通的完整指南
java·数据库·其他·matlab
武子康3 小时前
大数据-115 - Flink DataStream Transformation Map、FlatMap、Filter 到 Window 的全面讲解
大数据·后端·flink