神奇注解：一鍵下載任意對(duì)象
介紹
下載功能應(yīng)該是比較常見(jiàn)的功能了，雖然一個(gè)項(xiàng)目里面可能出現(xiàn)的不多，但是基本上每個(gè)項(xiàng)目都會(huì)有，而且有些下載功能其實(shí)還是比較繁雜的，倒不是難，而是麻煩。
所以結(jié)合之前的下載需求，我寫(xiě)了一個(gè)庫(kù)來(lái)簡(jiǎn)化下載功能的實(shí)現(xiàn)。
傳送門(mén)：https://github.com/Linyuzai/concept/wiki/Concept-Download。
如果我說(shuō)現(xiàn)在只需要一個(gè)注解就能幫你下載任意的對(duì)象，是不是覺(jué)得非常的方便。
@Download(source = "classpath:/download/README.txt")
@GetMapping("/classpath")
public void classpath() {
}
@Download
@GetMapping("/file")
public File file() {
return new File("/Users/Shared/README.txt");
}
@Download
@GetMapping("/http")
public String http() {
return "http://127.0.0.1:8080/concept-download/image.jpg";
}感覺(jué)差別不大？那就聽(tīng)聽(tīng)我遇到的一個(gè)下載需求。
我們有一個(gè)平臺(tái)是管理設(shè)備的，然后每個(gè)設(shè)備都會(huì)有一個(gè)二維碼圖片，用一個(gè)字段存儲(chǔ)的 http 地址。
現(xiàn)在需要導(dǎo)出所有設(shè)備二維碼圖片的壓縮包，圖片名稱需要用設(shè)備名稱加 .png 后綴，需求上來(lái)說(shuō)并不難，但是實(shí)現(xiàn)著實(shí)有點(diǎn)麻煩。
- 首先需要將設(shè)備列表查出來(lái)
- 然后使用二維碼地址下載圖片并寫(xiě)到本地緩存文件
- 在下載之前需要先判斷是否已經(jīng)存在緩存
- 下載時(shí)需要并發(fā)下載提升性能
- 等所有圖片下載結(jié)束后
- 再生成一個(gè)壓縮文件
- 然后再操作輸入輸出流寫(xiě)到響應(yīng)中
我實(shí)現(xiàn)了將近 200 行的代碼，真是又臭又長(zhǎng)，一個(gè)下載功能咋能那么麻煩呢，于是我就想有沒(méi)有更簡(jiǎn)單的方式。
我當(dāng)時(shí)的需求很簡(jiǎn)單，我想著我只要提供需要下載的數(shù)據(jù)，比如一個(gè)文件路徑，一個(gè)文件對(duì)象，一段字符串文本，一個(gè)http地址，或者混搭了前面所有類型的一個(gè)集合，甚至是我們自定義的某個(gè)類的實(shí)例，后面的事情我就不用管了。
文件路徑是一個(gè)文件還是一個(gè)目錄？字符串文本需要先寫(xiě)入一個(gè)文本文件中？http資源如何下載到本地？多個(gè)文件怎么壓縮？最后怎么寫(xiě)到響應(yīng)中？我才不想花時(shí)間管這些。
比如就像我現(xiàn)在這個(gè)需求，我只要返回設(shè)備列表就行了，其他的事情我都不用管。
@Download(filename = "二維碼.zip")
@GetMapping("/download")
public List<Device> download() {
return deviceService.all();
}
public class Device {
//設(shè)備名稱
private String name;
//設(shè)備二維碼
//注解表示該http地址是需要下載的數(shù)據(jù)
@SourceObject
private String qrCodeUrl;
//注解表示文件名稱
@SourceName
public String getQrCodeName() {
return name + ".png";
}
//省略其他屬性方法
}通過(guò)在 Device 的字段上標(biāo)注某些注解（或是實(shí)現(xiàn)某個(gè)接口）來(lái)指定文件名稱和文件地址。
如果能這樣實(shí)現(xiàn)，省時(shí)省心省力，又多了寫(xiě) 199 行代碼的摸魚(yú)時(shí)間難道不香么。
思路
下面來(lái)講講這個(gè)庫(kù)的主要設(shè)計(jì)思路，以及中間遇到的坑。
其實(shí)基于一開(kāi)始的設(shè)想，我覺(jué)得功能并沒(méi)有多復(fù)雜，于是就決定開(kāi)肝。
只是萬(wàn)萬(wàn)沒(méi)想到實(shí)現(xiàn)起來(lái)比我想象的更復(fù)雜（這是后話了）。
基礎(chǔ)
首先整個(gè)庫(kù)基于響應(yīng)式編程，但卻并不是完全意義上的響應(yīng)式，只能說(shuō)是Mono<InputStream>這樣的。。。奇怪組合？
為什么會(huì)這樣呢，很大的一個(gè)原因是由于需要兼容webmvc和webflux，導(dǎo)致我僅僅是將之前實(shí)現(xiàn)的InputStream方式重構(gòu)成了響應(yīng)式，所以就出現(xiàn)了這樣的組合。
這也是我遇到的最大的一個(gè)坑，我先前已經(jīng)基本調(diào)通了基于Servlet的整個(gè)下載流程，然后就想著支持一下webflux。
大家都知道webmvc中，我們可以通過(guò)RequestContextHolder來(lái)獲得請(qǐng)求和響應(yīng)對(duì)象，但是在webflux中就不行了，當(dāng)然我們可以在方法參數(shù)中注入。
@Download(source = "classpath:/download/README.txt")
@GetMapping("/classpath")
public void classpath(ServerHttpResponse response) {
}結(jié)合Spring自帶的注入功能，我們就可以通過(guò)AOP拿到響應(yīng)的入?yún)⒘耍强傆X(jué)得這樣寫(xiě)有點(diǎn)多余，強(qiáng)迫癥表示不能忍。
有什么辦法既能把用不到的入?yún)⒏傻簦帜苣玫巾憫?yīng)對(duì)象呢，在網(wǎng)上找到了一種實(shí)現(xiàn)方式。
/**
* 用于設(shè)置當(dāng)前的請(qǐng)求和響應(yīng)。
*
* @see ReactiveDownloadHolder
*/
public class ReactiveDownloadFilter implements WebFilter {
@Override
public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
ServerHttpResponse response = exchange.getResponse();
return chain.filter(exchange)
//低版本使用subscriberContext
.contextWrite(ctx -> ctx.put(ServerHttpRequest.class, request))
.contextWrite(ctx -> ctx.put(ServerHttpResponse.class, response));
}
}
/**
* 用于獲得當(dāng)前的請(qǐng)求和響應(yīng)。
*
* @see ReactiveDownloadFilter
*/
public class ReactiveDownloadHolder {
public static Mono<ServerHttpRequest> getRequest() {
//低版本使用subscriberContext
return Mono.deferContextual(contextView -> Mono.just(contextView.get(ServerHttpRequest.class)));
}
public static Mono<ServerHttpResponse> getResponse() {
//低版本使用subscriberContext
return Mono.deferContextual(contextView -> Mono.just(contextView.get(ServerHttpResponse.class)));
}
}通過(guò)添加WebFilter就可以獲得響應(yīng)對(duì)象了，但是返回值是Mono<ServerHttpResponse>。
那么可不可以通過(guò)Mono.block()阻塞得到對(duì)應(yīng)的對(duì)象呢，答案是不行，由于webflux基于Netty的非阻塞線程，如果調(diào)用該方法會(huì)直接拋出異常。
所以就沒(méi)有任何辦法了，只能將之前代碼基于響應(yīng)式重構(gòu)。
架構(gòu)
接下來(lái)說(shuō)說(shuō)整體架構(gòu)：
圖片
對(duì)于一個(gè)下載請(qǐng)求，我們可以分成幾個(gè)步驟，以下載多個(gè)文件的壓縮包為例：
- 首先我們一般是得到多個(gè)文件的路徑或?qū)?yīng)的File對(duì)象。
- 然后將這些文件壓縮生成一個(gè)壓縮文件。
- 最后將壓縮文件寫(xiě)入到響應(yīng)中。
但是對(duì)于我上面描述的需求，一開(kāi)始就不是文件路徑或?qū)ο罅耍且粋€(gè)http地址，然后在壓縮之前還需要多一個(gè)步驟，需要先將圖片下載下來(lái)。
那么對(duì)于各種各樣的需求我們可能需要在當(dāng)前步驟中的任意位置添加額外的步驟，所以我參考了Spring Cloud Gateway 攔截鏈的實(shí)現(xiàn)方式。
/**
* 下載處理器。
*/
public interface DownloadHandler extends OrderProvider {
/**
* 執(zhí)行處理。
*
* @param context {@link DownloadContext}
* @param chain {@link DownloadHandlerChain}
*/
Mono<Void> handle(DownloadContext context, DownloadHandlerChain chain);
}
/**
* 下載處理鏈。
*/
public interface DownloadHandlerChain {
/**
* 調(diào)度下一個(gè)下載處理器。
*
* @param context {@link DownloadContext}
*/
Mono<Void> next(DownloadContext context);
}這樣每個(gè)步驟就可以單獨(dú)實(shí)現(xiàn)一個(gè)DownloadHandler，步驟與步驟之間可以任意的組合添加。
下載上下文
在此基礎(chǔ)上使用一個(gè)貫穿整個(gè)流程的上下文DownloadContext，方便共享和傳遞步驟之間的中間結(jié)果。
對(duì)于上下文DownloadContext也提供了DownloadContextFactory可以用于自定義上下文。
同時(shí)提供了DownloadContextInitializer和DownloadContextDestroyer用于在上下文初始化和銷毀時(shí)擴(kuò)展自己的邏輯。
下載類型支持
我們需要下載的數(shù)據(jù)的類型是不固定的，比如有文件，有http地址，也會(huì)有之前我希望的自定義的類的實(shí)例。
所以我將所有的下載對(duì)象抽象成了Source，表示一個(gè)下載源，這樣文件可以實(shí)現(xiàn)為FileSource，http地址可以實(shí)現(xiàn)為HttpSource，然后通過(guò)對(duì)應(yīng)的SourceFactory來(lái)匹配創(chuàng)建。
比如FileSourceFactory可以匹配File并且創(chuàng)建FileSource，HttpSourceFactory可以匹配http://前綴并且創(chuàng)建HttpSource。
/**
* {@link Source} 工廠。
*/
public interface SourceFactory extends OrderProvider {
/**
* 是否支持需要下載的原始數(shù)據(jù)對(duì)象。
*
* @param source 需要下載的原始數(shù)據(jù)對(duì)象
* @param context {@link DownloadContext}
* @return 如果支持則返回 true
*/
boolean support(Object source, DownloadContext context);
/**
* 創(chuàng)建。
*
* @param source 需要下載的原始數(shù)據(jù)對(duì)象
* @param context {@link DownloadContext}
* @return 創(chuàng)建的 {@link Source}
*/
Source create(Object source, DownloadContext context);
}那么對(duì)于我們自定義的類要怎么支持呢，之前提到可以在類上標(biāo)注注解或是實(shí)現(xiàn)特定的接口，那么就用我實(shí)現(xiàn)的注解的方式來(lái)大概講一講吧！
其實(shí)邏輯很簡(jiǎn)單，只要能熟練的運(yùn)用反射就完全沒(méi)問(wèn)題，我們?cè)賮?lái)看一看用法。
@Download(filename = "二維碼.zip")
@GetMapping("/download")
public List<Device> download() {
return deviceService.all();
}
public class Device {
//設(shè)備名稱
private String name;
//設(shè)備二維碼
//注解表示該http地址是需要下載的數(shù)據(jù)
@SourceObject
private String qrCodeUrl;
//注解表示文件名稱
@SourceName
public String getQrCodeName() {
return name + ".png";
}
//省略其他屬性方法
}首先我定義了一個(gè)注解@SourceModel標(biāo)注在類上表示需要被解析，然后定義了一個(gè)@SourceObject注解標(biāo)注在需要下載的字段（或方法）上，這樣我們就可以通過(guò)反射拿到這個(gè)字段（或方法）的值。
基于當(dāng)前支持的SourceFactory就能創(chuàng)建出對(duì)應(yīng)的Source，接下來(lái)使用@SourceName指定名稱，也同樣可以通過(guò)反射獲得這個(gè)方法（或字段）的值并依舊通過(guò)反射設(shè)置到創(chuàng)建出來(lái)的Source上。
這樣就能非常靈活的支持任意的對(duì)象類型了。
并發(fā)加載
對(duì)于像http這種網(wǎng)絡(luò)資源，我們需要先并發(fā)加載（多個(gè)文件時(shí)）到本地的內(nèi)存中或是緩存文件中來(lái)提升我們的處理效率。
當(dāng)然我可以直接定死一個(gè)線程池來(lái)執(zhí)行，但是每個(gè)機(jī)器每個(gè)項(xiàng)目甚至每個(gè)需求對(duì)于并發(fā)的要求和資源的分配都不一樣。
所以我提供了SourceLoader來(lái)支持自定義的加載邏輯，你甚至可以一部分用線程池，一部分用協(xié)程，剩下一部分不加載。
/**
* {@link Source} 加載器。
*
* @see DefaultSourceLoader
* @see SchedulerSourceLoader
*/
public interface SourceLoader {
/**
* 執(zhí)行加載。
*
* @param source {@link Source}
* @param context {@link DownloadContext}
* @return 加載后的 {@link Source}
*/
Mono<Source> load(Source source, DownloadContext context);
}壓縮
當(dāng)我們加載完之后就可以執(zhí)行壓縮了，同樣的我定義了一個(gè)類Compression作為壓縮對(duì)象的抽象。
一般來(lái)說(shuō)，我們會(huì)先在本地創(chuàng)建一個(gè)緩存文件，然后將壓縮后的數(shù)據(jù)寫(xiě)入到緩存文件中。
不過(guò)我每次都很討厭在配置文件中配置各種各樣的路徑，所以在壓縮時(shí)支持內(nèi)存壓縮，當(dāng)然如果文件比較大還是老老實(shí)實(shí)生成一個(gè)緩存文件。
對(duì)于壓縮格式也提供了可以完全自定義的SourceCompressor接口，你想自己實(shí)現(xiàn)一個(gè)壓縮協(xié)議都沒(méi)有問(wèn)題。
/**
* {@link Source} 壓縮器。
*
* @see ZipSourceCompressor
*/
public interface SourceCompressor extends OrderProvider {
/**
* 獲得壓縮格式。
*
* @return 壓縮格式
*/
String getFormat();
/**
* 判斷是否支持對(duì)應(yīng)的壓縮格式。
*
* @param format 壓縮格式
* @param context {@link DownloadContext}
* @return 如果支持則返回 true
*/
default boolean support(String format, DownloadContext context) {
return format.equalsIgnoreCase(getFormat());
}
/**
* 如果支持對(duì)應(yīng)的格式就會(huì)調(diào)用該方法執(zhí)行壓縮。
*
* @param source {@link Source}
* @param writer {@link DownloadWriter}
* @param context {@link DownloadContext}
* @return {@link Compression}
*/
Compression compress(Source source, DownloadWriter writer, DownloadContext context);
}響應(yīng)寫(xiě)入
我將響應(yīng)抽象成了DownloadResponse，主要用于兼容HttpServletResponse和ServerHttpResponse。
但是問(wèn)題又出現(xiàn)了，下面是webmvc和webflux寫(xiě)入響應(yīng)的方式。
//HttpServletResponse
response.getOutputStream().write(byte b[], int off, int len);
//ServerHttpResponse
response.writeWith(Publisher<? extends DataBuffer> body);這兼容的我腦殼疼，不過(guò)最后還是搞定了。
/**
* 持有 {@link ServerHttpResponse} 的 {@link DownloadResponse}，用于 webflux。
*/
@Getter
public class ReactiveDownloadResponse implements DownloadResponse {
private final ServerHttpResponse response;
private OutputStream os;
private Mono<Void> mono;
public ReactiveDownloadResponse(ServerHttpResponse response) {
this.response = response;
}
@Override
public Mono<Void> write(Consumer<OutputStream> consumer) {
if (os == null) {
mono = response.writeWith(Flux.create(fluxSink -> {
try {
os = new FluxSinkOutputStream(fluxSink, response);
consumer.accept(os);
} catch (Throwable e) {
fluxSink.error(e);
}
}));
} else {
consumer.accept(os);
}
return mono;
}
@SneakyThrows
@Override
public void flush() {
if (os != null) {
os.flush();
}
}
@AllArgsConstructor
public static class FluxSinkOutputStream extends OutputStream {
private FluxSink<DataBuffer> fluxSink;
private ServerHttpResponse response;
@Override
public void write(byte[] b) throws IOException {
writeSink(b);
}
@Override
public void write(byte[] b, int off, int len) throws IOException {
byte[] bytes = new byte[len];
System.arraycopy(b, off, bytes, 0, len);
writeSink(bytes);
}
@Override
public void write(int b) throws IOException {
writeSink((byte) b);
}
@Override
public void flush() {
fluxSink.complete();
}
public void writeSink(byte... bytes) {
DataBuffer buffer = response.bufferFactory().wrap(bytes);
fluxSink.next(buffer);
//在這里可能有問(wèn)題，但是目前沒(méi)有沒(méi)有需要釋放的數(shù)據(jù)
DataBufferUtils.release(buffer);
}
}
}只要最后都是寫(xiě)byte[]就可以相互轉(zhuǎn)化，只不過(guò)可能麻煩一點(diǎn)，需要用接口回調(diào)。
將FluxSink偽裝成一個(gè)OutputStream，寫(xiě)入時(shí)把byte[]轉(zhuǎn)成DataBuffer 并調(diào)用next方法，最后在flush的時(shí)候調(diào)用complete方法就行了，完美。
響應(yīng)寫(xiě)入其實(shí)就是對(duì)輸入輸出流的處理了，正常情況下，我們會(huì)定義一個(gè)byte[]用來(lái)緩存讀到的數(shù)據(jù)，所以我也不會(huì)固定這個(gè)緩存的大小而是提供了DownloadWriter可以自定義處理輸入輸出流，包括存在指定編碼或是Range頭的情況。
/**
* 具體操作 {@link InputStream} 和 {@link OutputStream} 的寫(xiě)入器。
*/
public interface DownloadWriter extends OrderProvider {
/**
* 該寫(xiě)入器是否支持寫(xiě)入。
*
* @param resource {@link Resource}
* @param range {@link Range}
* @param context {@link DownloadContext}
* @return 如果支持則返回 true
*/
boolean support(Resource resource, Range range, DownloadContext context);
/**
* 執(zhí)行寫(xiě)入。
*
* @param is {@link InputStream}
* @param os {@link OutputStream}
* @param range {@link Range}
* @param charset {@link Charset}
* @param length 總大小，可能為 null
*/
default void write(InputStream is, OutputStream os, Range range, Charset charset, Long length) {
write(is, os, range, charset, length, null);
}
/**
* 執(zhí)行寫(xiě)入。
*
* @param is {@link InputStream}
* @param os {@link OutputStream}
* @param range {@link Range}
* @param charset {@link Charset}
* @param length 總大小，可能為 null
* @param callback 回調(diào)當(dāng)前進(jìn)度和增長(zhǎng)的大小
*/
void write(InputStream is, OutputStream os, Range range, Charset charset, Long length, Callback callback);
/**
* 進(jìn)度回調(diào)。
*/
interface Callback {
/**
* 回調(diào)進(jìn)度。
*
* @param current 當(dāng)前值
* @param increase 增長(zhǎng)值
*/
void onWrite(long current, long increase);
}
}事件
當(dāng)我把整個(gè)下載流程實(shí)現(xiàn)之后發(fā)現(xiàn)其實(shí)整個(gè)邏輯還是有點(diǎn)復(fù)雜的，所有得想個(gè)辦法能監(jiān)控整個(gè)下載流程。
最開(kāi)始我定義了幾個(gè)監(jiān)聽(tīng)器用來(lái)回調(diào)，但是并不好用，首先我們整個(gè)架構(gòu)設(shè)計(jì)的是十分靈活可擴(kuò)展的，而定義的監(jiān)聽(tīng)器類型少而且不好擴(kuò)展。
當(dāng)我們后續(xù)添加了其他的流程和步驟后，不得不新加幾類監(jiān)聽(tīng)器或是在原來(lái)的監(jiān)聽(tīng)器類上添加方法，十分麻煩。
所以我想到使用事件的方式能更加靈活的擴(kuò)展，并定義了DownloadEventPublisher用于發(fā)布事件和DownloadEventListener用于監(jiān)聽(tīng)事件，而且支持了Spring的事件監(jiān)聽(tīng)方式。
日志
基于上述的事件方式，我在此基礎(chǔ)上實(shí)現(xiàn)了幾種下載日志。
- 每個(gè)流程對(duì)應(yīng)的日志。
- 加載進(jìn)度更新，壓縮進(jìn)度更新，響應(yīng)寫(xiě)入進(jìn)度更新的日志。
- 時(shí)間花費(fèi)的日志。
這些日志由于比較詳細(xì)的打印了整個(gè)下載流程的信息，還幫我發(fā)現(xiàn)了好多Bug。
其他坑
最開(kāi)始上下文的初始化和銷毀各自對(duì)應(yīng)了一個(gè)步驟分別位于最開(kāi)始和最末尾，但是當(dāng)我在webflux中寫(xiě)完響應(yīng)后，發(fā)現(xiàn)上下文的銷毀不會(huì)執(zhí)行。
于是我跟了下Spring的源碼發(fā)現(xiàn)寫(xiě)入方法返回的是Mono.empty()，也就是說(shuō)，當(dāng)響應(yīng)寫(xiě)入后就不會(huì)往下調(diào)用next方法了，所以在響應(yīng)寫(xiě)入之后的步驟永遠(yuǎn)都不會(huì)被調(diào)用。
最后就把上下文初始化和銷毀單獨(dú)出來(lái)了，并且在doAfterTerminate時(shí)調(diào)用銷毀方法。
