Digitalhainan OSS 使用指南

概述

本项目是 OSS 聚合工具包，封装了阿里云 OSS、华为云 OBS、S3 协议的统一接口。有 OSS 需求时，统一使用 IObjectStorageService 接口。

支持的客户端类型： aliyun（默认）| obs | s3 | ds（动态多数据源）

前置检查清单

使用 OSS 功能前，请确认：

• [ ] 项目已引入 oss-spring-boot-starter 依赖
• [ ] 已在 application-local.yml / application-dev.yml / application-prd.yml 中配置对应云厂商的 OSS 参数
• [ ] 已确定使用的客户端类型（aliyun/obs/s3/ds）

依赖配置

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>oss-spring-boot-starter</artifactId>
    <version>${digitalhainan.version}</version>
</dependency>

参考文档索引

文档	内容	链接
基础操作指南	文件上传、下载、删除、配置说明	basic-operations.md
高级功能指南	签名 URL、分片上传、断点续传、访问权限	advanced-features.md
集成指南	动态数据源切换、最佳实践、配置模板	integration-guide.md

Step-by-step 使用流程

Step 1：注入服务

@Autowired
private IObjectStorageService ossService;

Step 2：选择操作类型

操作目标	调用方法
上传字节数组	ossService.upload(objectName, bytes)
上传输入流	ossService.upload(objectName, inputStream)
上传本地文件	ossService.upload(objectName, localFile)
下载为输入流	ossService.download(objectName)
下载到本地	ossService.download(objectName, localFile)
删除文件	ossService.delete(objectName)
获取临时 URL	ossService.securityUrlStr(objectName, expirationMillis)

Step 3：处理返回结果

// 上传
ObjectStorageResponse resp = ossService.upload(objectName, bytes);

// 下载
InputStream stream = ossService.download(objectName);

// 获取临时 URL
String url = ossService.securityUrlStr(objectName, expirationMillis);

场景选择速查

场景	参考文档
文件上传/下载/删除	basic-operations.md
单/多数据源配置	basic-operations.md
签名 URL	advanced-features.md
分片上传/断点续传	advanced-features.md
动态数据源切换	integration-guide.md
最佳实践	integration-guide.md

核心方法速查

// 上传
upload(String objectName, byte[] bytes)
upload(String objectName, InputStream inputStream)
upload(String objectName, String localFile)

// 下载
download(String objectName)                    // 返回 InputStream
download(String objectName, String localFile)  // 保存到本地

// 删除
delete(String objectName)

// URL
securityUrl(String objectName, Long expiration)              // 返回 URL
securityUrlStr(String objectName, Long expiration)           // 返回 String
getObjectUrl(String objectName)                              // 自定义域名 URL
getDefaultObjectUrl(String objectName)                       // 默认域名 URL

// 分片上传
getUploadId(String objectName)
uploadPart(String objectName, String uploadId, int partNumber, long offset, long currPartSize, byte[] bytes)
completeMultipartUpload(String objectName, String uploadId, List<UploadPart> partEtags)

// 断点续传
resumeUpload(String objectName, String localFile, int taskNum, long partSize)

Do's and Don'ts

Do（推荐做法）	Don't（避免做法）
统一使用 IObjectStorageService 接口	直接使用阿里云/华为云/S3 原生 SDK
ds 模式在 finally 块中调用 OssDynamicDataSourceHolder.clearDataSource()	动态数据源切换后不清除，导致后续操作数据源错乱
分片上传 partNumber 从 1 开始计数	从 0 开始计数
断点续传 partSize 控制在 100KB ~ 5GB 范围	设置过大或过小导致性能问题