X File Storage 技术文档

1. 安装指南

环境要求

• JDK 8+
• Maven 3.0+
• Spring Boot 2.x+（可选）
• Solon（可选）

Maven 依赖配置

在项目的 pom.xml 文件中添加以下依赖：

<!-- 核心依赖 -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.3.0</version>
</dependency>

<!-- 存储平台SDK（以阿里云OSS为例） -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>

2. 项目使用说明

基础配置

在 application.yml 中配置存储平台信息：

dromara:
  x-file-storage:
    default-platform: aliyun-oss-1
    aliyun-oss:
      - platform: aliyun-oss-1
        enable-storage: true
        access-key: your-access-key
        secret-key: your-secret-key
        end-point: your-endpoint
        bucket-name: your-bucket
        domain: https://your-domain.com/
        base-path: test/

启用服务

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

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

3. API使用文档

文件上传

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

    // 基础上传
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        return fileStorageService.of(file).upload();
    }

    // 带参数上传
    @PostMapping("/upload2")
    public String upload2(MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file)
                .setPath("upload/")
                .setSaveFilename("custom.jpg")
                .setObjectId("123")
                .setObjectType("user")
                .putAttr("role","admin")
                .upload();
        return fileInfo.getUrl();
    }
}

图片处理

// 图片缩放+缩略图
@PostMapping("/upload-image")
public FileInfo uploadImage(MultipartFile file) {
    return fileStorageService.of(file)
            .image(img -> img.size(1000,1000))
            .thumbnail(th -> th.size(200,200))
            .upload();
}

文件操作

// 文件存在检查
boolean exists = fileStorageService.exists(fileInfo);

// 文件下载
byte[] bytes = fileStorageService.download(fileInfo).bytes();

// 文件删除
fileStorageService.delete(fileInfo);

// 通过URL操作
fileStorageService.delete("https://example.com/file.jpg");

4. 项目安装方式

Spring Boot项目

1. 添加Maven依赖
2. 配置application.yml
3. 添加@EnableFileStorage注解
4. 注入FileStorageService使用

Solon项目

参考官方文档中的"在Solon中使用"章节

非Spring环境

参考官方文档中的"脱离SpringBoot单独使用"章节

多平台支持

项目支持30+存储平台，包括：

• 本地存储
• FTP/SFTP
• 主流云存储(阿里云OSS、腾讯云COS等)
• WebDAV
• MinIO
• MongoDB GridFS
• FastDFS等

各平台配置方式类似，只需引入对应SDK并在配置文件中添加平台配置即可。