这是一个 Spring Boot 中用于定义 RESTful 接口的注解组合，作用是**声明一个处理 HTTP POST 请求的控制器方法，专门接收 `multipart/form-data` 类型的文件上传请求（通常包含文件 + 其他表单字段）**。下面逐部分详细解释： --- ### ✅ 注解分解说明： #### 1. `@PostMapping` - 是 Spring MVC 提供的 **HTTP 方法映射注解**，等价于 `@RequestMapping(method = RequestMethod.POST)`。 - 表示该方法只响应 **HTTP POST 请求**。 #### 2. `value = "/importAuxiliaryEquipmentData"` - 指定该接口的 **请求路径（URI）**，即客户端需向 `/importAuxiliaryEquipmentData` 发起 POST 请求。 - 示例：`POST http://localhost:8080/importAuxiliaryEquipmentData` #### 3. `consumes = MediaType.MULTIPART_FORM_DATA_VALUE` - `consumes` 指定该接口**能接收的请求体（Request Body）的 MIME 类型**。 - `MediaType.MULTIPART_FORM_DATA_VALUE` 的值是字符串 `"multipart/form-data"`。 - ✅ 这是 HTML 文件上传表单（`<form enctype="multipart/form-data">`）的标准 Content-Type。 - ⚠️ 此设置具有**强约束性**：如果客户端发送的 `Content-Type` 不是 `multipart/form-data`（如 `application/json`），Spring 会直接返回 `415 Unsupported Media Type` 错误，**不会进入方法体**。 > 💡 补充：`multipart/form-data` 的典型结构是将多个字段（包括文本字段和文件字段）按边界（boundary）分隔，例如： > ``` > POST /importAuxiliaryEquipmentData HTTP/1.1 > Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW > > ------WebKitFormBoundary7MA4YWxkTrZu0gW > Content-Disposition: form-data; name="file"; filename="data.xlsx" > Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet > > <binary content of Excel file> > ------WebKitFormBoundary7MA4YWxkTrZu0gW > Content-Disposition: form-data; name="category" > > auxiliary > ------WebKitFormBoundary7MA4YWxkTrZu0gW-- > ``` --- ### ✅ 完整典型用法（含参数绑定） ```java @PostMapping(value = "/importAuxiliaryEquipmentData", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public ResponseEntity<String> importAuxiliaryEquipmentData( @RequestParam("file") MultipartFile file, // 必须匹配 form 中 name="file" @RequestParam(value = "category", required = false) String category, @RequestParam(value = "overwrite", defaultValue = "false") boolean overwrite) { if (file.isEmpty()) { return ResponseEntity.badRequest().body("文件不能为空"); } try { // ✅ 处理上传的 Excel 文件（例如用 Apache POI 解析） List<AuxiliaryEquipment> equipments = parseExcel(file.getInputStream()); equipmentService.batchImport(equipments, overwrite); return ResponseEntity.ok("导入成功，共 " + equipments.size() + " 条数据"); } catch (Exception e) { log.error("导入辅助设备数据失败", e); return ResponseEntity.status(500).body("导入失败：" + e.getMessage()); } } ``` #### 🔍 关键点说明： - `@RequestParam("file") MultipartFile file`： 绑定 HTML 表单中 `name="file"` 的 `<input type="file">` 字段；Spring 自动将 `multipart/form-data` 中的文件部分解析为 `MultipartFile` 对象。 - `@RequestParam` 也可绑定普通文本字段（如 `category`, `overwrite`）。 - `MultipartFile` 提供了 `getInputStream()`, `getOriginalFilename()`, `getSize()`, `transferTo(File)` 等实用方法。 - Spring Boot 默认已配置 `MultipartResolver`（如 `StandardServletMultipartResolver`），无需额外配置（但需注意 `spring.servlet.multipart.*` 配置项，如大小限制）。 --- ### ⚠️ 常见注意事项： | 问题 | 解决方案 | |------|----------| | ❌ 报错 `400 Bad Request` 或 `Required request part 'file' is not present` | 检查前端是否正确设置了 `enctype="multipart/form-data"`，且 `<input name="file">` 的 `name` 与 `@RequestParam("file")` 一致 | | ❌ 报错 `413 Payload Too Large` | 在 `application.yml` 中增大上传限制：<br>`spring.servlet.multipart.max-file-size: 50MB`<br>`spring.servlet.multipart.max-request-size: 50MB` | | ❌ `MultipartFile` 为 null | 确保未同时使用 `@RequestBody`（它与 `@RequestParam` 冲突）；`multipart/form-data` **不能用 `@RequestBody` 接收** | ---