X File Storage 脱离 SpringBoot 独立使用教程：轻量级文件存储解决方案

X File Storage 脱离 SpringBoot 独立使用教程：轻量级文件存储解决方案

【免费下载链接】x-file-storage一行代码将文件存储到 本地、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项目地址: https://gitcode.com/gh_mirrors/xfi/x-file-storage

X File Storage 是一款功能强大的轻量级文件存储工具，支持一行代码将文件存储到本地、FTP、SFTP、WebDAV、阿里云OSS、华为云OBS等多种平台。本教程将详细介绍如何在非SpringBoot环境中独立使用X File Storage，让你快速实现跨平台文件存储功能。

📌 核心优势与适用场景

X File Storage 脱离SpringBoot独立使用时，依然保留了其核心优势：

• 零框架依赖：纯Java环境即可运行，无需Spring生态支持
• 多平台兼容：支持20+种存储平台，轻松应对不同存储需求
• 极简API：一行代码完成文件上传，大幅降低开发复杂度
• 轻量级设计：核心包体积小，无冗余依赖，适合各种项目场景

特别适合以下开发场景：

• 传统Java SE项目
• 非Spring框架的Web项目
• 工具类应用或桌面程序
• 对依赖体积有严格要求的微服务

X File Storage 支持多种存储平台的架构设计

📦 快速开始：环境准备

1. 克隆项目代码

首先需要获取X File Storage的源代码：

git clone https://gitcode.com/gh_mirrors/xfi/x-file-storage

2. 引入核心依赖

在你的项目中引入x-file-storage-core核心包，无需Spring相关依赖：

<dependency> <groupId>org.dromara.x-file-storage</groupId> <artifactId>x-file-storage-core</artifactId> <version>2.1.0</version> </dependency>

3. 添加存储平台依赖

根据需要存储的平台，添加对应的依赖。以下是常用平台的依赖配置：

本地存储

无需额外依赖

FTP存储

<dependency> <groupId>commons-net</groupId> <artifactId>commons-net</artifactId> <version>3.9.0</version> </dependency> <dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-extra</artifactId> <version>5.8.22</version> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-pool2</artifactId> <version>2.11.1</version> </dependency>

阿里云OSS

<dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>3.16.1</version> </dependency>

更多平台的依赖配置可参考官方文档：docs/快速入门.md

⚙️ 配置与初始化

1. 创建存储平台配置

以FTP存储为例，手动创建存储平台配置：

// 创建配置对象 FileStorageProperties properties = new FileStorageProperties(); // 设置默认存储平台 properties.setDefaultPlatform("ftp-1"); // 配置FTP存储平台 FtpConfig ftp = new FtpConfig(); ftp.setPlatform("ftp-1"); // 存储平台标识 ftp.setHost("192.168.3.100"); // FTP服务器地址 ftp.setPort(2121); // FTP端口 ftp.setUser("root"); // 用户名 ftp.setPassword("123456"); // 密码 ftp.setDomain("ftp://192.168.3.100:2121/"); // 访问域名 ftp.setBasePath("ftp/"); // 基础路径 ftp.setStoragePath("/"); // 存储路径 // 将FTP配置添加到属性中 properties.setFtp(Collections.singletonList(ftp));

2. 初始化FileStorageService

通过构建器模式创建FileStorageService实例：

// 创建并初始化FileStorageService FileStorageService service = FileStorageServiceBuilder .create(properties) // 使用配置 .useDefault() // 使用默认组件 .build(); // 构建服务实例

🚀 核心功能使用示例

文件上传

上传文件到默认存储平台：

// 上传本地文件 FileInfo fileInfo = service.of(new File("D:\\Desktop\\example.png")) .setPath("upload/2023/") // 设置相对路径 .setObjectId("1001") // 关联对象ID（可选） .setObjectType("user") // 关联对象类型（可选） .upload(); // 执行上传 // 输出上传结果 System.out.println("文件URL: " + fileInfo.getUrl()); System.out.println("文件大小: " + fileInfo.getSize()); System.out.println("存储平台: " + fileInfo.getPlatform());

文件存在性检查

// 构造文件信息对象 FileInfo fileInfo = new FileInfo() .setPlatform("ftp-1") .setBasePath("ftp/") .setPath("upload/2023/") .setFilename("example.png"); // 检查文件是否存在 boolean exists = service.exists(fileInfo); System.out.println("文件是否存在: " + exists);

文件下载

// 下载文件为字节数组 byte[] fileBytes = service.download(fileInfo).bytes(); // 下载文件到本地 service.download(fileInfo).toFile(new File("D:\\Downloads\\example.png"));

文件删除

// 删除文件 boolean deleted = service.delete(fileInfo); System.out.println("文件是否删除成功: " + deleted);

🔧 高级配置选项

多平台配置

可以同时配置多个存储平台，根据需要选择使用：

// 配置本地存储 LocalPlusConfig local = new LocalPlusConfig(); local.setPlatform("local-1"); local.setEnableStorage(true); local.setStoragePath("/data/files/"); local.setDomain("http://localhost:8080/files/"); // 添加到配置 properties.setLocalPlus(Collections.singletonList(local)); // 使用指定平台上传 FileInfo fileInfo = service.of(new File("test.txt")) .setPlatform("local-1") // 指定使用本地存储 .upload();

进度监听

上传大文件时可以添加进度监听：

service.of(new File("large-file.zip")) .setProgressListener(progress -> { System.out.println("上传进度: " + progress.getProgress() + "%"); System.out.println("已上传: " + progress.getUploadedSize() + "字节"); System.out.println("总大小: " + progress.getTotalSize() + "字节"); }) .upload();

❓ 常见问题解决

依赖冲突怎么办？

如果遇到依赖冲突（尤其是不同存储平台的SDK之间），可以使用Maven的exclusions排除冲突依赖：

<dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>3.16.1</version> <exclusions> <exclusion> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> </exclusion> </exclusions> </dependency>

如何自定义文件命名规则？

可以通过实现FileNameGenerator接口来自定义文件命名：

service.setFileNameGenerator((fileWrapper, fileStorage) -> { // 生成UUID作为文件名 String uuid = UUID.randomUUID().toString(); // 获取文件扩展名 String ext = FilenameUtils.getExtension(fileWrapper.getOriginalFilename()); return uuid + "." + ext; });

支持的全部存储平台有哪些？

X File Storage支持20+种存储平台，包括：本地存储、FTP、SFTP、WebDAV、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云BOS、又拍云USS、MinIO、AWS S3、FastDFS、Azure Blob Storage等。完整列表可参考docs/存储平台.md

📚 相关资源

• 官方文档：docs/
• 核心源代码：x-file-storage-core/src/main/java/org/dromara/x/file/storage/core/
• 存储平台实现：x-file-storage-core/src/main/java/org/dromara/x/file/storage/core/platform/
• 示例代码：x-file-storage-tests/x-file-storage-general-test/src/test/java/org/dromara/x/file/storage/test/

通过本教程，你已经掌握了X File Storage脱离SpringBoot独立使用的方法。无论是小型工具还是大型应用，X File Storage都能为你提供简单、高效、可靠的文件存储解决方案。开始尝试使用，体验跨平台文件存储的便捷吧！

【免费下载链接】x-file-storage一行代码将文件存储到 本地、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项目地址: https://gitcode.com/gh_mirrors/xfi/x-file-storage