create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/shared-services/file-storage/bucket-resolver.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview 存储桶解析器
+ *
+ * 本文件实现了存储桶的智能解析功能，负责：
+ * - 根据 IP 地址进行区域感知的存储桶选择
+ * - 根据公开/私有属性选择合适的存储桶
+ * - 验证存储桶配置的有效性
+ *
+ * @module file-storage/bucket-resolver
+ */
+
+import { Injectable, Inject } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { FileBucketVendor } from '@prisma/client';
+
+import { PardxUploader } from '@app/clients/internal/file-storage';
+import { IpInfoService } from '@app/shared-services/ip-info';
+import { AppConfig } from '@/config/validation';
+import arrayUtil from '@/utils/array.util';
+import enviromentUtil from '@/utils/enviroment.util';
+import { BucketLookupOptions } from './types';
+
+/**
+ * 存储桶解析结果
+ *
+ * @interface BucketResolveResult
+ */
+export interface BucketResolveResult {
+  /** 解析后的存储桶名称 */
+  bucket: string;
+  /** 解析后的存储供应商 */
+  vendor: FileBucketVendor;
+  /** 存储桶配置（如果找到） */
+  config?: PardxUploader.Config;
+}
+
+/**
+ * 存储桶解析器
+ *
+ * @description 负责根据各种条件智能解析存储桶配置。
+ *
+ * 解析优先级：
+ * 1. 如果明确指定了 bucket，验证并使用
+ * 2. 根据 IP 地址推断区域（大洲）
+ * 3. 根据 isPublic 属性过滤
+ * 4. 选择默认存储桶
+ *
+ * @class BucketResolver
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   constructor(private readonly resolver: BucketResolver) {}
+ *
+ *   async getBucket(ip: string) {
+ *     const result = await this.resolver.resolve({
+ *       ip,
+ *       isPublic: false,
+ *     });
+ *     console.log('Resolved bucket:', result.bucket);
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class BucketResolver {
+  /**
+   * 存储桶配置列表
+   * @private
+   */
+  private readonly bucketConfigs: PardxUploader.Config[];
+
+  /**
+   * 应用配置
+   * @private
+   */
+  private readonly appConfig: AppConfig;
+
+  /**
+   * 默认存储供应商
+   * @private
+   */
+  private readonly defaultVendor: FileBucketVendor;
+
+  /**
+   * 构造函数
+   *
+   * @param {ConfigService} configService - NestJS 配置服务
+   * @param {IpInfoService} ipInfoService - IP 信息服务
+   * @param {Logger} logger - Winston 日志记录器
+   */
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly ipInfoService: IpInfoService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {
+    this.bucketConfigs =
+      configService.getOrThrow<PardxUploader.Config[]>('buckets');
+    this.appConfig = configService.getOrThrow<AppConfig>('app');
+    this.defaultVendor = this.appConfig.defaultVendor;
+  }
+
+  /**
+   * 解析存储桶
+   *
+   * @description 根据提供的选项智能解析出最合适的存储桶配置。
+   *
+   * @param {BucketLookupOptions} options - 查询选项
+   * @returns {Promise<BucketResolveResult>} 解析结果
+   *
+   * @example
+   * ```typescript
+   * // 根据 IP 解析
+   * const result = await resolver.resolve({ ip: '8.8.8.8' });
+   *
+   * // 指定公开存储桶
+   * const result = await resolver.resolve({ isPublic: true });
+   *
+   * // 明确指定存储桶
+   * const result = await resolver.resolve({
+   *   vendor: 'oss',
+   *   bucket: 'my-bucket',
+   * });
+   * ```
+   */
+  async resolve(
+    options: BucketLookupOptions = {},
+  ): Promise<BucketResolveResult> {
+    const { bucket, ip, isPublic, locale, vendor } = options;
+
+    // 确定供应商
+    const finalVendor = vendor ?? this.defaultVendor;
+
+    // 如果明确指定了 bucket，验证并返回
+    if (bucket) {
+      if (this.validateBucket(finalVendor, bucket)) {
+        const config = this.findBucketConfig(finalVendor, bucket);
+        return { bucket, vendor: finalVendor, config };
+      }
+      // bucket 无效，继续使用默认逻辑
+      this.logger.warn('Invalid bucket specified, falling back to default', {
+        bucket,
+        vendor: finalVendor,
+      });
+    }
+
+    // 解析默认存储桶
+    const defaultBucket = await this.resolveDefaultBucket(isPublic, ip, locale);
+    const resolvedVendor =
+      this.getVendorForBucket(defaultBucket) ?? finalVendor;
+    const config = this.findBucketConfig(resolvedVendor, defaultBucket);
+
+    return {
+      bucket: defaultBucket,
+      vendor: resolvedVendor,
+      config,
+    };
+  }
+
+  /**
+   * 解析默认存储桶
+   *
+   * @description 根据公开属性、IP 和区域设置选择默认存储桶。
+   *
+   * @param {boolean} [isPublic] - 是否公开存储桶
+   * @param {string} [ip] - 客户端 IP 地址
+   * @param {string} [locale] - 区域设置
+   * @returns {Promise<string>} 默认存储桶名称
+   */
+  async resolveDefaultBucket(
+    isPublic?: boolean,
+    ip?: string,
+    locale?: string,
+  ): Promise<string> {
+    // 确定区域
+    let zone = enviromentUtil.getBaseZone();
+    if (ip) {
+      const continent = await this.ipInfoService.getContinent(ip);
+      zone = continent ?? zone;
+    }
+    locale = locale ?? zone;
+
+    // 确定公开属性
+    const finalIsPublic = isPublic ?? this.appConfig.defaultBucketPublic;
+
+    // 过滤存储桶
+    let buckets = arrayUtil.filter(
+      this.bucketConfigs,
+      { isPublic: finalIsPublic },
+      this.appConfig.defaultBucketPublic,
+    );
+    buckets = arrayUtil.filter(buckets, { locale: locale }, zone);
+
+    // 查找默认存储桶
+    const bucketConfig = arrayUtil.findOne(buckets, { isDefault: true }, false);
+
+    if (bucketConfig?.bucket) {
+      return bucketConfig.bucket;
+    }
+
+    // 回退到区域配置的默认存储桶
+    const zoneConfig = this.appConfig.zones?.find((z) => z.zone === zone);
+    return finalIsPublic
+      ? (zoneConfig?.defaultPublicBucket ?? '')
+      : (zoneConfig?.defaultPrivateBucket ?? '');
+  }
+
+  /**
+   * 验证存储桶是否有效
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {boolean} 是否有效
+   */
+  validateBucket(vendor: FileBucketVendor, bucket: string): boolean {
+    return this.bucketConfigs.some(
+      (config) =>
+        config.bucket === bucket &&
+        (config.vendor ?? this.defaultVendor) === vendor,
+    );
+  }
+
+  /**
+   * 根据存储桶名称获取供应商
+   *
+   * @param {string} bucket - 存储桶名称
+   * @returns {FileBucketVendor | undefined} 供应商或 undefined
+   */
+  getVendorForBucket(bucket: string): FileBucketVendor | undefined {
+    const config = this.bucketConfigs.find((c) => c.bucket === bucket);
+    return config?.vendor ?? this.defaultVendor;
+  }
+
+  /**
+   * 查找存储桶配置
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {PardxUploader.Config | undefined} 配置或 undefined
+   */
+  findBucketConfig(
+    vendor: FileBucketVendor,
+    bucket: string,
+  ): PardxUploader.Config | undefined {
+    return this.bucketConfigs.find(
+      (config) =>
+        config.bucket === bucket &&
+        (config.vendor ?? this.defaultVendor) === vendor,
+    );
+  }
+
+  /**
+   * 获取所有存储桶配置
+   *
+   * @returns {PardxUploader.Config[]} 配置列表
+   */
+  getAllConfigs(): PardxUploader.Config[] {
+    return [...this.bucketConfigs];
+  }
+
+  /**
+   * 根据属性过滤存储桶
+   *
+   * @param {Partial<PardxUploader.Config>} filter - 过滤条件
+   * @returns {PardxUploader.Config[]} 匹配的配置列表
+   */
+  filterBuckets(filter: Partial<PardxUploader.Config>): PardxUploader.Config[] {
+    return this.bucketConfigs.filter((config) => {
+      for (const [key, value] of Object.entries(filter)) {
+        if (config[key] !== value) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+
+  /**
+   * 生成新的文件键
+   *
+   * @description 根据根路径和扩展名生成唯一的文件键。
+   *
+   * @param {string} root - 根路径
+   * @param {string} ext - 文件扩展名
+   * @param {string} [bucket] - 存储桶名称
+   * @returns {string} 生成的文件键
+   *
+   * @example
+   * ```typescript
+   * const key = resolver.generateFileKey('uploads', 'jpg', 'my-bucket');
+   * // 返回: "my-bucket/dev/uploads/1704067200000-abc123.jpg"
+   * ```
+   */
+  generateFileKey(root: string, ext: string, bucket?: string): string {
+    const prefix = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    const env = enviromentUtil.getEnv();
+
+    if (bucket) {
+      return `${bucket}/${env}/${root}/${prefix}.${ext}`;
+    }
+    return `${env}/${root}/${prefix}.${ext}`;
+  }
+}

package/template/apps/api/libs/infra/shared-services/file-storage/file-storage.factory.ts

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview 文件存储客户端工厂
+ *
+ * 本文件实现了文件存储客户端的工厂模式，负责：
+ * - 根据存储供应商类型创建对应的客户端实例
+ * - 管理客户端实例的生命周期（单例模式）
+ * - 提供统一的客户端获取接口
+ *
+ * @module file-storage/factory
+ */
+
+import { Injectable, Inject } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { HttpService } from '@nestjs/axios';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { FileBucketVendor } from '@prisma/client';
+
+import {
+  FileStorageInterface,
+  FileS3Client,
+  FileQiniuClient,
+  FileGcsClient,
+  FileUs3Client,
+  FileTosClient,
+  PardxUploader,
+} from '@app/clients/internal/file-storage';
+import { RedisService } from '@app/redis';
+import { getKeysConfig } from '@/config/configuration';
+import { AppConfig, StorageCredentialsConfig } from '@/config/validation';
+import { CommonErrorCode } from '@repo/contracts/errors';
+import { apiError } from '@/filter/exception/api.exception';
+import {
+  StorageClientKey,
+  buildStorageClientKey,
+  StorageCredentialsMap,
+} from './types';
+import enviromentUtil from '@/utils/enviroment.util';
+
+/**
+ * 存储客户端类类型
+ */
+type StorageClientClass = new (
+  config: PardxUploader.Config,
+  storageConfig: StorageCredentialsConfig,
+  appConfig: AppConfig,
+  redis: RedisService,
+  httpService: HttpService,
+  logger: Logger,
+) => FileStorageInterface;
+
+/**
+ * 存储供应商到客户端类的映射
+ *
+ * @description 目前支持的存储供应商客户端实现。
+ * `tencent` 和 `ksyun` 在枚举中定义但尚未实现客户端。
+ */
+const VENDOR_CLIENT_MAP: Partial<Record<FileBucketVendor, StorageClientClass>> =
+  {
+    s3: FileS3Client,
+    oss: FileS3Client,
+    tos: FileTosClient,
+    us3: FileUs3Client,
+    gcs: FileGcsClient,
+    qiniu: FileQiniuClient,
+    // tencent: 尚未实现
+    // ksyun: 尚未实现
+  };
+
+/**
+ * 文件存储客户端工厂
+ *
+ * @description 使用工厂模式管理不同存储供应商的客户端实例。
+ *
+ * 主要职责：
+ * - 根据 vendor 和 bucket 创建对应的客户端实例
+ * - 使用单例模式缓存客户端实例，避免重复创建
+ * - 统一管理存储配置和凭证
+ *
+ * 支持的存储供应商：
+ * - 's3': AWS S3 兼容存储
+ * - 'oss': 阿里云 OSS
+ * - 'tos': 火山引擎 TOS
+ * - 'us3': UCloud US3
+ * - 'gcs': Google Cloud Storage
+ * - 'qiniu': 七牛云存储
+ *
+ * @class FileStorageClientFactory
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   constructor(private readonly factory: FileStorageClientFactory) {}
+ *
+ *   async uploadFile(vendor: FileBucketVendor, bucket: string, file: Buffer) {
+ *     const client = this.factory.getClient(vendor, bucket);
+ *     await client.fileUploader(file, { key: 'path/to/file', bucket });
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class FileStorageClientFactory {
+  /**
+   * 客户端实例缓存
+   * @private
+   */
+  private readonly clients: Map<StorageClientKey, FileStorageInterface> =
+    new Map();
+
+  /**
+   * 存储桶配置列表
+   * @private
+   */
+  private readonly bucketConfigs: PardxUploader.Config[];
+
+  /**
+   * 存储凭证配置
+   * @private
+   */
+  private readonly storageCredentials: StorageCredentialsMap;
+
+  /**
+   * 应用配置
+   * @private
+   */
+  private readonly appConfig: AppConfig;
+
+  /**
+   * 默认存储供应商
+   * @private
+   */
+  private readonly defaultVendor: FileBucketVendor;
+
+  /**
+   * 构造函数
+   *
+   * @param {ConfigService} configService - NestJS 配置服务
+   * @param {RedisService} redis - Redis 服务
+   * @param {HttpService} httpService - HTTP 服务
+   * @param {Logger} logger - Winston 日志记录器
+   */
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly redis: RedisService,
+    private readonly httpService: HttpService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {
+    // 加载配置
+    this.bucketConfigs =
+      configService.getOrThrow<PardxUploader.Config[]>('buckets');
+    this.appConfig = configService.getOrThrow<AppConfig>('app');
+    this.defaultVendor = this.appConfig.defaultVendor;
+    this.storageCredentials =
+      (getKeysConfig()?.storage as StorageCredentialsMap) || {};
+
+    // 预初始化所有配置的客户端
+    this.initializeClients();
+  }
+
+  /**
+   * 预初始化所有配置的存储客户端
+   *
+   * @private
+   */
+  private initializeClients(): void {
+    for (const config of this.bucketConfigs) {
+      const vendor = config.vendor ?? this.defaultVendor;
+      try {
+        this.createClient(vendor, config);
+      } catch (error) {
+        this.logger.error('Failed to initialize storage client', {
+          vendor,
+          bucket: config.bucket,
+          error: (error as Error).message,
+        });
+      }
+    }
+
+    if (enviromentUtil.isProduction()) {
+      this.logger.info('FileStorageClientFactory module initialized', {
+        clientCount: this.clients.size,
+        vendors: [...new Set(this.bucketConfigs.map((c) => c.vendor))],
+      });
+    }
+  }
+
+  /**
+   * 创建存储客户端实例
+   *
+   * @private
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {PardxUploader.Config} config - 存储桶配置
+   * @returns {FileStorageInterface} 客户端实例
+   * @throws {Error} 不支持的供应商类型时抛出异常
+   */
+  private createClient(
+    vendor: FileBucketVendor,
+    config: PardxUploader.Config,
+  ): FileStorageInterface {
+    const ClientClass = VENDOR_CLIENT_MAP[vendor];
+
+    if (!ClientClass) {
+      throw apiError(CommonErrorCode.FileServiceUnsupportedVendor);
+    }
+
+    const storageConfig = this.storageCredentials[vendor];
+    const client = new ClientClass(
+      config,
+      storageConfig,
+      this.appConfig,
+      this.redis,
+      this.httpService,
+      this.logger,
+    );
+
+    // 缓存客户端
+    const key = buildStorageClientKey(vendor, config.bucket);
+    this.clients.set(key, client);
+
+    return client;
+  }
+
+  /**
+   * 获取存储客户端
+   *
+   * @description 根据供应商和存储桶获取对应的客户端实例。
+   * 如果客户端不存在，将返回 undefined。
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {FileStorageInterface | undefined} 客户端实例或 undefined
+   *
+   * @example
+   * ```typescript
+   * const client = factory.getClient('oss', 'my-bucket');
+   * if (client) {
+   *   await client.uploadFile('/path/to/file', 'key', 'my-bucket');
+   * }
+   * ```
+   */
+  getClient(
+    vendor: FileBucketVendor,
+    bucket: string,
+  ): FileStorageInterface | undefined {
+    const key = buildStorageClientKey(vendor, bucket);
+    return this.clients.get(key);
+  }
+
+  /**
+   * 获取存储客户端（必须存在）
+   *
+   * @description 获取客户端实例，如果不存在则抛出异常。
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {FileStorageInterface} 客户端实例
+   * @throws {Error} 客户端不存在时抛出异常
+   *
+   * @example
+   * ```typescript
+   * const client = factory.getClientOrThrow('oss', 'my-bucket');
+   * await client.uploadFile('/path/to/file', 'key', 'my-bucket');
+   * ```
+   */
+  getClientOrThrow(
+    vendor: FileBucketVendor,
+    bucket: string,
+  ): FileStorageInterface {
+    const client = this.getClient(vendor, bucket);
+
+    if (!client) {
+      throw new Error(
+        `File storage client not found for vendor: ${vendor}, bucket: ${bucket}`,
+      );
+    }
+
+    return client;
+  }
+
+  /**
+   * 检查客户端是否存在
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {boolean} 是否存在
+   */
+  hasClient(vendor: FileBucketVendor, bucket: string): boolean {
+    const key = buildStorageClientKey(vendor, bucket);
+    return this.clients.has(key);
+  }
+
+  /**
+   * 获取存储桶配置
+   *
+   * @param {FileBucketVendor} vendor - 存储供应商
+   * @param {string} bucket - 存储桶名称
+   * @returns {PardxUploader.Config | undefined} 存储桶配置
+   */
+  getBucketConfig(
+    vendor: FileBucketVendor,
+    bucket: string,
+  ): PardxUploader.Config | undefined {
+    return this.bucketConfigs.find(
+      (config) =>
+        config.bucket === bucket &&
+        (config.vendor ?? this.defaultVendor) === vendor,
+    );
+  }
+
+  /**
+   * 获取所有存储桶配置
+   *
+   * @returns {PardxUploader.Config[]} 存储桶配置列表
+   */
+  getAllBucketConfigs(): PardxUploader.Config[] {
+    return [...this.bucketConfigs];
+  }
+
+  /**
+   * 获取默认存储供应商
+   *
+   * @returns {FileBucketVendor} 默认供应商
+   */
+  getDefaultVendor(): FileBucketVendor {
+    return this.defaultVendor;
+  }
+
+  /**
+   * 获取应用配置
+   *
+   * @returns {AppConfig} 应用配置
+   */
+  getAppConfig(): AppConfig {
+    return this.appConfig;
+  }
+
+  /**
+   * 获取所有已初始化的客户端键
+   *
+   * @returns {StorageClientKey[]} 客户端键列表
+   */
+  getClientKeys(): StorageClientKey[] {
+    return [...this.clients.keys()];
+  }
+}

package/template/apps/api/libs/infra/shared-services/file-storage/file-storage.module.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview 文件存储服务模块
+ *
+ * 本模块提供文件存储服务的 NestJS 模块配置，整合了：
+ * - FileStorageService: 文件存储服务门面
+ * - FileStorageClientFactory: 客户端工厂
+ * - BucketResolver: 存储桶解析器
+ *
+ * @module file-storage/module
+ */
+
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { HttpModule } from '@nestjs/axios';
+import { IpInfoServiceModule } from '@app/shared-services/ip-info';
+import { RedisModule } from '@app/redis';
+import { FileStorageService } from './file-storage.service';
+import { FileStorageClientFactory } from './file-storage.factory';
+import { BucketResolver } from './bucket-resolver';
+
+/**
+ * 文件存储服务模块
+ *
+ * @description 提供文件存储服务的依赖注入配置。
+ *
+ * 导出服务：
+ * - `FileStorageService`: 文件存储服务统一入口
+ * - `FileStorageClientFactory`: 客户端工厂（可选，用于高级场景）
+ * - `BucketResolver`: 存储桶解析器（可选，用于高级场景）
+ *
+ * 依赖模块：
+ * - `ConfigModule`: 配置服务
+ * - `HttpModule`: HTTP 客户端
+ * - `RedisModule`: Redis 缓存
+ * - `IpInfoServiceModule`: IP 信息服务（用于区域感知）
+ *
+ * @example
+ * ```typescript
+ * // 在其他模块中导入
+ * @Module({
+ *   imports: [FileStorageServiceModule],
+ * })
+ * export class VideoModule {}
+ *
+ * // 在服务中使用
+ * @Injectable()
+ * class VideoService {
+ *   constructor(private readonly fileStorage: FileStorageService) {}
+ *
+ *   async upload(file: Buffer, key: string) {
+ *     const client = await this.fileStorage.getFileClient('oss', 'my-bucket');
+ *     await client.fileUploader(file, { key, bucket: 'my-bucket' });
+ *   }
+ * }
+ * ```
+ */
+@Module({
+  imports: [ConfigModule, RedisModule, IpInfoServiceModule, HttpModule],
+  providers: [BucketResolver, FileStorageClientFactory, FileStorageService],
+  exports: [FileStorageService, FileStorageClientFactory, BucketResolver],
+})
+export class FileStorageServiceModule {}