一个注解实现下载接口：concept-download @Download注解入门教程-开发者社区

一个注解实现下载接口：concept-download @Download注解入门教程

【免费下载链接】concept封装了一些常用组件，走过路过不要错过哦项目地址: https://gitcode.com/gh_mirrors/con/concept

concept-download 是开源项目 concept 中封装的 Spring Boot 下载组件：一个 @Download 注解就能实现文件下载接口，自动完成文件读取、ZIP/TAR 压缩、缓存加速与响应写出，还支持 Servlet 与 Reactive 双栈。本教程面向新手，带你快速掌握 @Download 注解的核心用法。

为什么需要一个下载组件？🤔

传统 Spring 下载接口通常要自己处理一套重复劳动：

判断数据是本地文件、classpath 资源还是远程 URL
打开流、写出响应、设置Content-Disposition
多个文件要手动打 ZIP 包、单文件判断要不要压缩
下载进度日志、异常处理、缓存

concept-download 把这些工作收进了一条「处理链」，你只需要在 Controller 方法上加一个@Download 下载注解，框架自动接管整个流程。

@Download 注解工作原理一览

组件内部由 4 个环节构成：构建参数 → 创建上下文 → 执行处理链 → 善后。

核心组件速览：

组件	职责
DownloadOptions	汇总注解 + 全局配置的下载参数
CreateSourceHandler	把返回值/注解配置解析成统一数据源 Source
LoadSourceHandler	并发加载网络资源，支持自定义线程池/协程
CompressSourceHandler	自动压缩（ZIP/TAR），支持密码
WriteResponseHandler	写出响应，兼容 Servlet 与 Reactive
DownloadEvent	全流程事件，可监听进度（兼容 Spring 事件）

注解源码见 Download.java，官方示例代码在 ConceptDownloadController.java。

快速上手：5 种数据源写法

在任意 Controller 方法上加 @Download 即可。下载数据有两种指定方式：写在注解的 source 属性，或作为方法返回值。

// 1. 本地文件（source 直接写路径，方法体为空） @Download(source = "file:/Users/Shared/README.txt") @GetMapping("/s1") public void s1() {} // 2. 方法返回文件路径字符串 @Download @GetMapping("/s2") public String s2() { return "file:/Users/Shared/README.txt"; } // 3. 方法直接返回 File / ClassPathResource 对象 @Download @GetMapping("/s3") public File s3() { return new File("/Users/Shared/README.txt"); } // 4. 任意文本直接当文本文件下载 @Download(filename = "s9.txt") @GetMapping("/s9") public String s9() { return "任意文本将会直接作为文本文件处理"; }

支持的路径前缀包括file:（本地）、user.home:（用户目录）、classpath:（资源文件）、http(s)://（远程 URL），返回值还兼容List、POJO 集合等多种形态。

下载多个文件：自动打包成压缩包

当有多个数据源时，组件会自动压缩（默认 ZIP）后下发，单个文件默认不压缩，可用forceCompress强制开启：

@Download(source = { "classpath:/download/text.txt", "http://192.168.20.112:8088/demo/download"}, filename = "压缩包14.zip") @GetMapping("/s14") public void s14() {}

在线预览：图片/视频直接展示

设置inline = true并指定contentType，浏览器就不再触发下载而是直接预览：

@Download(source = "classpath:/download/image.jpg", inline = true, contentType = "image/jpeg") @GetMapping("/image.jpg") public void image() {}

@Download 注解属性速查表

属性	说明
source	下载数据（路径/URL 数组），优先级最高
filename	浏览器中显示的下载文件名
inline	是否内联预览（图片、视频等）
contentType	响应头 Content-Type
compressFormat	压缩格式：zip（默认）/ tar / tar.gz
compressPassword	压缩密码（支持 SpEL 如`${download.password}`）
forceCompress	单文件是否强制压缩
charset	指定编码时以字符流读取（如 GBK）
headers	额外响应头，两两一组 name/value

缓存加速：@SourceCache 与 @CompressCache 🚀

远程资源反复下载会拖慢接口？配合两个缓存注解（源码见 SourceCache.java）：

@SourceCache：把网络数据缓存到本地磁盘，下次直接读取
@CompressCache：把压缩结果也缓存下来，内容不变就不重复压缩

@Download(filename = "压缩包16.zip") @SourceCache(group = "s16", delete = true) @CompressCache(group = "s16", name = "s16.zip", delete = true) @GetMapping("/s16") public List<Object> s16() { ... }

group用于按业务划分缓存子目录，delete = true表示下载结束后清理缓存，适合内容动态变化的场景。

全局配置：concept.download 前缀

大部分默认值可以在配置文件中统一调整（绑定类见 DownloadProperties.java）：

concept: download: compress: format: zip # 默认压缩格式 password: 123456 # 默认压缩密码 cache: enabled: true # 开启压缩缓存 delete: false source: cache: enabled: true # 开启数据源缓存

注解上的配置优先级高于全局配置，需要时也可以让方法返回DownloadOptions.Configurer在回调中动态修改本次下载的全部参数。