# 1 简介
苍穹默认实现了以磁盘文件的访问方式实现了文件存储服务，如果客户需要接入自己的文件存储实现，可以开发实现kd.bos.filestorage.spi.FileStorageService接口。
> 公有如阿里OSS，华为OBS，AWS S3等对象存储服务也可以映射为磁盘文件，无需二次开发即可利用苍穹默认的文件服务实现文件存取。
苍穹业务代码访问文件存储服务时，首先通过bos-fileservice-sdk-1.0.jar包的kd.bos.fileservice.FileServiceFactory()工厂类获取到FileStorageService具体的实现，然后执行实现类的上传下载删除接口的具体逻辑。
# 2 应用场景
有存储文件需求的场景。
# 3 接口说明
文件存储相关接口定义和实现存在于bos-fileservice-sdk-1.0.jar中。对于使用者来说只需要调用kd.bos.fileservice.spiimpl.FileStorageSPIFactory类创建文件存储对象FileService，然后调用FileStorageService对象的接口方法即可。
## 3.1 接口列表
***FileStorageSPIFactory***
| 静态方法 | 说明 |
| - | - |
| getFileStorageService | 创建文件存储服务对象 |
***FileStorageService***
| 方法 | 说明 |
| - | - |
| setConfig | 设置文件存储配置参数 |
| getForbiddenExtensions | 获取文件服务器禁止的文件扩展名集合 |
| getTicket | 获取文件服务器的Ticket |
| upload | 上传文件 |
| getInputStream | 读取指定文件的文件流 |
| download | 下载文件 |
| delete | 删除文件 |
## 3.2 接口详情
### getFileStorageService
+ **功能描述**
创建文件存储服务对象。
+ **方法**
```java
public static FileStorageService getFileStorageService(String fileServiceType,String className)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| fileServiceType | String | 文件存储类型（本地磁盘、S3或Swift） |
| className | String | FileStorageService对象的实现类名 |
+ **返回值**
返回FileStorageService对象。
### setConfig
+ **功能描述**
设置文件存储配置参数。例如S3、Swift的用户名，密码配置等。
+ **方法**
```java
void setConfig(FileStorageConfig fileStorageConfig)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| fileStorageConfig | FileStorageConfig | 文件存储服务配置对象 |
+ **返回值**
无
### upload
+ **功能描述**
上传文件。
+ **方法**
```java
String upload(InputStream inputStream, String path, String fileName,boolean isCreateNewFileWhenExists, Map<String, String> headers)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| inputStream | InputStream | 文件输入流 |
| path | String | 文件路径 |
| fileName | String | 文件名 |
| isCreateNewFileWhenExists | boolean | 文件已存在是否新建 |
| headers | Map<String, String> | 请求参数 |
+ **返回值**
返回文件存储URL。
### getInputStream
+ **功能描述**
读取指定文件的文件流。
+ **方法**
```java
InputStream getInputStream(String path,String userAgent)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
| userAgent | String | 用户代理字符串 |
+ **返回值**
返回文件流。
### download
+ **功能描述**
下载指定文件并输出到文件流中。
+ **方法**
```java
void download(String path, OutputStream out, String userAgent)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
| out | OutputStream | 文件输出流 |
| userAgent | String | 用户代理字符串 |
+ **返回值**
无
### delete
+ **功能描述**
删除指定文件。
+ **方法**
```java
void delete(String path)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
+ **返回值**
无
### 示例工程
可以参考bos-filestorage-swift样例工程源码
```java
//详见bos-filestorage-swift源码
public class SwiftStorage implements FileStorageService {
public void setConfig(FileStorageConfig fileStorageConfig) { ... }
public InputStream getInputStream(String path,String userAgent) throws Exception { ... }
public void download(String path, OutputStream outputStream, String userAgent) throws Exception { ... }
public void delete(String path) throws Exception { ... }
public String upload(InputStream inputStream, String path, String fileName,boolean isCreateNewFileWhenExists, Map<String, String> headers) throws Exception{ ... }
...
}
```
在MC中swift样板工程需要配置的属性：
| 属性 | 值 | 说明 |
| - | - | - |
| attachmentServer.container | upload | 容器名，支持多个容器以平衡性能，用逗号隔开如 upload1,upload2,upload3将随机选择一个（容器先请用管理员账户创建好） |
| attachmentServer.authuser | xxx | 用户名 |
| attachmentServer.authpass | xxx | 密码 |
| attachmentServer.authtype | xxx | swift认证模式如：none,tempauth,keystone |
| attachmentServer.upload.timeout | 600 | 上传超时时间默认600秒 |
| attachmentServer.fileStorage.className | 实现了kd.bos.filestorage.spi.FileStorageService接口的类的全类名 | 例如bos-filestorage-swift样例工程中的SwiftStorage类的全类名 |
这些属性会封装在FileStorageConfig对象中。如果要想实现华为OBS存储，则按照swift样板工程实现即可。部署时将实现的工程打包，上传到服务器AppStore中即可。
# 4 公众号文章
[1分钟了解苍穹自定义文件存储服务](https://mp.weixin.qq.com/s/s9QXo94fNeqGhOcpbEh4cg)
