一、介绍

        官方网址：https://x-file-storage.xuyanwu.cn/?from=domain-admin.cn#/%E5%BF%AB%E9%80%9F%E5%85%A5%E9%97%A8

        x-file-storage 是一个文件存储抽象框架（通常基于 Java/Spring Boot 生态），诞生的核心背景是解决项目中文件存储的碎片化和耦合性问题。
        简介：一行代码将文件存储到本地、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 定义了一套通用的文件存储接口（如FileStorage），底层适配不同存储实现（本地、OSS、COS 等），业务代码只需调用接口方法，无需关心具体存储源，这就很好的解决了上述的问题，实现了多平台文件存储。

下面是以java的springboot项目为例来演示

二、项目集成X-File-Storage

        第一步：引入相关依赖

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

        这里使用阿里云OSS存储，则还需要引入阿里云依赖，如果使用其他平台，则参照官方寻找依赖即可

        第二步：配置文件信息

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

# 文件上传
dromara:
  x-file-storage: #文件存储配置
    default-platform: aliyun-oss-1 #默认使用的存储平台
    thumbnail-suffix: ".min.jpg" #缩略图后缀，例如【.min.jpg】【.png】
    #对应平台的配置写在这里，注意缩进要对齐
    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: dkd-images/ # 基础路径，这里也可以修改成自己想要的路径
# 其中?是需要再官网上替换成自己的配置信息。

        更多配置信息可去参考官方说明

第三步：在启动类添加注解@EnableFileStorage

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

}

三、修改upload上传接口代码

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

/**
  * 通用上传请求（单个）
*/
@PostMapping("/upload")
public AjaxResult uploadFile(MultipartFile file) throws Exception {

    try {
        // 指定oss保存文件路径
        String objectName = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")) + "/";
        // 上传图片，成功返回文件信息
        FileInfo fileInfo = fileStorageService.of(file)
                                            .setPath(objectName)
                                            .upload();
        // 设置返回结果
        AjaxResult ajax = AjaxResult.success();
        ajax.put("url", fileInfo.getUrl());
        ajax.put("fileName", fileInfo.getUrl());  
        ajax.put("newFileName", fileInfo.getUrl());
        ajax.put("originalFilename", file.getOriginalFilename());
        return ajax;
    } catch (Exception e) {
        return AjaxResult.error(e.getMessage());
    }
}

响应结果：

{
    "msg": "操作成功",
    "fileName": "https://ruoyidkd.oss-cn-beijing.aliyuncs.com/dkd-images/2025/11/22/6921650b9085216fc5fd5f0a.jpg",
    "code": 200,
    "newFileName": "6921650b9085216fc5fd5f0a.jpg",
    "url": "https://ruoyidkd.oss-cn-beijing.aliyuncs.com/dkd-images/2025/11/22/6921650b9085216fc5fd5f0a.jpg",
    "originalFilename": "2.jpg"
}

最后在阿里云bucket里面即可看到刚刚上传的文件