Relax Box

外观

Java 工具包 - 多平台文件存储神器 X-File-Storage

约 2330 字大约 8 分钟

2026-05-25

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

X-File-Storage

X-File-Storage（原名 X Spring File Storage）是一个基于 Java 的开源文件存储中间件，目前已捐赠至 Dromara 开源组织。该项目允许开发者通过一行代码将文件存储到各种存储平台中，极大地简化了文件上传、下载和管理的复杂性。

官方文档：https://x-file-storage.xuyanwu.cn/#/

GIT: https://gitee.com/dromara/x-file-storage

核心价值主张

在传统的应用开发中，文件存储往往需要针对不同的存储平台编写不同的代码，当需要更换存储方式时，经常面临大量重构工作。X-File-Storage 通过统一的 API 接口，解决了这一痛点，让开发者能够：

  • 使用同一套代码应对不同的存储需求

  • 轻松在多种存储平台间切换或迁移

  • 专注于业务逻辑，而非文件存储细节

支持的存储平台

X-File-Storage 支持几乎所有主流的存储平台，包括但不限于：

  • 本地存储：本地磁盘

  • 云存储服务：阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS

  • 国际云服务：Amazon S3、GoogleCloud Storage、Azure Blob Storage

  • 开源存储系统：MinIO、FastDFS

  • 其他协议：FTP、SFTP、WebDAV

  • 新兴平台：火山引擎 TOS、Cloudflare R2、金山云 KS3 等

特别值得一提的是，通过 WebDAV 连接到 Alist 后，还可以间接使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务，大大扩展了其应用范围。

快速入门指南

环境准备与依赖配置

X-File-Storage 支持 Spring Boot 环境，也需要 JDK 8+ 。

在 pom.xml 中引入相关依赖，这里以阿里云 OSS 为例：

<!-- 引入 X-File-Storage -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.3.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: ?? # 替换为你的 access-key
        secret-key: ?? # 替换为你的 secret-key
        end-point: ?? # 替换为你的 end-point
        bucket-name: ?? # 替换为你的 bucket-name
        domain: ?? # 访问域名，注意“/”结尾，例如：https://abc.oss-cn-shanghai.aliyuncs.com/
        base-path: test/ # 基础路径

启用与基础使用

在 Spring Boot 启动类上添加 @EnableFileStorage 注解：

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

在 Controller 中注入并使用 FileStorageService：

@RestController
public class FileDetailController {
    
    @Autowired
    private FileStorageService fileStorageService; 

    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        // 只需要这一行代码即可上传成功
        return fileStorageService.of(file).setPath(LocalDate.now() + StrUtil.SLASH).upload();
    }
}

高级功能与实战技巧

灵活的上传选项

X-File-Storage 提供了丰富的上传选项，满足各种业务场景需求：

/**
 * 上传文件，成功返回文件 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();
}

图片处理与缩略图生成

X-File-Storage 内置了图片处理功能，基于 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();
}

高级上传技巧

对于大文件或特殊场景，X-File-Storage 提供了更多高级功能：

/**
 * 直接读取 HttpServletRequest 中的文件进行上传
 * 可以实现文件不落盘，边读取边上传，速度更快
 */
@PostMapping("/upload-request")
public FileInfo uploadRequest(HttpServletRequest request) {
    return fileStorageService.of(request).upload();
}

使用此功能需要在配置文件中开启 multipart 懒加载：

spring:
  servlet:
    multipart:
      max-file-size: 10MB # 文件大小限制
      max-request-size: 100MB # 请求大小限制
      resolve-lazily: true # 开启懒加载

文件管理与进阶功能

文件操作全套解决方案

X-File-Storage 不仅支持文件上传，还提供了一套完整的文件管理功能：

// 根据 URL 获取文件信息
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");

保存上传记录

通过实现 FileRecorder 接口，可以将文件信息保存到数据库中，方便后续管理和检索。官方推荐的数据库表结构如下：

CREATE TABLE `file_detail`
(
    `id`                varchar(32)  NOT NULL COMMENT '文件id',
    `url`               varchar(512) NOT NULL COMMENT '文件访问地址',
    `size`              bigint(20)   DEFAULT NULL COMMENT '文件大小，单位字节',
    `filename`          varchar(256) DEFAULT NULL COMMENT '文件名称',
    `original_filename` varchar(256) DEFAULT NULL COMMENT '原始文件名',
    `base_path`         varchar(256) DEFAULT NULL COMMENT '基础存储路径',
    `path`              varchar(256) DEFAULT NULL COMMENT '存储路径',
    `ext`               varchar(32)  DEFAULT NULL COMMENT '文件扩展名',
    `content_type`      varchar(128) DEFAULT NULL COMMENT 'MIME类型',
    `platform`          varchar(32)  DEFAULT NULL COMMENT '存储平台',
    `th_url`            varchar(512) DEFAULT NULL COMMENT '缩略图访问路径',
    `th_filename`       varchar(256) DEFAULT NULL COMMENT '缩略图名称',
    `th_size`           bigint(20)   DEFAULT NULL COMMENT '缩略图大小，单位字节',
    `th_content_type`   varchar(128) DEFAULT NULL COMMENT '缩略图MIME类型',
    `object_id`         varchar(32)  DEFAULT NULL COMMENT '文件所属对象id',
    -- 其他字段...
)

跨平台文件迁移

X-File-Storage 支持在不同存储平台之间迁移文件，当业务需要更换存储服务商时，这一功能显得尤为实用。

技术架构与设计理念

模块化设计

X-File-Storage 采用高度模块化的设计，核心特性包括：

  • 多后端支持：支持多种文件存储后端，满足不同场景的需求

  • 统一的API：通过标准的接口进行文件操作，方便集成到任何应用中

  • 易于扩展：设计为微服务架构，容易添加新的功能或者适配器

与框架的整合

除了 Spring Boot，X-File-Storage 还提供了对 Solon 框架的支持，并可以脱离 Spring Boot 单独使用，展现了其良好的框架适应性。

应用场景与最佳实践

典型应用场景

X-File-Storage 适用于多种业务场景：

  • 企业级文件管理系统：对内提供统一的文件上传、下载和分享平台

  • 图片/视频托管服务：适用于媒体网站、社交媒体平台等

  • 多云策略实施：帮助企业避免供应商锁定，灵活调配存储资源

  • 数据迁移与备份：方便在不同存储系统间迁移数据

性能与安全性建议

在实际生产环境中，建议考虑以下方面：

  • 大文件上传：X-File-Storage 支持大文件自动分片上传，适合处理大体积文件

  • 权限控制：通过自定义属性和切面实现精细化的访问控制

  • 资源清理：合理管理存储空间，定期清理无用文件

总结

X-File-Storage 2.3.0 作为一个功能全面的文件存储中间件，通过简化的 API 设计和广泛存储平台支持，极大地降低了Java开发者在文件存储方面的复杂度。其主要优势包括：

  • 极简API：一行代码完成文件上传，降低学习成本

  • 平台无关性：支持众多存储平台，避免供应商锁定

  • 功能全面：从基础上传下载到高级功能如缩略图生成、跨平台迁移

  • 持续进化：紧跟技术发展趋势，定期更新加入新特性

  • 良好扩展性：支持自定义存储平台和功能扩展

对于正在寻找文件存储解决方案的Java开发者，X-File-Storage 无疑是一个值得尝试的选择，它能显著提升开发效率，让开发者更专注于核心业务逻辑的实现。

版权归属：今朝· Liushigong · Relax Box

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)

「放轻松，慢慢来」盒子 — 记录日常思考、学习笔记与技术总结
Copyright © 2023 - 2026 今朝（Liushigong） | 京ICP备20031061号