@dofe/infra-shared-services 0.1.1

package/dist/file-storage/bucket-resolver.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview 存储桶解析器
+ *
+ * 本文件实现了存储桶的智能解析功能，负责：
+ * - 根据 IP 地址进行区域感知的存储桶选择
+ * - 根据公开/私有属性选择合适的存储桶
+ * - 验证存储桶配置的有效性
+ *
+ * @module file-storage/bucket-resolver
+ */
+import { ConfigService } from '@nestjs/config';
+import { Logger } from 'winston';
+import { FileBucketVendor } from '@prisma/client';
+import { PardxUploader } from '@dofe/infra-clients';
+import { IpGeoService } from '@dofe/infra-shared-services';
+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);
+ *   }
+ * }
+ * ```
+ */
+export declare class BucketResolver {
+    private readonly ipGeoService;
+    private readonly logger;
+    /**
+     * 存储桶配置列表
+     * @private
+     */
+    private readonly bucketConfigs;
+    /**
+     * 应用配置
+     * @private
+     */
+    private readonly appConfig;
+    /**
+     * 默认存储供应商
+     * @private
+     */
+    private readonly defaultVendor;
+    /**
+     * 构造函数
+     *
+     * @param {ConfigService} configService - NestJS 配置服务
+     * @param {IpGeoService} ipGeoService - IP 地理位置服务（infra 层）
+     * @param {Logger} logger - Winston 日志记录器
+     */
+    constructor(configService: ConfigService, ipGeoService: IpGeoService, logger: Logger);
+    /**
+     * 解析存储桶
+     *
+     * @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',
+     * });
+     * ```
+     */
+    resolve(options?: BucketLookupOptions): Promise<BucketResolveResult>;
+    /**
+     * 解析默认存储桶
+     *
+     * @description 根据公开属性、IP 和区域设置选择默认存储桶。
+     *
+     * @param {boolean} [isPublic] - 是否公开存储桶
+     * @param {string} [ip] - 客户端 IP 地址
+     * @param {string} [locale] - 区域设置
+     * @returns {Promise<string>} 默认存储桶名称
+     */
+    resolveDefaultBucket(isPublic?: boolean, ip?: string, locale?: string): Promise<string>;
+    /**
+     * 验证存储桶是否有效
+     *
+     * @param {FileBucketVendor} vendor - 存储供应商
+     * @param {string} bucket - 存储桶名称
+     * @returns {boolean} 是否有效
+     */
+    validateBucket(vendor: FileBucketVendor, bucket: string): boolean;
+    /**
+     * 根据存储桶名称获取供应商
+     *
+     * @param {string} bucket - 存储桶名称
+     * @returns {FileBucketVendor | undefined} 供应商或 undefined
+     */
+    getVendorForBucket(bucket: string): FileBucketVendor | undefined;
+    /**
+     * 查找存储桶配置
+     *
+     * @param {FileBucketVendor} vendor - 存储供应商
+     * @param {string} bucket - 存储桶名称
+     * @returns {PardxUploader.Config | undefined} 配置或 undefined
+     */
+    findBucketConfig(vendor: FileBucketVendor, bucket: string): PardxUploader.Config | undefined;
+    /**
+     * 获取所有存储桶配置
+     *
+     * @returns {PardxUploader.Config[]} 配置列表
+     */
+    getAllConfigs(): PardxUploader.Config[];
+    /**
+     * 根据属性过滤存储桶
+     *
+     * @param {Partial<PardxUploader.Config>} filter - 过滤条件
+     * @returns {PardxUploader.Config[]} 匹配的配置列表
+     */
+    filterBuckets(filter: Partial<PardxUploader.Config>): PardxUploader.Config[];
+    /**
+     * 生成新的文件键
+     *
+     * @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;
+}
+//# sourceMappingURL=bucket-resolver.d.ts.map

package/dist/file-storage/bucket-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-resolver.d.ts","sourceRoot":"","sources":["../../src/file-storage/bucket-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAI3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,MAAM,EAAE,gBAAgB,CAAC;IACzB,kBAAkB;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBACa,cAAc;IA4BvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IACI,OAAO,CAAC,QAAQ,CAAC,MAAM;IA5B1D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IAEvD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD;;;;;;OAMG;gBAED,aAAa,EAAE,aAAa,EACX,YAAY,EAAE,YAAY,EACO,MAAM,EAAE,MAAM;IAQlE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CACX,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC;IAgC/B;;;;;;;;;OASG;IACG,oBAAoB,CACxB,QAAQ,CAAC,EAAE,OAAO,EAClB,EAAE,CAAC,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;IAkClB;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAQjE;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAKhE;;;;;;OAMG;IACH,gBAAgB,CACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,GACb,aAAa,CAAC,MAAM,GAAG,SAAS;IAQnC;;;;OAIG;IACH,aAAa,IAAI,aAAa,CAAC,MAAM,EAAE;IAIvC;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE;IAW5E;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;CASpE"}

package/dist/file-storage/bucket-resolver.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * @fileoverview 存储桶解析器
+ *
+ * 本文件实现了存储桶的智能解析功能，负责：
+ * - 根据 IP 地址进行区域感知的存储桶选择
+ * - 根据公开/私有属性选择合适的存储桶
+ * - 验证存储桶配置的有效性
+ *
+ * @module file-storage/bucket-resolver
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BucketResolver = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const nest_winston_1 = require("nest-winston");
+const winston_1 = require("winston");
+const infra_shared_services_1 = require("@dofe/infra-shared-services");
+const array_util_1 = __importDefault(require("@dofe/infra-utils/array.util"));
+const environment_util_1 = __importDefault(require("@dofe/infra-utils/environment.util"));
+/**
+ * 存储桶解析器
+ *
+ * @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);
+ *   }
+ * }
+ * ```
+ */
+let BucketResolver = class BucketResolver {
+    ipGeoService;
+    logger;
+    /**
+     * 存储桶配置列表
+     * @private
+     */
+    bucketConfigs;
+    /**
+     * 应用配置
+     * @private
+     */
+    appConfig;
+    /**
+     * 默认存储供应商
+     * @private
+     */
+    defaultVendor;
+    /**
+     * 构造函数
+     *
+     * @param {ConfigService} configService - NestJS 配置服务
+     * @param {IpGeoService} ipGeoService - IP 地理位置服务（infra 层）
+     * @param {Logger} logger - Winston 日志记录器
+     */
+    constructor(configService, ipGeoService, logger) {
+        this.ipGeoService = ipGeoService;
+        this.logger = logger;
+        this.bucketConfigs =
+            configService.getOrThrow('buckets');
+        this.appConfig = configService.getOrThrow('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 = {}) {
+        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, ip, locale) {
+        // 确定区域
+        let zone = environment_util_1.default.getBaseZone();
+        if (ip) {
+            const continent = await this.ipGeoService.getContinent(ip);
+            zone = continent ?? zone;
+        }
+        locale = locale ?? zone;
+        // 确定公开属性
+        const finalIsPublic = isPublic ?? this.appConfig.defaultBucketPublic;
+        // 过滤存储桶
+        let buckets = array_util_1.default.filter(this.bucketConfigs, { isPublic: finalIsPublic }, this.appConfig.defaultBucketPublic);
+        buckets = array_util_1.default.filter(buckets, { locale: locale }, zone);
+        // 查找默认存储桶
+        const bucketConfig = array_util_1.default.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, bucket) {
+        return this.bucketConfigs.some((config) => config.bucket === bucket &&
+            (config.vendor ?? this.defaultVendor) === vendor);
+    }
+    /**
+     * 根据存储桶名称获取供应商
+     *
+     * @param {string} bucket - 存储桶名称
+     * @returns {FileBucketVendor | undefined} 供应商或 undefined
+     */
+    getVendorForBucket(bucket) {
+        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, bucket) {
+        return this.bucketConfigs.find((config) => config.bucket === bucket &&
+            (config.vendor ?? this.defaultVendor) === vendor);
+    }
+    /**
+     * 获取所有存储桶配置
+     *
+     * @returns {PardxUploader.Config[]} 配置列表
+     */
+    getAllConfigs() {
+        return [...this.bucketConfigs];
+    }
+    /**
+     * 根据属性过滤存储桶
+     *
+     * @param {Partial<PardxUploader.Config>} filter - 过滤条件
+     * @returns {PardxUploader.Config[]} 匹配的配置列表
+     */
+    filterBuckets(filter) {
+        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, ext, bucket) {
+        const prefix = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+        const env = environment_util_1.default.getEnv();
+        if (bucket) {
+            return `${bucket}/${env}/${root}/${prefix}.${ext}`;
+        }
+        return `${env}/${root}/${prefix}.${ext}`;
+    }
+};
+exports.BucketResolver = BucketResolver;
+exports.BucketResolver = BucketResolver = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Inject)(nest_winston_1.WINSTON_MODULE_PROVIDER)),
+    __metadata("design:paramtypes", [config_1.ConfigService,
+        infra_shared_services_1.IpGeoService,
+        winston_1.Logger])
+], BucketResolver);
+//# sourceMappingURL=bucket-resolver.js.map

package/dist/file-storage/bucket-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-resolver.js","sourceRoot":"","sources":["../../src/file-storage/bucket-resolver.ts"],"names":[],"mappings":"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"}

package/dist/file-storage/file-storage.factory.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview 文件存储客户端工厂
+ *
+ * 本文件实现了文件存储客户端的工厂模式，负责：
+ * - 根据存储供应商类型创建对应的客户端实例
+ * - 管理客户端实例的生命周期（单例模式）
+ * - 提供统一的客户端获取接口
+ *
+ * @module file-storage/factory
+ */
+import { ConfigService } from '@nestjs/config';
+import { HttpService } from '@nestjs/axios';
+import { Logger } from 'winston';
+import { FileBucketVendor } from '@prisma/client';
+import { FileStorageInterface, PardxUploader } from '@dofe/infra-clients';
+import { RedisService } from '@dofe/infra-redis';
+import { AppConfig } from '@dofe/infra-common';
+import { StorageClientKey } from './types';
+/**
+ * 文件存储客户端工厂
+ *
+ * @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 });
+ *   }
+ * }
+ * ```
+ */
+export declare class FileStorageClientFactory {
+    private readonly redis;
+    private readonly httpService;
+    private readonly logger;
+    /**
+     * 客户端实例缓存
+     * @private
+     */
+    private readonly clients;
+    /**
+     * 存储桶配置列表
+     * @private
+     */
+    private readonly bucketConfigs;
+    /**
+     * 存储凭证配置
+     * @private
+     */
+    private readonly storageCredentials;
+    /**
+     * 应用配置
+     * @private
+     */
+    private readonly appConfig;
+    /**
+     * 默认存储供应商
+     * @private
+     */
+    private readonly defaultVendor;
+    /**
+     * 构造函数
+     *
+     * @param {ConfigService} configService - NestJS 配置服务
+     * @param {RedisService} redis - Redis 服务
+     * @param {HttpService} httpService - HTTP 服务
+     * @param {Logger} logger - Winston 日志记录器
+     */
+    constructor(configService: ConfigService, redis: RedisService, httpService: HttpService, logger: Logger);
+    /**
+     * 预初始化所有配置的存储客户端
+     *
+     * @private
+     */
+    private initializeClients;
+    /**
+     * 创建存储客户端实例
+     *
+     * @private
+     * @param {FileBucketVendor} vendor - 存储供应商
+     * @param {PardxUploader.Config} config - 存储桶配置
+     * @returns {FileStorageInterface} 客户端实例
+     * @throws {Error} 不支持的供应商类型时抛出异常
+     */
+    private createClient;
+    /**
+     * 获取存储客户端
+     *
+     * @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;
+    /**
+     * 获取存储客户端（必须存在）
+     *
+     * @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;
+    /**
+     * 检查客户端是否存在
+     *
+     * @param {FileBucketVendor} vendor - 存储供应商
+     * @param {string} bucket - 存储桶名称
+     * @returns {boolean} 是否存在
+     */
+    hasClient(vendor: FileBucketVendor, bucket: string): boolean;
+    /**
+     * 获取存储桶配置
+     *
+     * @param {FileBucketVendor} vendor - 存储供应商
+     * @param {string} bucket - 存储桶名称
+     * @returns {PardxUploader.Config | undefined} 存储桶配置
+     */
+    getBucketConfig(vendor: FileBucketVendor, bucket: string): PardxUploader.Config | undefined;
+    /**
+     * 获取所有存储桶配置
+     *
+     * @returns {PardxUploader.Config[]} 存储桶配置列表
+     */
+    getAllBucketConfigs(): PardxUploader.Config[];
+    /**
+     * 获取默认存储供应商
+     *
+     * @returns {FileBucketVendor} 默认供应商
+     */
+    getDefaultVendor(): FileBucketVendor;
+    /**
+     * 获取应用配置
+     *
+     * @returns {AppConfig} 应用配置
+     */
+    getAppConfig(): AppConfig;
+    /**
+     * 获取所有已初始化的客户端键
+     *
+     * @returns {StorageClientKey[]} 客户端键列表
+     */
+    getClientKeys(): StorageClientKey[];
+}
+//# sourceMappingURL=file-storage.factory.d.ts.map

package/dist/file-storage/file-storage.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage.factory.d.ts","sourceRoot":"","sources":["../../src/file-storage/file-storage.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EACL,oBAAoB,EAMpB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,SAAS,EAA4B,MAAM,oBAAoB,CAAC;AAGzE,OAAO,EACL,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAiCjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,wBAAwB;IA0CjC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IACK,OAAO,CAAC,QAAQ,CAAC,MAAM;IA3C1D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CACZ;IAEZ;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IAEvD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwB;IAE3D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD;;;;;;;OAOG;gBAED,aAAa,EAAE,aAAa,EACX,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,WAAW,EACS,MAAM,EAAE,MAAM;IAclE;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA8BpB;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CACP,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,GACb,oBAAoB,GAAG,SAAS;IAKnC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,GACb,oBAAoB;IAYvB;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAK5D;;;;;;OAMG;IACH,eAAe,CACb,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,GACb,aAAa,CAAC,MAAM,GAAG,SAAS;IAQnC;;;;OAIG;IACH,mBAAmB,IAAI,aAAa,CAAC,MAAM,EAAE;IAI7C;;;;OAIG;IACH,gBAAgB,IAAI,gBAAgB;IAIpC;;;;OAIG;IACH,YAAY,IAAI,SAAS;IAIzB;;;;OAIG;IACH,aAAa,IAAI,gBAAgB,EAAE;CAGpC"}