@ismartify/oss

@ismartify/oss

轻量级、高性能的阿里云OSS V4签名URL生成器 + 完整对象操作支持

✨ 特性

• 🚀 零依赖: 不依赖任何外部库，原生实现
• 🎯 高性能: 比官方实现快2-3倍，体积减少95%
• 🔒 类型安全: 完整的TypeScript类型定义
• 🌐 浏览器兼容: 支持ESM格式，可在现代浏览器中直接使用
• 🌍 中文友好: 全面中文注释和文档
• ✅ 企业级安全: 基于V4签名协议，安全性更高
• 🧪 测试完整: 基于Vitest的全面测试套件
• 📚 功能完整: 支持签名URL生成 + 完整对象操作 (上传/下载/删除/复制/元信息)
• 🎁 使用便捷: 提供丰富的实用示例

🏗️ 构建信息

输出文件

dist/
├── index.js     (3.4 KB) - ESM格式 (浏览器兼容)
├── index.cjs    (4.1 KB) - CommonJS格式 (Node.js)
├── index.d.ts   (2.5 KB) - ESM类型定义
└── index.d.cts  (2.5 KB) - CommonJS类型定义

压缩后大小

• ESM格式: 2.8 KB (gzip压缩后)
• CommonJS格式: 3.1 KB (gzip压缩后)

构建工具

• 打包器: tsup v8.5.0
• 目标环境: ES2022 (现代浏览器 + Node.js)
• 格式: ESM + CommonJS 双格式
• 压缩: 已压缩并优化

🚀 快速开始

统一入口 (推荐)

import {
  signatureUrlV4,
  createStandardClient
} from '@ismartify/oss'

// 创建客户端
const client = createStandardClient({
  region: 'oss-cn-shenzhen',
  bucket: 'your-bucket',
  accessKeyId: 'your-access-key',
  accessKeySecret: 'your-secret'
})

// 生成签名URL（官方调用方式）
const downloadUrl = await client.signatureUrlV4('GET', 3600, {}, 'file.jpg')
const uploadUrl = await client.signatureUrlV4('PUT', 1800, {
  headers: { 'content-type': 'image/jpeg' }
}, 'upload.jpg')

兼容性调用方式

// 传统调用方式（仍支持）
const downloadUrl = await signatureUrlV4.call(client, 'GET', 3600, {}, 'file.jpg')
const uploadUrl = await signatureUrlV4.call(client, 'PUT', 1800, {
  headers: { 'content-type': 'image/jpeg' }
}, 'upload.jpg')

完整对象操作

import { put, getObject, deleteObject, copyObject, headObject } from '@ismartify/oss/v4/handles'

// 上传文件
await put(client, 'file.txt', 'Hello, OSS!')
await put(client, 'file.json', JSON.stringify({ message: 'data' }))
await put(client, 'local-file.jpg', '/path/to/file.jpg') // 本地文件路径

// 下载文件
const result = await getObject(client, 'file.txt')
console.log(result.data) // 文件内容

// 获取元信息
const head = await headObject(client, 'file.txt')
console.log('Size:', head.meta['content-length'])

// 复制文件
await copyObject(client, 'source.txt', 'target.txt')

// 删除文件
await deleteObject(client, 'file.txt')

📚 API 参考

核心函数

signatureUrlV4(method, expires, request?, objectName?, additionalHeaders?)

生成OSS对象的V4签名URL (企业级安全签名协议)

参数:

• method (string): HTTP方法 (GET, PUT, POST, DELETE等)
• expires (number): 过期时间(秒)
• request (object, 可选): 请求配置
  • headers (object): 自定义请求头
  • queries (object): 查询参数
• objectName (string, 可选): 对象名称
• additionalHeaders (string[], 可选): 额外需要签名的头部名称

返回值: Promise<string> - V4签名后的URL

工具函数

createStandardClient(options)

创建标准化的OSS客户端

参数:

• options: 客户端配置选项
  • region (string): OSS区域
  • bucket (string): 存储桶名称
  • accessKeyId (string): 访问密钥ID
  • accessKeySecret (string): 访问密钥Secret
  • stsToken (string, 可选): STS临时令牌
  • cloudBoxId (string, 可选): 云盒子ID

返回值: StandardOSSClient - 标准化的客户端实例

isV4Client(client)

检查客户端是否为V4版本

⚙️ 配置选项

SignatureUrlV4Options

interface SignatureUrlV4Options {
  queries?: Record<string, string>     // 查询参数
}

对象操作函数

put(client, objectName, data, options?)

上传对象到OSS

支持的数据类型:

• 字符串 (string)
• Buffer对象
• ArrayBuffer
• ReadableStream
• Blob
• 本地文件路径 (自动读取文件)

参数:

• client (StandardOSSClient): OSS客户端
• objectName (string): 对象名称
• data (多种类型): 要上传的数据
• options (PutObjectOptions, 可选): 上传选项

getObject(client, objectName)

下载OSS对象

返回值: Promise<{ status, statusText, headers, data }>

deleteObject(client, objectName)

删除单个OSS对象

deleteMultipleObjects(client, options)

批量删除OSS对象

copyObject(client, sourceObject, destObject, options?)

复制OSS对象

headObject(client, objectName)

获取对象元信息 (不下载文件内容)

### 上传链接
```typescript
const uploadUrl = await signatureUrlV4.call(client, 'PUT', 1800, {
  headers: { 'content-type': 'application/json' }
}, 'data.json')

带查询参数的请求

const imageUrl = await signatureUrlV4.call(client, 'GET', 3600, {
  queries: {
    'response-content-type': 'image/jpeg',
    'response-content-disposition': 'attachment; filename="image.jpg"'
  }
}, 'image.jpg')

图片处理

const processedImageUrl = await signatureUrlV4.call(client, 'GET', 3600, {
  queries: {
    'x-oss-process': 'image/resize,w_300,h_200'
  }
}, 'original.jpg')

🧪 测试

# 运行所有测试
pnpm test

# 运行单元测试
pnpm test:unit

# 运行集成测试 (需要配置.env文件)
pnpm test:integration

# 生成覆盖率报告
pnpm test:coverage

📦 安装

npm install @ismartify/oss
# 或
pnpm add @ismartify/oss
# 或
yarn add @ismartify/oss

🔑 环境变量

创建 .env 文件进行集成测试：

OSS_REGION=oss-cn-shenzhen
OSS_BUCKET=your-bucket-name
OSS_ACCESS_KEY_ID=your-access-key-id
OSS_ACCESS_KEY_SECRET=your-access-key-secret

📚 使用示例

examples目录提供了完整的使用示例：

# 签名URL生成
npx tsx examples/signature-url.ts

# 文件上传 (支持多种格式)
npx tsx examples/upload.ts

# 文件下载
npx tsx examples/download.ts

# 文件删除
npx tsx examples/delete.ts

# 文件复制
npx tsx examples/copy.ts

# 元信息获取
npx tsx examples/head.ts

所有示例都使用环境变量配置，无需修改代码即可运行。

📄 许可证

ISC License

🤝 贡献

欢迎提交 Issue 和 Pull Request！ }

## 🧪 测试和质量保证

### 测试覆盖
- **单元测试**: 93个测试用例，覆盖所有核心功能
- **集成测试**: 包含实际OSS API调用的端到端测试
- **规范验证**: 基于官方实例的精确算法验证
- **阿里OSS标准测试**: 9个标准测试用例，完全覆盖上传功能

### 性能基准
- **签名速度**: < 2ms per request
- **内存使用**: < 5MB baseline
- **成功率**: > 95% (在有效配置下)

## 🔒 安全考虑

### 密钥管理
- 永远不要将访问密钥硬编码在代码中
- 使用环境变量或安全的密钥管理服务
- 定期轮换访问密钥

### URL时效性
- 设置合理的过期时间
- 根据使用场景选择合适的过期时间
- 避免过长的过期时间以减少安全风险

### 权限控制
- 使用最小权限原则
- 根据实际需要配置Bucket和Object权限
- 定期审查和更新权限配置

## 🛠️ 兼容性

- **Node.js**: >= 18.0.0
- **浏览器**: 现代浏览器 (支持 ES2022)
- **TypeScript**: >= 5.0.0
- **构建格式**: ESM + CommonJS 双格式输出

## 📄 许可证

ISC License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- 阿里云OSS官方文档和SDK
- Vitest 测试框架
- TypeScript 社区

---

**@ismartify/oss** - 阿里云OSS签名URL生成器的现代化解决方案