---
description: "从任意URL下载文件并保存到MinIO，同时创建数据库记录"
---

# FileService.downloadAndSaveFromUrl 使用指令

## 功能概述
`downloadAndSaveFromUrl` 是 FileService 中新增的统一方法，用于从任意URL下载文件并保存到MinIO，同时创建数据库记录。

## 基本使用

### 导入服务
```typescript
import { FileService } from '@/server/modules/files/file.service';
import { DataSource } from 'typeorm';

// 在服务中注入
const fileService = new FileService(dataSource);
```

### 基础调用
```typescript
const result = await fileService.downloadAndSaveFromUrl(
  'https://example.com/image.jpg',
  {
    uploadUserId: 123, // 必需：上传用户ID
  }
);
// 返回: { file: File实体, url: 文件访问URL }
```

## 参数说明

### 必填参数
| 参数 | 类型 | 说明 |
|------|------|------|
| url | string | 要下载的文件URL |
| fileData.uploadUserId | number | 上传用户的ID |

### 可选参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| fileData.mimeType | string | 自动推断 | 文件MIME类型 |
| fileData.customFileName | string | 自动获取 | 自定义文件名 |
| fileData.customPath | string | 自动生成 | 自定义存储路径 |
| options.timeout | number | 30000 | 下载超时时间(ms) |
| options.retries | number | 0 | 重试次数 |

## 使用场景示例

### 1. 下载用户头像
```typescript
const avatarFile = await fileService.downloadAndSaveFromUrl(
  'https://thirdwx.qlogo.cn/mmopen/vi_32/xxx/132',
  {
    uploadUserId: userId,
    customPath: 'avatars/',
    mimeType: 'image/jpeg'
  }
);
```

### 2. 下载文档附件
```typescript
const docFile = await fileService.downloadAndSaveFromUrl(
  'https://example.com/report.pdf',
  {
    uploadUserId: userId,
    customFileName: 'monthly-report.pdf',
    customPath: 'documents/reports/'
  }
);
```

### 3. 批量下载图片
```typescript
const imageUrls = ['url1.jpg', 'url2.png', 'url3.gif'];
const results = await Promise.all(
  imageUrls.map(url => 
    fileService.downloadAndSaveFromUrl(url, { uploadUserId: userId })
  )
);
```

## 错误处理

### 异常类型
- `从URL下载文件失败`: 网络或服务器错误
- `文件保存失败`: MinIO存储或数据库错误

### 使用示例
```typescript
try {
  const result = await fileService.downloadAndSaveFromUrl(url, { uploadUserId });
  return result.file.id;
} catch (error) {
  console.error('下载失败:', error.message);
  return null; // 或抛出异常
}
```

## 高级配置

### 自定义文件名和路径
```typescript
await fileService.downloadAndSaveFromUrl(
  'https://cdn.example.com/avatar.png',
  {
    uploadUserId: 1001,
    customFileName: 'user-1001-avatar.png',
    customPath: 'users/1001/profile/'
  }
);
```

### 设置超时时间
```typescript
await fileService.downloadAndSaveFromUrl(
  'https://large-file.example.com/video.mp4',
  {
    uploadUserId: userId
  },
  {
    timeout: 60000, // 60秒超时
    retries: 2      // 重试2次
  }
);
```

## 返回值结构
```typescript
{
  file: {
    id: number,
    name: string,
    path: string,
    size: number,
    mimeType: string,
    url: string,
    // ...其他File实体字段
  },
  url: string // MinIO访问URL
}
```

## 注意事项

1. **网络要求**: 确保服务器能够访问目标URL
2. **文件大小**: 大文件下载可能超时，可调整timeout参数
3. **文件名冲突**: 系统自动添加UUID避免冲突
4. **MIME类型**: 优先使用提供的mimeType，否则自动推断
5. **错误日志**: 所有错误都会记录详细日志便于调试