Vert.x4.1.0配合OpenAPI3.0.3发multipart/form-data文件报400错误

核心原因 #

Vert.x 4.x对OpenAPI请求校验做了大幅调整，3.x版本默认自动注入Multipart解析处理器、校验逻辑相对宽松，4.x版本改为需要开发者显式配置相关能力，且默认启用严格校验规则，未满足规则的请求会在进入业务handler前直接返回400。
常见触发400的具体场景：

• 没有显式向OpenAPI Router中注入BodyHandler，导致multipart/form-data格式的请求无法被正常解析
• 校验逻辑默认启用了额外字段拦截，请求中携带了yaml未声明的表单字段就会被拦截
• 未显式声明multipart字段的编码规则，4.x严格校验字段content-type与schema预期不匹配

修复步骤 #

1. 显式注入Multipart解析处理器 #

在初始化RouterBuilder时，先全局注入配置好的BodyHandler，开启multipart解析能力，示例代码：

// 按需配置BodyHandler参数，包括上传文件存储目录、单请求大小上限等
BodyHandler bodyHandler = BodyHandler.create()
        .setUploadsDirectory("/tmp/vertx-uploads")
        .setBodyLimit(50 * 1024 * 1024); // 示例限制50MB上传大小
// 注入到RouterBuilder的全局根处理器
routerBuilder.rootHandler(bodyHandler);

2. 调整校验规则适配业务场景 #

如果业务允许请求携带未在yaml中声明的额外表单字段，可以关闭额外字段校验开关：

// 配置校验规则
SchemaValidatorOptions validatorOptions = new SchemaValidatorOptions()
        .setAdditionalPropertiesValidationEnabled(false);
OpenAPIRouterOptions routerOptions = new OpenAPIRouterOptions()
        .setSchemaValidatorOptions(validatorOptions);
// 用自定义配置初始化RouterBuilder
RouterBuilder routerBuilder = RouterBuilder.create(vertx, yourOpenAPIInstance, routerOptions);

3. 补充OpenAPI配置避免字段匹配歧义 #

在yaml的multipart定义中补充必填字段声明、编码规则，消除校验逻辑的匹配歧义：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        required:
          - file
          - ggenPath
        properties:
          file:
            type: string
            format: binary
          ggenPath:
            type: string
      encoding:
        file:
          # 按需填写实际支持的文件类型，多个用逗号分隔
          contentType: application/octet-stream,image/png,image/jpg,text/plain
        ggenPath:
          contentType: text/plain

4. 临时关闭校验定位问题 #

如果上述配置后仍然返回400，可以先临时关闭请求校验，确认是否是校验逻辑导致的拦截：

routerOptions.setRequestValidationEnabled(false);

如果关闭校验后请求可以正常进入业务handler，再逐步排查校验规则的适配问题即可。

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