Spring Boot 处理带文件表单的方式汇总

更新时间：2025年12月12日 11:54:51 作者：zwjapple

本文详细介绍了六种处理文件上传的方式,包括@RequestParam、@RequestPart、@ModelAttribute、@ModelAttribute+@RequestPart、@RequestPart接收JSON和HttpServletRequest原生方式,每种方式都有其特点和适用场景,感兴趣的朋友跟随小编一起看看吧

方式 1：@RequestParam接收文件

后端代码

@PostMapping("/upload1")
public Result upload1(
    @RequestParam("file") MultipartFile file,
    @RequestParam("name") String name,
    @RequestParam("age") Integer age
) {
    // 处理文件
    String filename = file.getOriginalFilename();
    long size = file.getSize();
    return Result.success();
}

前端代码

const formData = new FormData();
formData.append('file', fileBlob);
formData.append('name', 'John');
formData.append('age', '25');
fetch('/api/upload1', {
    method: 'POST',
    body: formData
});

特点

✅ 最简单直接
✅ 适合少量参数
❌ 参数多时代码冗长
❌ 无法使用 @Valid 统一验证

方式 2：@RequestPart接收文件

后端代码

@PostMapping("/upload2")
public Result upload2(
    @RequestPart("file") MultipartFile file,
    @RequestPart("name") String name,
    @RequestPart("age") Integer age
) {
    return Result.success();
}

前端代码

// 与方式1相同
const formData = new FormData();
formData.append('file', fileBlob);
formData.append('name', 'John');
formData.append('age', '25');

特点

✅ 语义更明确（专为 multipart 设计）
✅ 可以指定每个 part 的 Content-Type
❌ 与 @RequestParam 功能类似，参数多时也冗长

方式 3：@ModelAttribute接收（文件在 DTO 中）

后端代码

@Data
public class UploadDTO {
    @NotNull(message = "文件不能为空")
    private MultipartFile file;
    @NotBlank(message = "姓名不能为空")
    private String name;
    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能为负数")
    private Integer age;
    private String description;
}
@PostMapping("/upload3")
public Result upload3(@Valid @ModelAttribute UploadDTO dto) {
    MultipartFile file = dto.getFile();
    // 额外检查文件是否为空
    if (file.isEmpty()) {
        throw new BusinessException("文件内容不能为空");
    }
    return Result.success();
}

前端代码

const formData = new FormData();
formData.append('file', fileBlob);
formData.append('name', 'John');
formData.append('age', '25');
formData.append('description', '这是描述');
fetch('/api/upload3', {
    method: 'POST',
    body: formData
});

特点

✅ 代码简洁，参数封装在 DTO 中
✅ 支持 @Valid 统一验证
✅ DTO 可复用
✅ 适合传统表单提交
❌ 只支持扁平数据结构

方式 4：@ModelAttribute+@RequestPart混合（推荐）

后端代码

@Data
public class LoanRequest {
    @NotBlank(message = "姓名不能为空")
    private String name;
    @NotNull(message = "贷款金额不能为空")
    private BigDecimal amount;
    @NotBlank(message = "贷款类型不能为空")
    private String loanType;
    private String description;
}
@PostMapping("/upload4")
public Result upload4(
    @Valid @ModelAttribute LoanRequest request,
    @RequestPart(value = "propProofDocs", required = false) MultipartFile file
) {
    // 文件验证
    if (file == null || file.isEmpty()) {
        throw new BusinessException("财产证明文件不能为空");
    }
    return Result.success();
}

前端代码

const formData = new FormData();
// 普通字段
formData.append('name', 'John');
formData.append('amount', '100000');
formData.append('loanType', 'mortgage');
formData.append('description', '购房贷款');
// 文件单独处理
formData.append('propProofDocs', fileBlob);
fetch('/api/upload4', {
    method: 'POST',
    body: formData
});

特点

✅ 最灵活，业务数据和文件分离
✅ 支持 DTO 验证
✅ 文件验证可以单独处理
✅ 适合复杂业务场景
✅ 推荐用于大多数项目

方式 5：@RequestPart接收 JSON + 文件

后端代码

@Data
public class UserInfo {
    @NotBlank(message = "姓名不能为空")
    private String name;
    @NotNull(message = "年龄不能为空")
    private Integer age;
    private List<String> hobbies;  // 支持复杂结构
    private Address address;  // 支持嵌套对象
}
@Data
class Address {
    private String city;
    private String street;
}
@PostMapping("/upload5")
public Result upload5(
    @Valid @RequestPart("userInfo") UserInfo userInfo,
    @RequestPart("avatar") MultipartFile avatar
) {
    return Result.success();
}

前端代码

const userInfo = {
    name: 'John',
    age: 25,
    hobbies: ['reading', 'coding'],
    address: {
        city: 'Beijing',
        street: 'Chang\'an Ave'
    }
};
const formData = new FormData();
// 将 JSON 对象转为 Blob，指定 Content-Type
formData.append('userInfo', new Blob([JSON.stringify(userInfo)], {
    type: 'application/json'
}));
formData.append('avatar', fileBlob);
fetch('/api/upload5', {
    method: 'POST',
    body: formData
});

特点

✅ 支持复杂 JSON 结构（数组、嵌套对象）
✅ 前后端分离友好
✅ RESTful 风格
❌ 前端需要额外构造 JSON Blob
✅ 推荐用于复杂数据结构

方式 6：多文件上传

后端代码

// 方式 6.1：数组接收
@PostMapping("/upload6-1")
public Result upload6(
    @RequestParam("files") MultipartFile[] files,
    @RequestParam("description") String description
) {
    for (MultipartFile file : files) {
        // 处理每个文件
    }
    return Result.success();
}
// 方式 6.2：List 接收
@PostMapping("/upload6-2")
public Result upload6(
    @RequestParam("files") List<MultipartFile> files,
    @RequestParam("description") String description
) {
    files.forEach(file -> {
        // 处理每个文件
    });
    return Result.success();
}
// 方式 6.3：不同字段多个文件
@PostMapping("/upload6-3")
public Result upload6(
    @RequestPart("idCard") MultipartFile idCard,
    @RequestPart("bankCard") MultipartFile bankCard,
    @RequestPart("propProof") MultipartFile propProof
) {
    return Result.success();
}

前端代码

// 多个文件同名
const formData = new FormData();
files.forEach(file => {
    formData.append('files', file);  // 注意：相同的 key
});
formData.append('description', '批量上传');
// 多个文件不同名
const formData2 = new FormData();
formData2.append('idCard', idCardFile);
formData2.append('bankCard', bankCardFile);
formData2.append('propProof', propProofFile);

方式 7：HttpServletRequest 原生方式

后端代码

@PostMapping("/upload7")
public Result upload7(HttpServletRequest request) throws Exception {
    // 判断是否为 multipart 请求
    if (!ServletFileUpload.isMultipartContent(request)) {
        throw new BusinessException("请求格式错误");
    }
    // 使用 Apache Commons FileUpload
    ServletFileUpload upload = new ServletFileUpload();
    List<FileItem> items = upload.parseRequest(new ServletRequestContext(request));
    for (FileItem item : items) {
        if (item.isFormField()) {
            // 普通字段
            String fieldName = item.getFieldName();
            String value = item.getString("UTF-8");
        } else {
            // 文件字段
            String filename = item.getName();
            InputStream inputStream = item.getInputStream();
            // 处理文件
        }
    }
    return Result.success();
}

特点

✅ 完全控制
✅ 适合特殊需求
❌ 代码复杂
❌ 不推荐常规使用

完整对比表

方式	适用场景	代码简洁度	验证支持	复杂结构	推荐度
@RequestParam	简单场景，少量参数	⭐⭐	❌	❌	⭐⭐
@RequestPart	与 @RequestParam 类似	⭐⭐	❌	❌	⭐⭐
@ModelAttribute（文件在DTO）	传统表单，扁平数据	⭐⭐⭐⭐	✅	❌	⭐⭐⭐⭐
@ModelAttribute + @RequestPart	通用场景	⭐⭐⭐⭐⭐	✅	⭐	⭐⭐⭐⭐⭐
@RequestPart (JSON)	复杂JSON结构	⭐⭐⭐	✅	✅	⭐⭐⭐⭐
多文件上传	批量上传	⭐⭐⭐	⭐	❌	⭐⭐⭐⭐
HttpServletRequest	特殊需求	⭐	❌	✅	⭐

实际项目推荐

场景 1：简单表单 + 单文件

@PostMapping("/simple")
public Result simple(
    @Valid @ModelAttribute SimpleDTO dto,
    @RequestPart("file") MultipartFile file
) { }

场景 2：复杂业务数据 + 多文件

@PostMapping("/complex")
public Result complex(
    @Valid @RequestPart("data") ComplexDTO data,  // JSON
    @RequestPart("idCard") MultipartFile idCard,
    @RequestPart("bankCard") MultipartFile bankCard
) { }

场景 3：可选文件 + 表单验证

@PostMapping("/optional")
public Result optional(
    @Valid @ModelAttribute FormDTO form,
    @RequestPart(value = "attachment", required = false) MultipartFile file
) {
    if (file != null && !file.isEmpty()) {
        // 处理文件
    }
}

文件验证最佳实践

自定义验证注解

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = FileValidator.class)
public @interface ValidFile {
    String message() default "文件不合法";
    long maxSize() default 10 * 1024 * 1024;  // 10MB
    String[] allowedTypes() default {};  // {"image/jpeg", "image/png"}
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}
// 验证器
public class FileValidator implements ConstraintValidator<ValidFile, MultipartFile> {
    private long maxSize;
    private String[] allowedTypes;
    @Override
    public void initialize(ValidFile annotation) {
        this.maxSize = annotation.maxSize();
        this.allowedTypes = annotation.allowedTypes();
    }
    @Override
    public boolean isValid(MultipartFile file, ConstraintValidatorContext context) {
        if (file == null || file.isEmpty()) {
            return false;
        }
        // 检查大小
        if (file.getSize() > maxSize) {
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(
                "文件大小不能超过 " + (maxSize / 1024 / 1024) + "MB"
            ).addConstraintViolation();
            return false;
        }
        // 检查类型
        if (allowedTypes.length > 0) {
            String contentType = file.getContentType();
            boolean typeMatched = Arrays.asList(allowedTypes).contains(contentType);
            if (!typeMatched) {
                context.disableDefaultConstraintViolation();
                context.buildConstraintViolationWithTemplate(
                    "只支持以下文件类型: " + String.join(", ", allowedTypes)
                ).addConstraintViolation();
                return false;
            }
        }
        return true;
    }
}
// 使用
@PostMapping("/validated")
public Result validated(
    @Valid @ModelAttribute FormDTO form,
    @ValidFile(
        maxSize = 5 * 1024 * 1024,  // 5MB
        allowedTypes = {"image/jpeg", "image/png", "application/pdf"},
        message = "文件不符合要求"
    )
    @RequestPart("file") MultipartFile file
) {
    return Result.success();
}

总结

日常开发推荐：

🥇 方式 4（@ModelAttribute + @RequestPart）- 最灵活通用
🥈 方式 3（@ModelAttribute 包含文件）- 简单场景
🥉 方式 5（@RequestPart JSON）- 复杂数据结构

根据实际业务需求选择合适的方式，优先考虑代码的可维护性和可读性！

到此这篇关于Spring Boot 处理带文件表单的方式汇总的文章就介绍到这了,更多相关springboot文件表单内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

java字符串遍历以及统计字符串中各类字符
这篇文章主要为大家详细介绍了java字符串遍历以及字符串中各类字符统计，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2018-03-03
springboot如何通过注解实现多线程
在Spring Boot中实现异步方法时,如果直接在调用类中使用`@Async`注解,可能会导致异步失败,正确的做法是将实现异步的方法放在一个独立的类中,并通过Spring生成的bean来调用这个方法,这样可以成功实现异步
2024-12-12
Java Selenium实现多窗口切换的示例代码
这篇文章主要介绍了Java Selenium实现多窗口切换的示例代码，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-09-09
如何在springBoot下搭建日志框架
这篇文章主要介绍了如何在springBoot下搭建日志框架,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-06-06
java如何使用jdbc连接TDSQL数据库
TDSQL是腾讯打造的一款分布式数据库产品,具备强一致高可用、全球部署架构、分布式水平扩展、高性能、企业级安全等特性,本文我们就来看看Java如何使用jdbc连接TDSQL数据库吧
2025-06-06
Mybatis-plus自动填充不生效或自动填充数据为null原因及解决方案
本文主要介绍了Mybatis-plus自动填充不生效或自动填充数据为null原因及解决方案，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2022-05-05
一篇文章带你入门Java字面量和常量
这篇文章主要介绍了探究Java的常量，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2021-08-08
Java方法重载和重写原理区别解析
这篇文章主要介绍了Java方法重载和重写原理区别解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-03-03
在SpringBoot中该如何配置拦截器
今天给大家带来的是关于SpringBoot的相关知识,文章围绕在SpringBoot中该如何配置拦截器展开,文中有非常详细的介绍及代码示例,需要的朋友可以参考下
2021-06-06
Java实现随机验证码具体代码
这篇文章主要为大家详细介绍了Java实现随机验证码具体代码，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2017-01-01