单个POST请求上传带元数据多文件，接口调用遇参数异常问题

嘿，我刚好之前踩过一模一样的坑！咱们来一步步把这个多文件带元数据上传的问题解决掉：

你的Attachment类定义完全ok，@Getter @Setter @NoArgsConstructor这些注解都加对了，不用调整。

方案一：用@ModelAttribute接收列表（最适合form-data场景） #

这是我最常用的方式，只要参数命名对了，Spring就能自动把form-data里的字段组装成List<Attachment>。

Controller代码：

@PostMapping("/upload")
public ResponseEntity<String> uploadAttachments(@ModelAttribute List<Attachment> attachments) {
    // 这里可以处理每个附件，比如打印信息验证
    for (Attachment attachment : attachments) {
        System.out.println("附件名称：" + attachment.getName());
        System.out.println("描述：" + attachment.getDescription());
        System.out.println("文件名：" + attachment.getFile().getOriginalFilename());
    }
    return ResponseEntity.ok("上传成功！");
}

Postman关键操作（别踩这个坑！） #

你之前拿到空列表，90%是因为参数命名没符合Spring的列表绑定规则。必须按attachments[index].字段名的格式来填键名：

• 第一个附件的参数组：
  • 键：attachments[0].file，类型选「File」，选择要上传的文件
  • 键：attachments[0].name，类型选「Text」，填写附件名称
  • 键：attachments[0].description，类型选「Text」，填写描述
• 第二个附件的参数组：
  • 键：attachments[1].file，类型选「File」，选择第二个文件
  • 键：attachments[1].name，类型选「Text」，填写第二个名称
  • 键：attachments[1].description，类型选「Text」，填写第二个描述

这样Spring才能准确把每组参数映射到对应的Attachment对象，再拼成列表返回给你。

方案二：用@RequestPart接收（适合复杂元数据场景） #

如果你的元数据是JSON格式，或者想更清晰地分离文件和元数据，可以用这个方式。不过请求构造会稍微复杂一点：

Controller代码：

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadAttachments(
        @RequestPart("attachments") List<Attachment> attachments) {
    // 处理逻辑同上
    return ResponseEntity.ok("上传成功！");
}

Postman构造方式 #

每个Attachment需要作为一个独立的Part：

• 对于每个附件，添加一个Part，名称设为attachments，然后把元数据写成JSON字符串，同时在同一个Part里添加文件（不过部分版本的Postman可能不太支持这种混合，所以更推荐方案一）。

• 提示“参数attachment未找到”：大概率是Controller参数名和Postman的键名不匹配，比如Controller用的是复数attachments，你Postman里写的是单数attachment，或者完全没按索引格式命名。
• @ModelAttribute拿到空列表：和上面一样，参数命名不符合Spring的列表绑定规则，必须用参数名[index].字段名的格式。
• @RequestPart的坑：如果用这个注解，要确保每个Part的名称和注解里的value一致；如果元数据是JSON，要把Part的Content-Type设为application/json，文件Part的Content-Type设为对应文件的MIME类型（比如image/jpeg）。

内容的提问来源于stack exchange，提问作者Lakshmikant Deshpande