Spring Boot REST API能否接收包含Excel文件的JSON请求？

核心问题说明 #

JSON格式（application/json）无法直接传输二进制文件，你想同时传递普通参数和Excel文件的需求，必须用multipart/form-data类型的请求。你当前的实现混用了@RequestBody和MultipartFile，这是导致失败的主要原因——@RequestBody用于解析JSON/XML格式数据，而multipart/form-data需要用@ModelAttribute或@RequestPart来绑定参数。

正确实现步骤 #

1. 实体类调整 #

保留现有结构，按需添加示例中的searchKey和searchValue字段：

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@ToString
public class ExcelTemplate {
    private MultipartFile file;
    private String searchKey;
    private String searchValue;
}

2. 控制器方法修改 #

替换@RequestBody为@ModelAttribute，并明确仅接收multipart/form-data类型请求：

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import lombok.extern.slf4j.Slf4j;
import org.apache.poi.ss.usermodel.*;

import java.io.InputStream;

@RestController
@Slf4j
public class ExcelController {

    @PostMapping(
            value = "/api/testrequest",
            consumes = MediaType.MULTIPART_FORM_DATA_VALUE
    )
    public String handleExcelRequest(@ModelAttribute ExcelTemplate request) {
        // 获取文件与参数信息
        MultipartFile excelFile = request.getFile();
        String fileName = excelFile.getOriginalFilename();
        log.info("收到Excel文件：{}", fileName);
        log.info("搜索键：{}，搜索值：{}", request.getSearchKey(), request.getSearchValue());

        // 调用POI解析Excel
        parseExcel(excelFile);

        return "处理完成";
    }

    // Apache POI解析Excel示例方法
    private void parseExcel(MultipartFile excelFile) {
        try (InputStream inputStream = excelFile.getInputStream()) {
            // 自动兼容.xls和.xlsx格式
            Workbook workbook = WorkbookFactory.create(inputStream);
            Sheet sheet = workbook.getSheetAt(0); // 获取第一个工作表

            // 遍历行与单元格
            for (Row row : sheet) {
                for (Cell cell : row) {
                    String cellContent = switch (cell.getCellType()) {
                        case STRING -> cell.getStringCellValue();
                        case NUMERIC -> String.valueOf(cell.getNumericCellValue());
                        case BOOLEAN -> String.valueOf(cell.getBooleanCellValue());
                        default -> "";
                    };
                    log.info("单元格内容：{}", cellContent);
                }
            }
            workbook.close();
        } catch (Exception e) {
            log.error("解析Excel出错", e);
            throw new RuntimeException("Excel解析失败");
        }
    }
}

3. 正确请求方式 #

用Postman或curl发送请求：

• 请求方法：POST
• 请求地址：http://localhost:8080/api/testrequest
• 请求头：Content-Type: multipart/form-data
• 请求体选择form-data，添加三个参数：
  • 键searchKey，值填test1
  • 键searchValue，按需填写对应值
  • 键file，类型选File，上传目标Excel文件

常见问题排查 #

• Lombok不生效：检查项目依赖是否包含Lombok，同时确保IDE已开启Lombok支持。
• 文件接收为null：确认请求中文件参数的键名与实体类file字段一致，也可在file字段上添加@RequestPart("file")明确指定参数名。
• Apache POI依赖缺失：在pom.xml中添加以下依赖：

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.5</version>
</dependency>

内容的提问来源于stack exchange，提问作者FPS Bard