Micronaut 如何通过Postman、curl、Swagger传递@Body MultipartBody参数

Micronaut的多部分请求参数绑定存在明确的规则边界，触发Required Body [file] not specified报错的核心原因有两个：

1. 代码定义层面的认知错位：@Body注解的作用是标记需要从整个请求体（JSON、纯文本等单结构内容）中绑定的参数，而MultipartBody类型本身是对整个多部分请求所有表单字段的集合封装。给MultipartBody类型参数加上@Body，再把参数命名为file，会让框架误以为要寻找名为file的独立请求体，而非多部分表单中的同名字段，最终触发参数缺失的报错。
2. 依赖缺失问题：如果项目没有引入Micronaut官方的多部分解析组件，框架根本无法识别multipart/form-data类型的请求，会把多部分请求当成普通的单结构请求处理，自然无法正确绑定参数。

在已经正确引入多部分解析依赖、不改控制器代码的前提下，客户端不需要额外调整传参逻辑，只要发送标准多部分格式的请求即可：

curl 命令写法 #

直接使用标准的表单上传语法，不需要添加自定义请求头：

curl --location --request POST 'http://localhost:8080/product' \
--form 'file=@"/Users/macbook/Downloads/anand 001.jpg"'

注意：如果路径中包含空格，需要确保路径被正确包裹，避免shell解析错误。

Postman 操作步骤 #

• 新建POST请求，填入接口地址http://localhost:8080/product
• 打开Body配置页，勾选form-data选项
• 在表单Key栏输入file，将右侧的字段类型从默认的Text切换为File，选择本地需要上传的图片文件
• 不要手动修改请求头的Content-Type配置，由Postman自动生成带boundary分隔标识的多部分请求头
• 直接发送请求即可正常访问接口

Swagger 集成场景 #

• 确保项目正确集成Micronaut的OpenAPI组件，多部分解析配置正常生效
• 在生成的Swagger调试页面找到/product的POST接口
• 在表单参数区域自动识别到文件上传字段，选择本地文件后直接发起请求即可
• 不要在Swagger的请求头配置区手动修改Content-Type值，避免破坏多部分请求的标准结构

原控制器的参数定义存在语义偏差，更推荐按照Micronaut的多部分设计逻辑调整代码，从根源避免绑定错误：

1. 如果需要拿到整个多部分请求的所有内容，直接移除参数上的@Body注解，框架会自动识别MultipartBody类型并注入，不需要额外标记：

@Controller("/product")
public class ProductController {

    @Post(consumes = MediaType.MULTIPART_FORM_DATA, produces = MediaType.TEXT_PLAIN)
    public String post(MultipartBody multipartBody){
        // 从集合中取出file字段对应的上传文件
        Optional<CompletedFileUpload> uploadedFile = multipartBody.getUploadedFile("file");
        return "This is multipost";
    }
}

2. 如果仅需要接收名为file的单个上传文件，可以进一步简化绑定逻辑，使用@Part注解直接映射表单字段：

@Post(consumes = MediaType.MULTIPART_FORM_DATA, produces = MediaType.TEXT_PLAIN)
public String post(@Part("file") CompletedFileUpload file){
    // 直接操作上传的文件对象
    return "This is multipost";
}

• 必须确保项目引入了Micronaut官方的多部分解析依赖，缺失依赖的情况下，无论客户端传参格式多么标准，都无法正常解析多部分请求
• 多部分请求的Content-Type必须包含随机生成的boundary分隔标识，手动固定的multipart/form-data值会导致服务端无法分割请求内容块
• MultipartBody是多部分请求的全量字段集合容器，不是单个文件字段的类型，不要和单文件上传的类型混淆

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