太方便了！SpringBoot 只需一個(gè)注解，就能搞定任意對(duì)象下載！
在日常開(kāi)發(fā)中，文件下載是一個(gè)常見(jiàn)的功能，雖然在項(xiàng)目中出現(xiàn)的頻率可能不算太高，但幾乎每個(gè)項(xiàng)目都會(huì)涉及。而有些下載需求相對(duì)復(fù)雜，雖然不是難點(diǎn)，但實(shí)現(xiàn)起來(lái)卻十分繁瑣。
因此，為了簡(jiǎn)化這一過(guò)程，有一個(gè)工具庫(kù)，使得下載功能的實(shí)現(xiàn)變得更加簡(jiǎn)單快捷。
https://github.com/Linyuzai/concept/wiki/Concept-Download
一鍵下載任意對(duì)象
如果告訴你，現(xiàn)在僅需一個(gè)注解就能輕松下載任意對(duì)象，你會(huì)不會(huì)覺(jué)得很方便？
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";
}
}看起來(lái)似乎沒(méi)有太大變化？那讓我們看看一個(gè)實(shí)際場(chǎng)景。
真實(shí)業(yè)務(wù)中的應(yīng)用
在一個(gè)設(shè)備管理平臺(tái)中，每個(gè)設(shè)備都會(huì)有一個(gè)二維碼圖片，其地址存儲(chǔ)在數(shù)據(jù)庫(kù)的一個(gè)字段中?，F(xiàn)需導(dǎo)出所有設(shè)備的二維碼圖片，并以設(shè)備名稱(chēng)命名，最終打包成 ZIP 文件。
實(shí)現(xiàn)這一需求，需要：
- 查詢?cè)O(shè)備列表。
- 根據(jù)二維碼 URL 下載圖片并存入本地緩存。
- 處理緩存判斷，避免重復(fù)下載。
- 并發(fā)下載以提升性能。
- 下載完成后生成 ZIP 文件。
- 將 ZIP 文件寫(xiě)入響應(yīng)流。
整個(gè)實(shí)現(xiàn)過(guò)程大約需要 200 行代碼，顯得十分冗長(zhǎng)繁瑣。于是我思考是否有更簡(jiǎn)單的方法。
其實(shí)，我們只需要提供待下載的數(shù)據(jù)，比如文件路徑、文件對(duì)象、文本內(nèi)容、HTTP 地址，甚至是一個(gè)自定義對(duì)象，而無(wú)需關(guān)注下載邏輯。
于是，我們可以這樣簡(jiǎn)化實(shí)現(xiàn)：
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";
}
}只需標(biāo)注注解，系統(tǒng)會(huì)自動(dòng)處理文件名稱(chēng)、下載內(nèi)容、打包等邏輯，無(wú)需手動(dòng)編寫(xiě)大量代碼。
設(shè)計(jì)思路
這一功能的核心思想是基于 AOP 攔截下載請(qǐng)求，并結(jié)合 Spring WebFlux 進(jìn)行異步處理。
@Download 注解說(shuō)明
參數(shù) | 說(shuō)明 |
| 需要下載的內(nèi)容，但是優(yōu)先級(jí)低于返回值 如果方法返回值不為 |
| 如果為 |
| 指定下載時(shí)瀏覽器上顯示的名稱(chēng) 如果不指定則會(huì)獲取下載內(nèi)容的名稱(chēng)，如文件則使用文件名 |
| 如果未指定，會(huì)嘗試獲取 如果嘗試獲取失敗，則默認(rèn) |
| 壓縮格式，默認(rèn) |
| 強(qiáng)制壓縮 如果為 |
| 如果下載包含中文的文本文件出現(xiàn)亂碼，可以嘗試指定編碼 |
| 統(tǒng)一的響應(yīng)頭，每2個(gè)為一組 |
| 額外的數(shù)據(jù)，當(dāng)需要自行編寫(xiě)額外流程業(yè)務(wù)時(shí)可能會(huì)用到 |
整體流程
圖片
響應(yīng)式支持
為了兼容 Spring WebFlux，我們需要獲取 ServerHttpResponse，但不能直接使用 RequestContextHolder，因此可以通過(guò) WebFilter 進(jìn)行注入：
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()));
}
}然后在需要的地方通過(guò) ReactiveDownloadHolder 獲取響應(yīng)對(duì)象。
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)));
}
}處理下載任務(wù)
下載任務(wù)分為多個(gè)步驟，例如：
- 獲取文件路徑或 File 對(duì)象。
- 如果是多個(gè)文件，則先進(jìn)行壓縮處理。
- 將最終文件寫(xiě)入響應(yīng)流。
因此，我們采用類(lèi)似 Spring Cloud Gateway 過(guò)濾鏈的方式，設(shè)計(jì)了 DownloadHandler：
import reactor.core.publisher.Mono;
public interface DownloadHandler {
Mono<Void> handle(DownloadContext context, DownloadHandlerChain chain);
}每個(gè) DownloadHandler 處理特定任務(wù)，如下載、壓縮、寫(xiě)入響應(yīng)流等。
適配多種數(shù)據(jù)源
不同類(lèi)型的下載對(duì)象需要不同的處理方式，例如文件、HTTP 地址、自定義對(duì)象等，因此我們抽象出 Source 接口，并通過(guò) SourceFactory 進(jìn)行匹配。
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);
}
}結(jié)語(yǔ)
這個(gè)工具庫(kù)極大簡(jiǎn)化了文件下載功能，尤其是針對(duì)復(fù)雜的批量下載需求，只需簡(jiǎn)單的注解即可完成。如果你正在開(kāi)發(fā) SpringBoot 3.4 版本的項(xiàng)目，并需要實(shí)現(xiàn)高效的下載功能，不妨試試這個(gè)方案！
