Spring WebFlux 文件上传：如何返回上传的文件名

本文探讨了如何在 spring WebFlux 文件上传场景中，将控制器方法的返回类型从默认的 Mono<void> 更改为返回已上传文件的名称。通过深入解析 flatMap 和 thenReturn 操作符，文章提供了一个清晰的解决方案和代码示例，帮助开发者在完成文件存储后，能够向客户端提供文件名称作为响应，从而提升API的实用性。

Spring WebFlux 文件上传基础

spring webflux 提供了一套基于 reactor 的非阻塞式编程模型，非常适合处理高并发的 i/o 密集型任务，如文件上传。在 webflux 中，文件上传通常通过 filepart 接口进行处理，它代表了一个上传文件的一部分。

一个典型的文件上传控制器方法可能如下所示，它接收一个 Flux<FilePart>，然后将每个文件保存到指定路径：

import org.springframework.http.codec.multipart.FilePart; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestPart; import org.springframework.web.bind.annotation.RestController; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono;  import Java.nio.file.Path; import java.nio.file.Paths;  @RestController public class FileUploadController {      private final Path basePath = Paths.get("./uploads"); // 假设文件存储的基础路径      @PostMapping("file/multi")     public Mono<Void> upload(@RequestPart("files") Flux<FilePart> partFlux) {         return partFlux                 .doOnNext(fp -> System.out.println("Uploading: " + fp.filename()))                 .flatMap(fp -> fp.transferTo(basePath.resolve(fp.filename())))                 .then(); // 默认返回 Mono<Void>     } }

在上述代码中，flatMap(fp -> fp.transferTo(basePath.resolve(fp.filename()))) 会将每个 FilePart 传输到目标位置。transferTo 方法本身返回 Mono<Void>，表示操作完成但没有返回任何值。最后的 .then() 操作符会将整个 Flux<FilePart> 的处理结果聚合成一个 Mono<Void>，表示所有文件都已处理完毕。这种方式适用于客户端只关心文件是否成功上传，而不关心具体文件名的场景。

返回上传的文件名

然而，在许多实际应用中，客户端可能需要知道上传成功的文件名，例如用于显示给用户、生成下载链接或进行后续操作。此时，仅仅返回 Mono<Void> 就不够了。我们需要修改控制器方法，使其在文件上传完成后，返回相应的文件名。

问题的关键在于如何在 transferTo 返回 Mono<Void> 之后，继续将文件名作为响应值传递下去。解决方案是利用 Reactor 的 flatMap 操作符来转换流，并在 transferTo 完成后，通过 thenReturn() 或 then(Mono.just()) 返回我们想要的值。

Brizy

Brizy是一个面向机构和 SaaS 的白标网站生成器，可以在几分钟内创建网站页面。

166

查看详情

考虑以下修改后的代码：

import org.springframework.http.codec.multipart.FilePart; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestPart; import org.springframework.web.bind.annotation.RestController; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono;  import java.nio.file.Path; import java.nio.file.Paths; import java.util.List; import java.util.stream.Collectors;  @RestController public class FileUploadController {      private final Path basePath = Paths.get("./uploads"); // 假设文件存储的基础路径      @PostMapping("file/multi-return-names")     public Mono<List<String>> uploadAndReturnNames(@RequestPart("files") Flux<FilePart> partFlux) {         return partFlux                 .flatMap(fp -> {                     // 获取原始文件名                     String originalFilename = fp.filename();                     // 构建完整的文件路径                     Path targetPath = basePath.resolve(originalFilename);                      // 执行文件传输，并在传输完成后返回文件名                     // transferTo(targetPath) 返回 Mono<Void>                     // thenReturn(originalFilename) 会在 Mono<Void> 完成后，发出 originalFilename                     return fp.transferTo(targetPath)                              .thenReturn(originalFilename);                 })                 .collectList(); // 将所有上传的文件名收集到一个 List<String> 中     } }

代码解析：

1. @PostMapping(“file/multi-return-names”): 控制器方法的路径。
2. public Mono<List<String>> uploadAndReturnNames(…): 方法的返回类型变为 Mono<List<String>>，表示它将返回一个包含所有上传文件名的列表的响应式流。
3. flatMap(fp -> { … }): 对于 Flux<FilePart> 中的每一个 FilePart (fp)，我们执行以下操作：
   • String originalFilename = fp.filename();: 获取当前文件的原始文件名。
   • Path targetPath = basePath.resolve(originalFilename);: 构建文件的完整存储路径。
   • fp.transferTo(targetPath): 执行文件传输操作，这会返回一个 Mono<Void>。
   • .thenReturn(originalFilename): 这是关键所在。当 fp.transferTo(targetPath) 这个 Mono<Void> 完成（即文件成功写入磁盘）后，thenReturn(originalFilename) 会立即发出 originalFilename 这个字符串作为新的 Mono<String> 的值。
4. .collectList(): 因为 flatMap 操作会为每个文件返回一个 Mono<String>，所以 partFlux.flatMap(…) 的结果是一个 Flux<String> (包含所有上传的文件名)。collectList() 操作符会将这个 Flux<String> 收集成一个 Mono<List<String>>，最终将所有文件名作为一个列表返回给客户端。

注意事项与最佳实践

1. 错误处理: 在实际应用中，文件上传可能失败（例如磁盘空间不足、权限问题）。transferTo 方法在失败时会发出错误信号。您应该在 flatMap 内部或外部添加错误处理逻辑，例如使用 onErrorResume 或 doOnError。

   // 示例：添加错误处理 return partFlux         .flatMap(fp -> {             String originalFilename = fp.filename();             Path targetPath = basePath.resolve(originalFilename);             return fp.transferTo(targetPath)                      .thenReturn(originalFilename)                      .onErrorResume(e -> {                          System.err.println("Failed to upload " + originalFilename + ": " + e.getMessage());                          return Mono.empty(); // 或者返回一个错误信息，或者重新抛出异常                      });         })         .collectList();
2. 安全性: 直接使用 fp.filename() 作为存储文件名存在安全风险，例如路径遍历攻击。在生产环境中，应进行文件名清理、生成唯一的文件名（如使用 UUID），并确保文件存储在安全的、非公开访问的目录。
3. 返回类型:
   • 如果只上传一个文件，可以返回 Mono<String>。
   • 如果上传多个文件，返回 Mono<List<String>> 是常见的做法。
   • 如果需要返回更多信息（如文件大小、存储路径、上传时间等），可以定义一个自定义的 DTO 对象，例如 FileUploadResult，然后返回 Mono<List<FileUploadResult>>。
4. 临时文件处理: FilePart 通常会将上传的文件先存储为临时文件。transferTo 会将这个临时文件移动或复制到目标位置。确保您的应用有权限写入 basePath 指定的目录。

总结

通过巧妙地结合 flatMap 和 thenReturn（或 then(Mono.just())）操作符，Spring WebFlux 允许我们在文件上传完成后，灵活地将所需信息（如文件名）作为响应返回给客户端。这种响应式编程模式不仅保持了非阻塞的特性，也提供了强大的数据流转换能力，使得构建高效且功能丰富的 Web 服务成为可能。在实现此类功能时，务必考虑错误处理和安全防护，以确保应用程序的健壮性和安全性。