# combofs

**Repository Path**: shadowedge/combofs

## Basic Information

- **Project Name**: combofs
- **Description**: 同一文件系统API
- **Primary Language**: Java
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2019-11-12
- **Last Updated**: 2021-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 统一文件存储SDK

## 典型使用：默认文件系统、默认Oracle数据源
### 环境准备
0. 添加私服

由于SDK均未存放在中央库内，因此需要对工程添加私服才可远程下载依赖库：
```xml
 <repositories>
        <!-- ComboFS 私服 -->
        <repository>
            <id>shadowedge-git</id>
            <url>https://raw.githubusercontent.com/shadowedge/maven/master/repository/</url>
        </repository>
    </repositories>
```  

1. 引入SDK

使用标准文件系统：
```xml
   <dependency>
     <groupId>keter</groupId>
     <artifactId>combofs-starter-fs</artifactId>
     <version>0.2.1.RELEASE</version>
   </dependency>
```
使用S3存储：
```xml
   <dependency>
     <groupId>keter</groupId>
     <artifactId>combofs-starter-s3</artifactId>
     <version>0.2.1.RELEASE</version>
   </dependency>
```

3. 添加配置

文件系统：
```ini
#--- 文件存储根目录 ---#
combofs.root=e:/temp/fs
```
s3：
```ini
combofs.s3.bucket=your_bucket
combofs.s3.endpoint=your_endpoint
combofs.s3.accessKey=your_accessKey
combofs.s3.secretKey=your_secretKey
```

### 开始使用
注入ComboFs接口对象：
```java
    @Autowired private ComboFs fs;
```
S3环境可以使用专属接口，具有部分特性功能：
```java
@Autowired private ComboS3 fs;
```
使用API操作文件：
```java
 // 测试用的本地文件
        String testFileUri = "e:/temp/test.xml";
        java.io.File f = new java.io.File(testFileUri);
        // 保存文件：只保存文件流
        ComboFile file = fs.save(Files.toByteArray(f));
        logger.info("读取文件: id={}, uri={}",fs.getComboFile(file.getId()).getId(),fs.getComboFile(file.getId()).getUri());
        Assert.isTrue ("61a070c47acf2e43eed674bc70ca8b9f".equals(fs.getMD5(file.getId())),"比对MD5");

        logger.info("读取文件流：性能最好!");
        Files.write(fs.getBytes(file.getId()),new java.io.File("e:/temp/output.xml"));
        logger.info("读取文件完整信息: id={}",fs.getComboFile(file.getId()).getId());

        // 保存文件：保存流和文件元数据
        // 构建元数据
        FileMeta meta =  FileMeta.build()
                .add("kaka","keke")
                .add("haha","hehe");
        file = fs.save(Files.toByteArray(f) ,meta);
        logger.info("读取文件:{}",fs.getComboFile(file.getId()));
        logger.info("文件删除：");
        Long id = 1234L;
        fs.delete(id);
```

SDK支持文件MD5读取功能，但在文件保存时并不进行计算，而是异步持久化md5信息。
如需校验，调用方可在文件保存成功后可通过API自行读取比对。

## 扩展使用：其他文件系统、其他数据源（进行中）

如需使用其他文件系统或数据源，则需在应用中提供相应的依赖库组件和配置即可。

## 设计说明
- 统一存取

  SDK统一使用字节数组(byte[])保存文件，写入成功后返回文件唯一ID（Snowflake Sequence）
  
  SDK通过ID进行文件读取


- 元数据存储

  SDK支持对Map<String,String>形式提供的文件元数据进行存储，前提是需要提供数据源

- 自动目录生成

  为避免同一目录下存放大量文件，SDK会对文件ID取HashCode后映射到256（一级）*16（二级）的子目录，并以**文件ID作为文件名**统一保存文件。

- 模块按需加载

  SDK会根据当前应用中的依赖库存在情况判断使用何种组件，

  如：依赖库中引入了S3驱动，则使用S3文件系统；

  依赖库中引入了Mysql/Sqlite/MongoDB驱动，则使用MySql/Sqlite/Mongodb作为数据源（未实现）；

  也可以通过`配置文件`强制使用的文件系统或数据源类型(未实现)

- 组件可替换
  
  可以使用自定义组件替换默认策略，目前支持ID生成策略、目录生成策略等。

  替换方法：自定义类实现SDK接口，声明为Spring容器组件即可，如：
  ```java
    @Component
    public class MyId implements IdMaker {
        @Override
        public Long makeId() {
            // 随机ID：仅用于示例，不可用于生产系统！
            return RandomUtils.nextLong();
        }
    }
  ```