Spring Boot 处理带文件表单的几种方式

zwjapple2025-12-12 18:08

方式 1：@RequestParam 接收文件

后端代码

java

复制代码 
@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();
}

前端代码

javascript

复制代码 
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 接收文件

后端代码

java

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

前端代码

javascript

复制代码 
// 与方式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 中）

后端代码

java

复制代码 
@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();
}

前端代码

javascript

复制代码 
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 混合（推荐）

后端代码

java

复制代码 
@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();
}

前端代码

javascript

复制代码 
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 + 文件

后端代码

java

复制代码 
@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();
}

前端代码

javascript

复制代码 
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：多文件上传

后端代码

java

复制代码 
// 方式 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();
}

前端代码

javascript

复制代码 
// 多个文件同名
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 原生方式

后端代码

java

复制代码 
@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：简单表单 + 单文件

java

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

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

java

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

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

java

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

文件验证最佳实践

自定义验证注解

java

复制代码 
@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）- 复杂数据结构

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

相关推荐
深紫色的三北六号2 小时前
大疆不同任务类型执行逻辑，上云API源码分析
java·无人机·springboot·大疆·上云api
期待のcode4 小时前
Thymeleaf模板引擎
java·html·springboot
期待のcode9 小时前
MyBatis-Plus通用枚举
java·数据库·后端·mybatis·springboot
武哥聊编程11 小时前
【从0带做】基于Springboot3+Vue3的生态养殖管理系统
java·学习·vue·毕业设计·springboot
她说..1 天前
Spring AOP场景2——数据脱敏（附带源码）
java·开发语言·java-ee·springboot·spring aop
邂逅星河浪漫2 天前
【Dify-Chatflow】简历优化助手实现+前后端分离式系统集成+Docker容器化部署）
java·docker·vue·springboot·dify·apifox
期待のcode3 天前
MyBatis-Plus通用Service
java·后端·mybatis·springboot
biyeyuanma3 天前
Windows 10 环境下使用 GraalVM JDK 21 + Spring Boot 3.5 构建 Native Image
springboot
热门推荐
01GitHub 镜像站点02【AutoGLM部署】本地私有化部署AI手机Agent03UV安装并设置国内源04【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）05Open-AutoGLM Windows 安装部署教程06Cursor 又偷偷更新，这个功能太实用：Visual Editor for Cursor Browser07安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）08Linux下V2Ray安装配置指南09BongoCat - 跨平台键盘猫动画工具10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）