太方便了！SpringBoot 只需一個注解，就能搞定任意對象下載！
在日常開發中，文件下載是一個常見的功能，雖然在項目中出現的頻率可能不算太高，但幾乎每個項目都會涉及。而有些下載需求相對復雜，雖然不是難點，但實現起來卻十分繁瑣。
因此，為了簡化這一過程，有一個工具庫，使得下載功能的實現變得更加簡單快捷。
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 注解說明
參數 | 說明 |
| 需要下載的內容，但是優先級低于返回值 如果方法返回值不為 |
| 如果為 |
| 指定下載時瀏覽器上顯示的名稱 如果不指定則會獲取下載內容的名稱，如文件則使用文件名 |
| 如果未指定，會嘗試獲取 如果嘗試獲取失敗，則默認 |
| 壓縮格式，默認 |
| 強制壓縮 如果為 |
| 如果下載包含中文的文本文件出現亂碼，可以嘗試指定編碼 |
| 統一的響應頭，每2個為一組 |
| 額外的數據，當需要自行編寫額外流程業務時可能會用到 |
整體流程
圖片
響應式支持
為了兼容 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 版本的項目，并需要實現高效的下載功能，不妨試試這個方案！
