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

The author starts by describing a common need for a download feature in backend projects and the pain of writing repetitive code for tasks such as exporting device QR‑code images as a zip archive.

To address this, a library called Concept‑Download is created. It provides a single @Download annotation that can be placed on controller methods to automatically handle various download sources (files, classpath resources, HTTP URLs, custom objects) and generate appropriate filenames.

Key concepts include:

**Source abstraction** – every downloadable item is represented by a Source (e.g., FileSource , HttpSource ) created by a matching SourceFactory .

**Download context** – a DownloadContext object is passed through the whole pipeline, allowing steps to share intermediate data.

**Handler chain** – the process is broken into independent DownloadHandler implementations (loading, compression, response writing) that can be ordered and combined like Spring Cloud Gateway filters.

**Reactive support** – the library works with both Servlet‑based HttpServletResponse and WebFlux ServerHttpResponse . A ReactiveDownloadResponse wraps a ServerHttpResponse and provides an OutputStream backed by a FluxSink so that traditional byte‑stream code can be reused.

Example controller methods:

@Download(source = "classpath:/download/README.txt")
@GetMapping("/classpath")
public void classpath() { }

@Download(filename = "二维码.zip")
@GetMapping("/download")
public List<Device> download() { return deviceService.all(); }

The Device class uses @SourceObject to mark the QR‑code URL field and @SourceName to define the file name:

public class Device {
    private String name;
    @SourceObject
    private String qrCodeUrl;
    @SourceName
    public String getQrCodeName() { return name + ".png"; }
}

Concurrency is handled by a SourceLoader interface, allowing custom strategies (thread pools, coroutines) for loading remote resources before compression.

Compression is abstracted by SourceCompressor ; the default implementation creates a ZIP archive, but any format can be added.

Response writing is unified through DownloadWriter , which can work with byte arrays, ranges, and character sets, and is used by both servlet and reactive responses.

To make the pipeline observable, an event system ( DownloadEventPublisher / DownloadEventListener ) is introduced, enabling detailed logging of each step, progress updates, and total execution time.

Several pitfalls are discussed, such as context destruction not being triggered in WebFlux after the response is written, and the solution of invoking the destroy hook in doAfterTerminate .

Overall, the library demonstrates a modular, extensible approach to handling complex download requirements in Java backend services, combining annotation‑driven configuration, reactive programming, and a pluggable architecture.