Design and Implementation of a Flexible Download Library for Spring WebFlux/WebMVC

In many projects a download feature is required, but implementing it can become cumbersome when handling various source types, naming rules, compression, and response writing.

The author introduces a lightweight library that allows a single @Download annotation on a controller method to automatically handle downloading of files, HTTP resources, strings, or custom objects, with the file name supplied by a @SourceName method.

Key design ideas include a processing chain similar to Spring Cloud Gateway, where each step implements DownloadHandler and can be composed freely. The DownloadContext carries data between steps, and SourceFactory implementations create concrete Source objects for files, HTTP URLs, etc.

To support both WebMVC and WebFlux, a ReactiveDownloadFilter stores the current request and response in a reactive context, while ReactiveDownloadResponse adapts the ServerHttpResponse to an OutputStream using a custom FluxSinkOutputStream implementation.

Compression is abstracted by SourceCompressor, allowing zip or custom formats, and the library can compress directly to memory or to a temporary file.

Event publishing via DownloadEventPublisher and listeners provides extensible logging for each stage (loading, compressing, writing) and helps discover bugs.

The article also discusses practical challenges such as context cleanup in reactive streams, concurrent downloading of HTTP resources, and the need to avoid blocking calls like Mono.block().

Overall, the library demonstrates a clean, modular approach to building a download service that works seamlessly in both servlet‑based and reactive Spring applications.