Spring Multipart上传接口无法访问，Postman请求报404问题排查

针对你遇到的Spring Multipart上传接口返回404的问题，结合代码和操作场景，从以下方向逐一排查：

1. 确认请求路径完全匹配 #

控制器前缀为/v1/finance/ratecard，接口路径是/uploadFile，完整请求URL应为：

POST /v1/finance/ratecard/uploadFile

• 检查Postman/curl中的URL是否存在大小写错误（Spring MVC默认路径大小写敏感，uploadfile和uploadFile会被视为不同路径）
• 确认没有网关、反向代理额外添加的前缀导致路径不匹配

2. 修正@PostMapping的consumes配置 #

将接口的consumes明确指定为multipart/form-data（这是文件上传的标准Content-Type），修改后的代码：

@PostMapping(value = "/uploadFile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@ResponseStatus(HttpStatus.OK)
public void uploadExcelFile(@RequestPart("file") MultipartFile file, @RequestPart("meta-data") UploadRateCardRequest uploadRateCardRequest) { 
  // 业务逻辑
}

注：multipart/mixed用于混合不同类型二进制内容，不是表单文件上传的标准类型，无需配置

3. 检查Postman的请求构造是否正确 #

Postman必须按以下步骤构造请求：

• 选择POST方法，填入正确URL
• 在Body选项卡选择form-data
• 添加第一个键值对：
  • Key：file
  • Type：切换为File（默认是Text，必须修改）
  • Value：选择本地Excel/CSV文件
• 添加第二个键值对：
  • Key：meta-data
  • Type：Raw
  • 格式选择JSON（右侧下拉框）
  • 填入UploadRateCardRequest对应的JSON结构（例如{"field1": "value1", "field2": 123}）

关键：meta-data作为@RequestPart参数，必须以JSON格式作为独立的multipart part传输，不能直接放在form文本字段中

4. 排查Spring MVC请求映射日志 #

开启Spring MVC的DEBUG级别日志，查看请求匹配过程：

• 在application.yml中添加配置：

logging:
  level:
    org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping: DEBUG

启动服务后重新发送请求，查看日志中Looking up handler method for path /v1/finance/ratecard/uploadFile相关记录，确认接口是否被Spring正确注册，以及是否存在匹配失败原因（如请求方法、Content-Type不匹配）

5. 检查拦截器/过滤器是否拦截请求 #

如果项目有自定义拦截器或过滤器，确认它们没有拦截/v1/finance/ratecard/uploadFile路径的POST请求，也没有对multipart类型请求做特殊限制

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