解决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 可动态调整(根据业务规则)
代码侵入性 直接处理框架异常 通过异常转换解耦业务与框架实现
相关推荐
一枚小小程序员哈1 小时前
基于asp.net 的在线餐饮订餐系统的设计与实现/基于c#的网上订餐系统/餐厅管理系统
后端·c#·asp.net
cyforkk2 小时前
ArrayList vs LinkedList:底层原理与实战选择指南
java
孟婆来包棒棒糖~4 小时前
泛型与反射
java·反射·javase·泛型
A尘埃4 小时前
Spring Event 企业级应用
java·spring·event
YuTaoShao6 小时前
【LeetCode 热题 100】139. 单词拆分——(解法一)记忆化搜索
java·算法·leetcode·职场和发展
Best_Liu~6 小时前
策略模式 vs 适配器模式
java·spring boot·适配器模式·策略模式
你的人类朋友6 小时前
【Node&Vue】什么是ECMAScript?
前端·javascript·后端
direction__7 小时前
Java Main无法初始化主类的原因与解决方法(VsCode工具)
java·vscode
帧栈7 小时前
开发避坑指南(29):微信昵称特殊字符存储异常修复方案
java·mysql
每天的每一天7 小时前
面试可能问到的问题思考-Redis
java