Vertx BodyHandler方法异常及头像上传目录、临时文件问题求助

我来帮你梳理这两个问题的解决方案，都是Vert.x文件上传中常见的坑，咱们一步步来：

一、修复错误的上传目录问题 #

Vert.x 默认会使用系统临时目录（比如Linux下的/tmp，Windows下的%TEMP%）存储上传的临时文件，如果你需要指定自定义目录，得在路由配置或文件上传选项里明确设置：

1. 在OpenAPI YAML中配置上传目录（结合OpenAPI3RouterFactory推荐方式） #

如果你的api.yaml定义了文件上传操作，可以通过x-vertx-options扩展字段指定目标目录：

paths:
  /upload/avatar:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar:
                  type: string
                  format: binary
      x-vertx-options:
        uploadsDirectory: "./uploads/avatars"  # 这里填写你的自定义上传目录
        maxFormSize: 10485760  # 可选，限制单文件大小（比如10MB）

2. 在HandlerVerticle中手动配置文件上传选项 #

如果YAML配置不生效，你可以在创建路由时，手动设置RouterOptions：

val router = OpenAPI3RouterFactory.create(vertx, "api.yaml").get()
// 全局配置上传目录与临时文件清理
router.route().handler(BodyHandler.create()
  .setUploadsDirectory("./uploads/avatars")
  .setDeleteUploadedFilesOnEnd(true))

重要提醒：Vert.x不会自动创建上传目录！你需要提前在启动代码中确保目录存在且有读写权限：

vertx.fileSystem().mkdirs("./uploads/avatars") { ar ->
  if (ar.failed()) {
    log.error("创建上传目录失败", ar.cause())
  }
}

二、解决临时文件未自动删除的问题 #

Vert.x的BodyHandler默认不会自动删除上传的临时文件，需要显式开启这个功能：

1. 通过BodyHandler开启自动删除 #

在HandlerVerticle中添加BodyHandler时，启用setDeleteUploadedFilesOnEnd(true)即可：

router.post("/upload/avatar").handler(BodyHandler.create()
  .setUploadsDirectory("./uploads/avatars")
  .setDeleteUploadedFilesOnEnd(true))
  .handler { ctx ->
    // 获取上传的文件
    val fileUpload = ctx.fileUploads().firstOrNull() ?: run {
      ctx.response().setStatusCode(400).end("未上传头像文件")
      return@handler
    }
    // 这里可以将临时文件移动到永久存储位置（如果业务需要）
    vertx.fileSystem().copy(fileUpload.uploadedFileName(), "./permanent/avatars/${fileUpload.fileName()}") { ar ->
      if (ar.succeeded()) {
        ctx.response().end("头像上传成功")
      } else {
        ctx.response().setStatusCode(500).end("保存头像失败")
      }
    }
  }

2. 手动删除临时文件（自动配置失效时的兜底方案） #

如果开启自动删除后仍有文件残留，可以在请求处理完成后（无论成功或失败）手动清理：

router.post("/upload/avatar").handler(BodyHandler.create())
  .handler { ctx ->
    val fileUploads = ctx.fileUploads()
    // 处理上传逻辑...

    // 请求结束后删除所有临时文件
    ctx.response().endHandler {
      fileUploads.forEach { upload ->
        vertx.fileSystem().delete(upload.uploadedFileName()) { ar ->
          if (ar.failed()) {
            log.warn("删除临时文件失败: ${upload.uploadedFileName()}", ar.cause())
          }
        }
      }
    }
  }

常见排查点 #

• 优先使用绝对路径配置上传目录，相对路径是相对于Vert.x进程的启动目录，容易因部署路径变化出错，比如/opt/app/uploads/avatars。
• 确认BodyHandler是否正确添加到路由链中，没有被其他拦截器覆盖或跳过。
• 查看Vert.x日志，是否存在目录创建失败、文件权限不足的报错信息，这往往是目录问题的根源。

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