glsk-oss-jssdk
v1.0.6
Published
glsk-oss-jssdk
Readme
GLSK OSS JavaScript SDK
一个用于阿里云OSS文件上传的JavaScript SDK，支持分片上传、断点续传、重试机制和动态配置。
📦 安装
npm install glsk-oss-jssdk🚀 快速开始
import GlOssApi from 'glsk-oss-jssdk'
const ossApi = new GlOssApi()
// 上传文件
await ossApi.multipartUpload(
file, // 文件对象
(result) => { // 成功回调
console.log('上传成功:', result)
},
(error) => { // 失败回调
console.error('上传失败:', error)
}
)📁 项目结构
glsk-oss-jssdk/
├── package.json # 项目配置
├── rollup.config.js # 构建配置
├── src/
│ └── index.js # 主入口文件，GlOssApi类
├── api/
│ └── ossConfigService.js # OSS配置服务
├── plugin/
│ └── axios/
│ └── httpClient.js # HTTP客户端封装
└── dist/ # 构建输出目录
└── glsk-oss-jssdk.js # 打包后的文件🔧 API 文档
GlOssApi
主要的API类，提供文件上传功能。
构造函数
const ossApi = new GlOssApi(params = {})multipartUpload(file, successCallback, errCallBack, options)
分片上传大文件到阿里云OSS，支持断点续传和重试机制。
参数:
| 参数名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| file | File | - | 要上传的文件对象（必需） |
| successCallback | Function | () => {} | 上传成功回调函数 |
| errCallBack | Function | () => {} | 上传失败回调函数 |
| bucketName | String | 'zzl-filerepostorypublic' | OSS桶名 |
| dir | String | 'image' | 上传目录 |
| custAttrObj | Object | { systemSource: 'dj' } | 自定义属性对象 |
| compressObj | Object | {} | 压缩配置对象 |
| partSize | Number | 500 | 分片大小（KB，最小100KB） |
| maxRetries | Number | 3 | 最大重试次数 |
示例:
const file = document.getElementById('fileInput').files[0]
await ossApi.multipartUpload(
file,
(result) => {
console.log('上传成功:', {
attachment: result.attachment, // 文件名
aliyunAddress: result.aliyunAddress, // 阿里云地址
size: result.size // 文件大小
})
},
(error) => {
console.error('上传失败:', error)
},
'my-bucket', // 自定义桶名
'uploads/documents', // 自定义目录
{ systemSource: 'web' }, // 自定义系统来源
{}, // 压缩配置
1024, // 1MB分片大小
5 // 最大重试5次
)⚙️ 配置系统
动态配置
SDK支持从配置中心动态获取baseURL和其他配置信息：
- 自动初始化: 首次调用
multipartUpload时，SDK会自动从配置中心获取配置 - 动态baseURL: 根据配置中心返回的
baseURL动态设置HTTP请求地址 - STS凭证: 自动获取临时访问凭证用于OSS操作
配置中心接口
- 基础配置:
https://config-center-backend.glsx.com.cn/glsxAdmin/config?moduleUrl=glsk-oss-config - STS凭证:
/rop-dj-script/router/dj.api.script.common.aliyun.oss.acs.sts.credentials/1.0.0
🔒 安全机制
STS临时凭证
SDK使用阿里云STS（Security Token Service）临时凭证确保安全：
- 自动获取临时访问密钥
- 凭证具有时效性，降低安全风险
- 支持不同系统来源的权限隔离
错误处理
完善的错误处理机制：
- 网络请求失败自动重试
- 详细的错误信息输出
- 优雅的降级处理
🛠️ 开发
构建
# 安装依赖
npm install
# 构建项目
npm run build
# 生成文档
npm run doc文件说明
src/index.js
主要的API类，包含：
GlOssApi类定义multipartUpload分片上传方法encodeOSSFilename文件名编码工具
api/ossConfigService.js
配置服务，负责：
- 从配置中心获取基础配置
- 获取STS临时凭证
- 动态设置HTTP客户端baseURL
plugin/axios/httpClient.js
HTTP客户端封装，提供：
- axios实例配置
- 请求/响应拦截器
- 动态baseURL设置功能
📝 使用示例
基本上传
import GlOssApi from 'glsk-oss-jssdk'
const ossApi = new GlOssApi()
const fileInput = document.getElementById('file')
fileInput.addEventListener('change', async (event) => {
const file = event.target.files[0]
if (!file) return
try {
await ossApi.multipartUpload(
file,
(result) => {
console.log('文件上传成功:', result.aliyunAddress)
// 在页面上显示上传成功的文件链接
document.getElementById('result').innerHTML =
`<a href="${result.aliyunAddress}" target="_blank">${result.attachment}</a>`
},
(error) => {
console.error('文件上传失败:', error)
alert('上传失败: ' + error.message)
}
)
} catch (error) {
console.error('上传过程出错:', error)
}
})高级配置
// 使用自定义配置上传
await ossApi.multipartUpload(
file,
successCallback,
errorCallback,
'custom-bucket', // 自定义桶名
'documents/pdf', // 指定上传到documents/pdf目录
{
systemSource: 'dj', // 项目
},
{ // 预留图片压缩参数
},
1024, // 1MB分片大小
5 // 最大重试5次
)🔍 调试
开启详细日志：
// SDK会在控制台输出详细的上传进度和状态信息
console.log('上传进度: 45.67%')
console.log('动态设置baseURL: https://api.example.com')
console.log('第2次重试上传...')📄 许可证
ISC License
👥 贡献者
- liwk (作者)
🐛 问题反馈
如果您在使用过程中遇到问题，请提交Issue或联系开发团队。
📚 更新日志
v1.0.3
- 支持动态baseURL配置
- 优化错误处理机制
- 改进分片上传性能
注意: 本SDK依赖阿里云OSS服务和特定的配置中心接口，请确保相关服务正常运行。