Spring File Storage Versions Save

一行代码将文件存储到本地、FTP、SFTP、WebDAV、谷歌云存储、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、 AWS S3、FastDFS、 Azure Blob Storage、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台。后续即将支持 Samba、NFS

2.1.0

4 months ago

原名 X Spring File Storage 现已捐赠至 dromara 开源组织

x-file-storage.dromara.org | x-file-storage.xuyanwu.cn | spring-file-storage.xuyanwu.cn

📚简介

一行代码将文件存储到本地、FTP、SFTP、WebDAV、阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS、MinIO、 Amazon S3、GoogleCloud Storage、FastDFS、 Azure Blob Storage、Cloudflare R2、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的存储平台。查看所有支持的存储平台

💡 通过 WebDAV 连接到 Alist 后，可以使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务，查看 Alist 支持的存储平台

GitHub：https://github.com/dromara/x-file-storage Gitee：https://gitee.com/dromara/x-file-storage

文档1：https://x-file-storage.dromara.org 文档2：https://x-file-storage.xuyanwu.cn 文档3：https://spring-file-storage.xuyanwu.cn

📜更新内容

新增 FastDFS 存储平台
新增 Azure Blob Storage 存储平台
新增复制文件，支持跨存储平台复制
新增移动（重命名）文件，支持跨存储平台移动（重命名）
新增大文件手动分片上传（断点续传），1.0.0 版本早已支持大文件自动分片上传
新增计算哈希功能，上传下载时可以边处理边计算
上传无需强制获取文件大小，上传未知大小的文件更友好
优化 SpringBoot 自动配置兼容非 SpringWeb 环境
优化FileKey获取方式，避免空指针异常
优化上传代码结构
优化异常处理
优化进度监听器
修复上传时设置缩略图保存名称错误的BUG
兼容低版本SpringBoot(2.0.x)的依赖注入
修复华为云 OBS 上传进度问题
修复 MultipartFile 存储到本地时，在某些情况下输入流未关闭的问题
修复又拍云 USS 上传缩略图文件时 Response 未关闭的问题

📦使用

点击快速入门查看全部存储平台的使用方法！

🔧 配置

这里以阿里云 OSS 为例，pom.xml 引入本项目，这里默认是 SpringBoot 环境，其它环境参考脱离 SpringBoot 单独使用

<!-- 引入本项目 -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.1.0</version>
</dependency>
<!-- 引入 阿里云 OSS SDK，如果使用其它存储平台，就引入对应的 SDK  -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>

application.yml 配置文件中添加以下基础配置

dromara:
  x-file-storage: #文件存储配置
    default-platform: aliyun-oss-1 #默认使用的存储平台
    aliyun-oss:
      - platform: aliyun-oss-1 # 存储平台标识
        enable-storage: true  # 启用存储
        access-key: ??
        secret-key: ??
        end-point: ??
        bucket-name: ??
        domain: ?? # 访问域名，注意“/”结尾，例如：https://abc.oss-cn-shanghai.aliyuncs.com/
        base-path: test/ # 基础路径

🔨编码

在启动类上加上@EnableFileStorage注解

@EnableFileStorage
@SpringBootApplication
public class SpringFileStorageTestApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringFileStorageTestApplication.class,args);
    }

}

✨开始上传

支持 File、MultipartFile、byte[]、InputStream、URL、URI、String、HttpServletRequest，大文件会自动分片上传。如果想支持更多方式，请阅读文件适配器章节

@RestController
public class FileDetailController {

    @Autowired
    private FileStorageService fileStorageService;//注入实列

    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        //只需要这一行代码即可上传成功
        return fileStorageService.of(file).upload();
    }
    
    /**
     * 上传文件，成功返回文件 url
     */
    @PostMapping("/upload2")
    public String upload2(MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file)
                .setPath("upload/") //保存到相对路径下，为了方便管理，不需要可以不写
                .setObjectId("0")   //关联对象id，为了方便管理，不需要可以不写
                .setObjectType("0") //关联对象类型，为了方便管理，不需要可以不写
                .putAttr("role","admin") //保存一些属性，可以在切面、保存上传记录、自定义存储平台等地方获取使用，不需要可以不写
                .upload();  //将文件上传到对应地方
        return fileInfo == null ? "上传失败！" : fileInfo.getUrl();
    }

    /**
     * 上传图片，成功返回文件信息
     * 图片处理使用的是 https://github.com/coobird/thumbnailator
     */
    @PostMapping("/upload-image")
    public FileInfo uploadImage(MultipartFile file) {
        return fileStorageService.of(file)
                .image(img -> img.size(1000,1000))  //将图片大小调整到 1000*1000
                .thumbnail(th -> th.size(200,200))  //再生成一张 200*200 的缩略图
                .upload();
    }

    /**
     * 上传文件到指定存储平台，成功返回文件信息
     */
    @PostMapping("/upload-platform")
    public FileInfo uploadPlatform(MultipartFile file) {
        return fileStorageService.of(file)
                .setPlatform("aliyun-oss-1")    //使用指定的存储平台
                .upload();
    }

    /**
     * 直接读取 HttpServletRequest 中的文件进行上传，成功返回文件信息
     * 使用这种方式有些注意事项，请查看文档 基础功能-上传 章节
     */
    @PostMapping("/upload-request")
    public FileInfo uploadPlatform(HttpServletRequest request) {
        return fileStorageService.of(request).upload();
    }
}

🎨其它操作

//手动构造文件信息，可用于其它操作
FileInfo fileInfo = new FileInfo()
        .setPlatform("huawei-obs-1")
        .setBasePath("test/")
        .setPath("aa/")
        .setFilename("image.png")
        .setThFilename("image.png.min.jpg");

//文件是否存在
boolean exists = fileStorageService.exists(fileInfo);
//下载
byte[] bytes = fileStorageService.download(fileInfo).bytes();
//删除
fileStorageService.delete(fileInfo);
//其它更多操作

如果将文件记录保存到数据库中，还可以更方便的根据 URL 进行操作了，详情请阅读保存上传记录章节

//直接从数据库中获取 FileInfo 对象，更加方便执行其它操作
FileInfo fileInfo = fileStorageService.getFileInfoByUrl("https://abc.def.com/test/aa/image.png");

//文件是否存在
boolean exists = fileStorageService.exists("https://abc.def.com/test/aa/image.png");
//下载
byte[] bytes = fileStorageService.download("https://abc.def.com/test/aa/image.png").bytes();
//删除
fileStorageService.delete("https://abc.def.com/test/aa/image.png");
//其它更多操作

点击快速入门查看全部存储平台的使用方法！

2.0.0

7 months ago

原名 X Spring File Storage 现已捐赠至 dromara 开源组织

x-file-storage.dromara.org | x-file-storage.xuyanwu.cn | spring-file-storage.xuyanwu.cn

📚简介

一行代码将文件存储到本地、FTP、SFTP、WebDAV、阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS、MinIO、 Amazon S3、GoogleCloud Storage、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的存储平台。查看所有支持的存储平台

💡 通过 WebDAV 连接到 Alist 后，可以使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务，查看 Alist 支持的存储平台

GitHub：https://github.com/dromara/x-file-storage Gitee：https://gitee.com/dromara/x-file-storage

文档1：https://x-file-storage.dromara.org 文档2：https://x-file-storage.xuyanwu.cn 文档3：https://spring-file-storage.xuyanwu.cn

📜更新内容

更改项目名、更改包名、优化项目结构
新增直接读取 HttpServletRequest 的流进行上传，文件不落盘，速度更快
新增支持 Metadata 元数据
优化 ACL 异常处理
优化文件删除逻辑
修复 Amazon S3 上传文件偶现 ResetException 问题
捐赠至 dromara 开源社区

项目依赖的变化

2.0.0 之前的版本

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>1.0.3</version>
</dependency>

2.0.0 及以后的版本

<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.0.0</version>
</dependency>

配置参数的变化

2.0.0 之前的版本

spring:
  file-storage: #文件存储配置
    default-platform: huawei-obs-1 #默认使用的存储平台
    thumbnail-suffix: ".min.jpg" #缩略图后缀，例如【.min.jpg】【.png】
    #对应平台的配置写在这里，注意缩进要对齐

2.0.0 及以后的版本

dromara:
  x-file-storage: #文件存储配置
    default-platform: huawei-obs-1 #默认使用的存储平台
    thumbnail-suffix: ".min.jpg" #缩略图后缀，例如【.min.jpg】【.png】
    #对应平台的配置写在这里，注意缩进要对齐

包名的变化

2.0.0 之前的版本

cn.xuyanwu.spring.file.storage
cn.xuyanwu.spring.file.storage.spring

2.0.0 及以后的版本

org.dromara.x.file.storage.core
org.dromara.x.file.storage.spring

📦使用

点击快速入门查看全部存储平台的使用方法！

🔧 配置

这里以阿里云 OSS 为例，pom.xml 引入本项目，这里默认是 SpringBoot 环境，其它环境参考脱离 SpringBoot 单独使用

<!-- 引入本项目 -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.0.0</version>
</dependency>
<!-- 引入 阿里云 OSS SDK，如果使用其它存储平台，就引入对应的 SDK  -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>

application.yml 配置文件中添加以下基础配置

dromara:
  x-file-storage: #文件存储配置
    default-platform: aliyun-oss-1 #默认使用的存储平台
    aliyun-oss:
      - platform: aliyun-oss-1 # 存储平台标识
        enable-storage: true  # 启用存储
        access-key: ??
        secret-key: ??
        end-point: ??
        bucket-name: ??
        domain: ?? # 访问域名，注意“/”结尾，例如：https://abc.oss-cn-shanghai.aliyuncs.com/
        base-path: test/ # 基础路径

🔨编码

在启动类上加上@EnableFileStorage注解

@EnableFileStorage
@SpringBootApplication
public class SpringFileStorageTestApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringFileStorageTestApplication.class,args);
    }

}

✨开始上传

支持 File、MultipartFile、byte[]、InputStream、URL、URI、String、HttpServletRequest，大文件会自动分片上传。如果想支持更多方式，请阅读文件适配器章节

@RestController
public class FileDetailController {

    @Autowired
    private FileStorageService fileStorageService;//注入实列

    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        //只需要这一行代码即可上传成功
        return fileStorageService.of(file).upload();
    }
    
    /**
     * 上传文件，成功返回文件 url
     */
    @PostMapping("/upload2")
    public String upload2(MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file)
                .setPath("upload/") //保存到相对路径下，为了方便管理，不需要可以不写
                .setObjectId("0")   //关联对象id，为了方便管理，不需要可以不写
                .setObjectType("0") //关联对象类型，为了方便管理，不需要可以不写
                .putAttr("role","admin") //保存一些属性，可以在切面、保存上传记录、自定义存储平台等地方获取使用，不需要可以不写
                .upload();  //将文件上传到对应地方
        return fileInfo == null ? "上传失败！" : fileInfo.getUrl();
    }

    /**
     * 上传图片，成功返回文件信息
     * 图片处理使用的是 https://github.com/coobird/thumbnailator
     */
    @PostMapping("/upload-image")
    public FileInfo uploadImage(MultipartFile file) {
        return fileStorageService.of(file)
                .image(img -> img.size(1000,1000))  //将图片大小调整到 1000*1000
                .thumbnail(th -> th.size(200,200))  //再生成一张 200*200 的缩略图
                .upload();
    }

    /**
     * 上传文件到指定存储平台，成功返回文件信息
     */
    @PostMapping("/upload-platform")
    public FileInfo uploadPlatform(MultipartFile file) {
        return fileStorageService.of(file)
                .setPlatform("aliyun-oss-1")    //使用指定的存储平台
                .upload();
    }

    /**
     * 直接读取 HttpServletRequest 中的文件进行上传，成功返回文件信息
     * 使用这种方式有些注意事项，请查看文档 基础功能-上传 章节
     */
    @PostMapping("/upload-request")
    public FileInfo uploadPlatform(HttpServletRequest request) {
        return fileStorageService.of(request).upload();
    }
}

🎨其它操作

//手动构造文件信息，可用于其它操作
FileInfo fileInfo = new FileInfo()
        .setPlatform("huawei-obs-1")
        .setBasePath("test/")
        .setPath("aa/")
        .setFilename("image.png")
        .setThFilename("image.png.min.jpg");

//文件是否存在
boolean exists = fileStorageService.exists(fileInfo);
//下载
byte[] bytes = fileStorageService.download(fileInfo).bytes();
//删除
fileStorageService.delete(fileInfo);
//其它更多操作

如果将文件记录保存到数据库中，还可以更方便的根据 URL 进行操作了，详情请阅读保存上传记录章节

//直接从数据库中获取 FileInfo 对象，更加方便执行其它操作
FileInfo fileInfo = fileStorageService.getFileInfoByUrl("https://abc.def.com/test/aa/image.png");

//文件是否存在
boolean exists = fileStorageService.exists("https://abc.def.com/test/aa/image.png");
//下载
byte[] bytes = fileStorageService.download("https://abc.def.com/test/aa/image.png").bytes();
//删除
fileStorageService.delete("https://abc.def.com/test/aa/image.png");
//其它更多操作

点击快速入门查看全部存储平台的使用方法！

1.0.3

9 months ago

修复了 FileStorageClientFactory 未自动加载的问题
优化了 HuaweiObsFileStorage 的 ACL 转换方式，使其兼容低版本 SDK
修复了 GoogleCloudStorageFileStorage 的 ACL 转换时空指针问题
修复了又拍云 USS 的错误提示问题

此版本支持本地、FTP、SFTP、WebDAV、谷歌云存储、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、AWS S3、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>1.0.3</version>
</dependency>

阅读文档开始使用！

1.0.2

9 months ago

修复了华为云 OBS 未加载的问题

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>1.0.2</version>
</dependency>

阅读文档开始使用！

1.0.1

9 months ago

修复了 MultipartFileWrapperAdapter 无法正确获取文件名的问题
修复了缺少配置文件元数据的问题

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>1.0.1</version>
</dependency>

阅读文档开始使用！

1.0.0

9 months ago

此版本变化较大、更新内容较多，从旧版本升级要做好充分的测试！

配置文件中，Amazon S3 存储平台名称由 aws-s3 更改为 amazon-s3
配置文件中，GoogleCloud Storage 存储平台名称由 google-cloud 更改为 google-cloud-storage
文件记录记录者接口 FileRecorder 的 record 方法更改为 save
脱离 SpringBoot 独立运行（方便集成到其它框架中）
支持大文件上传
上传进度监控
增加存储平台的 Client 工厂接口，用于支持网络代理、通过 STS 方式初始化存储平台的 Client 对象等功能
支持对象存储 Object 级别 ACL （私有桶上传后也可以公开访问）
对象存储支持获取临时访问链接（预签名URL）
解决上传文件时需要把文件全部读入内存，导致内存占用过大的问题
优化 FTP SFTP 的性能问题，使用了 Apache 对象池
修复了 WebDav 的兼容性问题，经过测试支持坚果云、NextCloud ，其它平台理论上也支持，可自行测试
修复某些 SpringBoot 版本下无法使用本地存储的问题
存储平台的 getClient 方法加锁，解决并发情况下重复初始化的问题
通过反射调用指定存储平台的方法，使其调用自定义存储平台的独有方法更方便
增加了文件适配器接口，可以自行适配各种类型的资源
整体架构优化、使其更易于使用

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>1.0.0</version>
</dependency>

阅读文档开始使用！

Full Changelog: https://github.com/1171736840/spring-file-storage/compare/1.0.0...1.0.0

0.7.0

1 year ago

增加对谷歌云存储的支持，由 kytrun 提供，非常感谢
修复 WebDAV 提示有误
使用 Tika 识别 ContentType

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>0.7.0</version>
</dependency>

阅读文档开始使用！

0.6.1

1 year ago

优化 ContentType 的识别方式

此版本支持本地、FTP、SFTP、WebDAV、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、AWS S3、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>0.6.1</version>
</dependency>

阅读文档开始使用！

0.6.0

1 year ago

增加对 FTP、SFTP、WebDAV 的支持
增加增强版的本地存储平台 LocalPlusFileStorage，建议新项目使用，老项目为了兼容性继续使用 LocalFileStorage
优化又拍云 Uss
优化七牛云 Kodo

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>0.6.0</version>
</dependency>

阅读文档开始使用！

0.5.0

1 year ago

增加对 ContentType 和 ContentLength 的支持
增加 FileInfo 属性：attr，这是一个字典对象，可以更方便的关联数据
将 FileInfo 的 id 属性由 Integer 改为 String，使其更通用
其它性能优化
升级相关依赖版本

此版本支持本地、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、AWS S3、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台

建议通过 maven 引入

<dependency>
    <groupId>cn.xuyanwu</groupId>
    <artifactId>spring-file-storage</artifactId>
    <version>0.5.0</version>
</dependency>

阅读文档开始使用！