太方便了！SpringBoot 只需一個注解，就能搞定任意對象下載！

作者：編程疏影 2025-03-03 00:00:55

?在日常開發中，文件下載是一個常見的功能，雖然在項目中出現的頻率可能不算太高，但幾乎每個項目都會涉及。而有些下載需求相對復雜，雖然不是難點，但實現起來卻十分繁瑣。

在日常開發中，文件下載是一個常見的功能，雖然在項目中出現的頻率可能不算太高，但幾乎每個項目都會涉及。而有些下載需求相對復雜，雖然不是難點，但實現起來卻十分繁瑣。

因此，為了簡化這一過程，有一個工具庫，使得下載功能的實現變得更加簡單快捷。

https://github.com/Linyuzai/concept/wiki/Concept-Download

一鍵下載任意對象

如果告訴你，現在僅需一個注解就能輕松下載任意對象，你會不會覺得很方便？

import com.icoderoad.download.annotation.Download;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.io.File;


@RestController
public class DownloadController {


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


    @Download
    @GetMapping("/file")
    public File downloadFile() {
        return new File("/Users/Shared/README.txt");
    }


    @Download
    @GetMapping("/http")
    public String downloadFromHttp() {
        return "http://127.0.0.1:8080/icoderoad-download/image.jpg";
    }
}

看起來似乎沒有太大變化？那讓我們看看一個實際場景。

真實業務中的應用

在一個設備管理平臺中，每個設備都會有一個二維碼圖片，其地址存儲在數據庫的一個字段中。現需導出所有設備的二維碼圖片，并以設備名稱命名，最終打包成 ZIP 文件。

實現這一需求，需要：

查詢設備列表。
根據二維碼 URL 下載圖片并存入本地緩存。
處理緩存判斷，避免重復下載。
并發下載以提升性能。
下載完成后生成 ZIP 文件。
將 ZIP 文件寫入響應流。

整個實現過程大約需要 200 行代碼，顯得十分冗長繁瑣。于是我思考是否有更簡單的方法。

其實，我們只需要提供待下載的數據，比如文件路徑、文件對象、文本內容、HTTP 地址，甚至是一個自定義對象，而無需關注下載邏輯。

于是，我們可以這樣簡化實現：

import com.icoderoad.download.annotation.Download;
import com.icoderoad.download.annotation.SourceName;
import com.icoderoad.download.annotation.SourceObject;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;


@RestController
public class DeviceDownloadController {


    private final DeviceService deviceService;


    public DeviceDownloadController(DeviceService deviceService) {
        this.deviceService = deviceService;
    }


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


class Device {
    private String name;


    @SourceObject
    private String qrCodeUrl;


    @SourceName
    public String getQrCodeName() {
        return name + ".png";
    }
}

只需標注注解，系統會自動處理文件名稱、下載內容、打包等邏輯，無需手動編寫大量代碼。

設計思路

這一功能的核心思想是基于 AOP 攔截下載請求，并結合 Spring WebFlux 進行異步處理。

@Download 注解說明

參數	說明
`source`	需要下載的內容，但是優先級低于返回值如果方法返回值不為`null`則會使用返回值作為下載的內容
`inline`	如果為`true`，可以直接在瀏覽器預覽需要配合`contentType`，如圖片或視頻，默認`false` 視頻文件目前存在一些問題，還在測試階段
`filename`	指定下載時瀏覽器上顯示的名稱如果不指定則會獲取下載內容的名稱，如文件則使用文件名
`contentType`	如果未指定，會嘗試獲取如果嘗試獲取失敗，則默認`application/octet-stream` 或`application/x-zip-compressed`
`compressFormat`	壓縮格式，默認`zip`
`forceCompress`	強制壓縮如果為`true`，不管下載的文件有幾個都會壓縮如果為`false`，有多個文件時壓縮，只有一個文件時不壓縮默認`false`
`charset`	如果下載包含中文的文本文件出現亂碼，可以嘗試指定編碼
`headers`	統一的響應頭，每2個為一組
`extra`	額外的數據，當需要自行編寫額外流程業務時可能會用到

整體流程

圖片

響應式支持

為了兼容 Spring WebFlux，我們需要獲取 ServerHttpResponse，但不能直接使用 RequestContextHolder，因此可以通過 WebFilter 進行注入：

import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;
import reactor.core.publisher.Mono;


public class ReactiveDownloadFilter implements WebFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        return chain.filter(exchange)
                .contextWrite(ctx -> ctx.put(ServerHttpResponse.class, exchange.getResponse()));
    }
}

然后在需要的地方通過 ReactiveDownloadHolder 獲取響應對象。

import org.springframework.web.server.ServerHttpResponse;
import reactor.core.publisher.Mono;


public class ReactiveDownloadHolder {
    public static Mono<ServerHttpResponse> getResponse() {
        return Mono.deferContextual(ctx -> Mono.just(ctx.get(ServerHttpResponse.class)));
    }
}

處理下載任務

下載任務分為多個步驟，例如：

獲取文件路徑或 File 對象。
如果是多個文件，則先進行壓縮處理。
將最終文件寫入響應流。

因此，我們采用類似 Spring Cloud Gateway 過濾鏈的方式，設計了 DownloadHandler：

import reactor.core.publisher.Mono;

public interface DownloadHandler {
    Mono<Void> handle(DownloadContext context, DownloadHandlerChain chain);
}

每個 DownloadHandler 處理特定任務，如下載、壓縮、寫入響應流等。

適配多種數據源

不同類型的下載對象需要不同的處理方式，例如文件、HTTP 地址、自定義對象等，因此我們抽象出 Source 接口，并通過 SourceFactory 進行匹配。

public interface SourceFactory {
    boolean support(Object source, DownloadContext context);
    Source create(Object source, DownloadContext context);
}

例如：

public class FileSourceFactory implements SourceFactory {
    @Override
    public boolean support(Object source, DownloadContext context) {
        return source instanceof File;
    }


    @Override
    public Source create(Object source, DownloadContext context) {
        return new FileSource((File) source);
    }
}

結語

這個工具庫極大簡化了文件下載功能，尤其是針對復雜的批量下載需求，只需簡單的注解即可完成。如果你正在開發 SpringBoot 3.4 版本的項目，并需要實現高效的下載功能，不妨試試這個方案！

責任編輯：武曉燕來源：路條編程

Spring 文件下載開發