file-starter/.claude/commands/download-从URL下载文件到MinIO.md

---

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

FileService.downloadAndSaveFromUrl 使用指令

功能概述

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

基本使用

导入服务

import { FileService } from '@/server/modules/files/file.service';
import { DataSource } from 'typeorm';

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

基础调用

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. 下载用户头像

const avatarFile = await fileService.downloadAndSaveFromUrl(
  'https://thirdwx.qlogo.cn/mmopen/vi_32/xxx/132',
  {
    uploadUserId: userId,
    customPath: 'avatars/',
    mimeType: 'image/jpeg'
  }
);

2. 下载文档附件

const docFile = await fileService.downloadAndSaveFromUrl(
  'https://example.com/report.pdf',
  {
    uploadUserId: userId,
    customFileName: 'monthly-report.pdf',
    customPath: 'documents/reports/'
  }
);

3. 批量下载图片

const imageUrls = ['url1.jpg', 'url2.png', 'url3.gif'];
const results = await Promise.all(
  imageUrls.map(url => 
    fileService.downloadAndSaveFromUrl(url, { uploadUserId: userId })
  )
);

错误处理

异常类型

• 从URL下载文件失败: 网络或服务器错误
• 文件保存失败: MinIO存储或数据库错误

使用示例

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

高级配置

自定义文件名和路径

await fileService.downloadAndSaveFromUrl(
  'https://cdn.example.com/avatar.png',
  {
    uploadUserId: 1001,
    customFileName: 'user-1001-avatar.png',
    customPath: 'users/1001/profile/'
  }
);

设置超时时间

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

返回值结构

{
  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. 错误日志: 所有错误都会记录详细日志便于调试