mirror of
https://github.com/Afilmory/afilmory
synced 2026-04-24 23:05:05 +00:00
128 lines
3.5 KiB
Plaintext
128 lines
3.5 KiB
Plaintext
---
|
||
description:
|
||
globs: src/core/**/*.ts
|
||
alwaysApply: false
|
||
---
|
||
# 存储抽象层
|
||
|
||
本模块使用适配器模式提供了统一的存储接口，支持多种存储提供商。目前已实现 S3 存储提供商，后续可以方便地扩展其他存储服务。
|
||
|
||
## 架构设计
|
||
|
||
- **`interfaces.ts`**: 定义通用的存储接口和数据结构
|
||
- **`providers/`**: 具体的存储提供商实现
|
||
- **`s3-provider.ts`**: S3 存储提供商实现
|
||
- **`factory.ts`**: 存储提供商工厂，负责创建具体的存储实例
|
||
- **`manager.ts`**: 存储管理器，提供统一的存储操作接口
|
||
- **`adapters.ts`**: 适配器函数，保持与原有 API 的兼容性
|
||
|
||
## 使用方式
|
||
|
||
### 推荐方式：使用 StorageManager
|
||
|
||
```typescript
|
||
import { defaultStorageManager, StorageManager } from '@/core/storage'
|
||
|
||
// 使用默认存储管理器（基于环境变量配置）
|
||
const buffer = await defaultStorageManager.getFile('path/to/image.jpg')
|
||
const images = await defaultStorageManager.listImages()
|
||
const allFiles = await defaultStorageManager.listAllFiles()
|
||
const publicUrl = defaultStorageManager.generatePublicUrl('path/to/image.jpg')
|
||
const livePhotos = await defaultStorageManager.detectLivePhotos()
|
||
|
||
// 或者创建自定义配置的存储管理器
|
||
const customManager = new StorageManager({
|
||
provider: 's3',
|
||
bucket: 'my-bucket',
|
||
region: 'us-east-1',
|
||
endpoint: 'https://s3.amazonaws.com',
|
||
prefix: 'photos/',
|
||
customDomain: 'https://cdn.example.com'
|
||
})
|
||
```
|
||
|
||
### 兼容性方式：使用原有 API
|
||
|
||
```typescript
|
||
// 这些函数仍然可用，但标记为 deprecated
|
||
import {
|
||
getImageFromS3,
|
||
listImagesFromS3,
|
||
listAllFilesFromS3,
|
||
detectLivePhotos,
|
||
generateS3Url
|
||
} from '@/core/s3/operations'
|
||
|
||
const buffer = await getImageFromS3('path/to/image.jpg')
|
||
const images = await listImagesFromS3()
|
||
```
|
||
|
||
### 直接使用存储提供商
|
||
|
||
```typescript
|
||
import { S3StorageProvider } from '@/core/storage'
|
||
|
||
const s3Provider = new S3StorageProvider({
|
||
provider: 's3',
|
||
bucket: 'my-bucket',
|
||
region: 'us-east-1',
|
||
// ... 其他配置
|
||
})
|
||
|
||
const buffer = await s3Provider.getFile('path/to/image.jpg')
|
||
```
|
||
|
||
## 扩展新的存储提供商
|
||
|
||
1. 实现 `StorageProvider` 接口：
|
||
|
||
```typescript
|
||
import { StorageProvider, StorageObject } from '@/core/storage/interfaces'
|
||
|
||
export class MyStorageProvider implements StorageProvider {
|
||
async getFile(key: string, logger?: Logger['s3']): Promise<Buffer | null> {
|
||
// 实现文件获取逻辑
|
||
}
|
||
|
||
async listImages(): Promise<StorageObject[]> {
|
||
// 实现图片列表逻辑
|
||
}
|
||
|
||
// ... 实现其他接口方法
|
||
}
|
||
```
|
||
|
||
2. 在工厂类中注册新的提供商：
|
||
|
||
```typescript
|
||
// 在 factory.ts 中添加新的 case
|
||
case 'my-storage':
|
||
return new MyStorageProvider(config)
|
||
```
|
||
|
||
3. 更新 `StorageConfig` 接口的 `provider` 类型。
|
||
|
||
## 优势
|
||
|
||
1. **解耦**: 业务逻辑与具体存储实现分离
|
||
2. **可扩展**: 轻松添加新的存储提供商
|
||
3. **统一接口**: 所有存储操作使用相同的 API
|
||
4. **向后兼容**: 保持原有 API 的兼容性
|
||
5. **类型安全**: 完整的 TypeScript 类型支持
|
||
6. **配置灵活**: 支持多种配置方式
|
||
|
||
## 迁移指南
|
||
|
||
现有代码可以继续使用原有的 S3 函数，无需立即修改。建议在新代码中使用 `StorageManager` API，并逐步迁移现有代码。
|
||
|
||
旧代码：
|
||
```typescript
|
||
import { getImageFromS3 } from '@/core/s3/operations'
|
||
const buffer = await getImageFromS3('key')
|
||
```
|
||
|
||
新代码：
|
||
```typescript
|
||
import { defaultStorageManager } from '@/core/storage'
|
||
const buffer = await defaultStorageManager.getFile('key')
|
||
``` |