@dd-code/oss-uploader 0.1.0

package/src/config/types.ts

@@ -0,0 +1,47 @@
+/**
+ * 配置与类型定义：华为 OBS、Provider、环境解析器等。
+ */
+
+/** 华为 OBS 连接与鉴权配置，含 basePrefix（所有 key 的基础前缀，仅在 config 中配置） */
+export interface HuaweiObsConfig {
+  endpoint: string;
+  accessKey: string;
+  secretKey: string;
+  region?: string;
+  basePrefix: string;
+  /** CDN 加速根地址，配置后上传完成可拼出完整访问 URL（如 https://cdn.example.com） */
+  cdnBaseUrl?: string;
+}
+
+/** 当前支持的存储 Provider 类型 */
+export type ProviderType = 'huawei';
+
+/** 创建 StorageClient 时传入的配置，按 type 选择具体实现 */
+export interface ProviderConfig {
+  type: ProviderType;
+  options: HuaweiObsConfig;
+}
+
+/** 根据环境标识解析华为 OBS 配置的接口，便于替换为配置文件等实现 */
+export interface EnvConfigResolver {
+  resolveHuaweiConfig(env?: string): HuaweiObsConfig;
+}
+
+/**
+ * 解析后的 Provider 配置（含上传流程所需的 basePrefix、cdnBaseUrl）。
+ * 由 ProviderConfigResolver 统一返回，OssService 只依赖此结构，不关心具体云厂商。
+ */
+export interface ResolvedProviderConfig {
+  providerConfig: ProviderConfig;
+  basePrefix: string;
+  cdnBaseUrl?: string;
+}
+
+/**
+ * 统一 Provider 配置解析器：返回当前要用的 Provider 及其配置。
+ * 切换云厂商时只需改此接口的【一个实现文件】即可（如改 env 或增加 case）。
+ */
+export interface ProviderConfigResolver {
+  resolve(): ResolvedProviderConfig;
+}
+

package/src/core/DirectoryUploadFlow.ts

@@ -0,0 +1,96 @@
+import fs from 'fs/promises';
+import { UploadFlowTemplate, UploadContext, LocalFile } from './UploadFlowTemplate';
+import { UploadSummary } from './reporter';
+import { buildCdnAccessUrl } from './urlHelper';
+
+/**
+ * 目录上传流程的具体实现：遍历本地目录，按 key 规则上传，云端同名则跳过。
+ * 规则：先 headObject，exists 则 skipped，否则 putObject。
+ */
+export class DirectoryUploadFlow extends UploadFlowTemplate {
+  constructor(context: UploadContext) {
+    super(context);
+  }
+
+  /** 递归收集 localDir 下所有文件 */
+  protected async collectFiles(): Promise<LocalFile[]> {
+    return this.walkDir(this.context.localDir);
+  }
+
+  /**
+   * 逐个文件上传：先 head 判断是否存在，存在则跳过，否则读取本地文件并 putObject。
+   * 每个文件的结果通过 reportFileResult 交给 Reporter。
+   */
+  protected async uploadFiles(files: LocalFile[]): Promise<UploadSummary> {
+    const { bucket, storageClient, cdnBaseUrl } = this.context;
+
+    const summary: UploadSummary = {
+      total: files.length,
+      success: 0,
+      failed: 0,
+      skipped: 0,
+    };
+
+    for (const file of files) {
+      const key = this.buildKey(file.relativePath);
+
+      try {
+        const head = await storageClient.headObject(bucket, key);
+
+        // 云端已有同名对象则跳过，不比较内容
+        if (head.exists) {
+          summary.skipped += 1;
+          await this.reportFileResult({
+            localPath: file.absolutePath,
+            relativePath: file.relativePath,
+            bucket,
+            key,
+            status: 'skipped',
+            ...(cdnBaseUrl && { accessUrl: buildCdnAccessUrl(cdnBaseUrl, key) }),
+          });
+          continue;
+        }
+
+        const data = await fs.readFile(file.absolutePath);
+
+        const { buffer, contentType } = this.context.fileProcessor
+          ? await this.context.fileProcessor.process({
+              localPath: file.absolutePath,
+              relativePath: file.relativePath,
+              buffer: data,
+            })
+          : { buffer: data, contentType: undefined as string | undefined };
+
+        await storageClient.putObject({
+          bucket,
+          key,
+          body: buffer,
+          contentType,
+        });
+
+        summary.success += 1;
+        await this.reportFileResult({
+          localPath: file.absolutePath,
+          relativePath: file.relativePath,
+          bucket,
+          key,
+          status: 'success',
+          ...(cdnBaseUrl && { accessUrl: buildCdnAccessUrl(cdnBaseUrl, key) }),
+        });
+      } catch (err: any) {
+        summary.failed += 1;
+        await this.reportFileResult({
+          localPath: file.absolutePath,
+          relativePath: file.relativePath,
+          bucket,
+          key,
+          status: 'failed',
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
+      }
+    }
+
+    return summary;
+  }
+}
+

package/src/core/StorageClient.ts

@@ -0,0 +1,25 @@
+/**
+ * 存储客户端统一接口（中间件层与各云厂商 Adapter 的契约）。
+ * 实现类负责将 putObject/headObject 翻译为具体云厂商的 API 调用。
+ */
+
+/** 上传单个对象时的参数 */
+export interface PutObjectOptions {
+  bucket: string;
+  key: string;
+  body: Buffer | NodeJS.ReadableStream;
+  contentType?: string;
+  headers?: Record<string, string>;
+}
+
+/** headObject 的返回结果，仅用于判断云端是否已有同名对象（决定是否跳过上传） */
+export interface HeadObjectResult {
+  exists: boolean;
+}
+
+/** 统一存储客户端接口，各 Provider（华为 OBS、阿里 OSS、S3 等）需实现此接口 */
+export interface StorageClient {
+  putObject(options: PutObjectOptions): Promise<void>;
+  headObject(bucket: string, key: string): Promise<HeadObjectResult>;
+}
+

package/src/core/StorageFactory.ts

@@ -0,0 +1,17 @@
+import { StorageClient } from './StorageClient';
+import { ProviderConfig } from '../config/types';
+import { HuaweiObsClient } from '../providers/huawei/HuaweiObsClient';
+
+/**
+ * 根据 Provider 类型创建对应的 StorageClient（简单工厂）。
+ * 后续扩展阿里 OSS、AWS S3 时在此增加 case 即可。
+ */
+export function createStorageClient(config: ProviderConfig): StorageClient {
+  switch (config.type) {
+    case 'huawei':
+      return new HuaweiObsClient(config.options);
+    default:
+      throw new Error(`Unsupported provider type: ${config.type}`);
+  }
+}
+

package/src/core/UploadFlowTemplate.ts

@@ -0,0 +1,119 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { Reporter, UploadSummary, UploadFileResult } from './reporter';
+import { StorageClient } from './StorageClient';
+import { shouldInclude } from './filters';
+import type { FileProcessor } from './fileProcessor';
+
+/** 上传流程的上下文：环境、bucket、前缀、本地目录、存储客户端、Reporter、CDN 根地址、上传前处理器等 */
+export interface UploadContext {
+  env?: string;
+  bucket: string;
+  basePrefix: string;
+  pathPrefix?: string;
+  localDir: string;
+  include?: string[];
+  exclude?: string[];
+  storageClient: StorageClient;
+  reporter?: Reporter;
+  /** CDN 加速根地址，配置后可为每个文件生成 accessUrl */
+  cdnBaseUrl?: string;
+  /** 上传前对文件内容的处理器（如图片压缩），未配置则直接上传原内容 */
+  fileProcessor?: FileProcessor;
+}
+
+/** 本地文件信息：绝对路径与相对路径 */
+export interface LocalFile {
+  absolutePath: string;
+  relativePath: string;
+}
+
+/**
+ * 上传流程模板（Template Method）。
+ * 定义固定步骤：onStart -> collectFiles -> filterFiles -> uploadFiles -> onComplete，
+ * 子类实现 collectFiles 与 uploadFiles，其余步骤可复用或重写。
+ */
+export abstract class UploadFlowTemplate {
+  protected constructor(protected readonly context: UploadContext) {}
+
+  /** 执行完整上传流程 */
+  async execute(): Promise<UploadSummary> {
+    const { reporter } = this.context;
+
+    if (reporter?.onStart) {
+      await reporter.onStart({
+        env: this.context.env,
+        bucket: this.context.bucket,
+        basePrefix: this.context.basePrefix,
+        pathPrefix: this.context.pathPrefix,
+        localDir: this.context.localDir,
+        cdnBaseUrl: this.context.cdnBaseUrl,
+      });
+    }
+
+    const files = await this.collectFiles();
+    const filtered = this.filterFiles(files);
+    const summary = await this.uploadFiles(filtered);
+
+    if (reporter?.onComplete) {
+      await reporter.onComplete(summary);
+    }
+
+    return summary;
+  }
+
+  protected abstract collectFiles(): Promise<LocalFile[]>;
+  protected abstract uploadFiles(files: LocalFile[]): Promise<UploadSummary>;
+
+  /** 使用 include/exclude 过滤文件列表 */
+  protected filterFiles(files: LocalFile[]): LocalFile[] {
+    const { include, exclude } = this.context;
+    return files.filter((f) => shouldInclude(f.relativePath, include, exclude));
+  }
+
+  /**
+   * 构造远端 key：basePrefix / env / pathPrefix / relativePath。
+   * 保持目录结构，且 base 前缀来自 config，不对外暴露。
+   */
+  protected buildKey(relativePath: string): string {
+    const parts: string[] = [];
+    if (this.context.basePrefix) parts.push(this.context.basePrefix);
+    if (this.context.env) parts.push(this.context.env);
+    if (this.context.pathPrefix) parts.push(this.context.pathPrefix);
+
+    parts.push(relativePath.replace(/\\/g, '/'));
+    return parts.join('/');
+  }
+
+  /** 递归遍历目录，收集所有文件的绝对路径与相对路径 */
+  protected async walkDir(rootDir: string, currentDir = ''): Promise<LocalFile[]> {
+    const dirPath = path.join(rootDir, currentDir);
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files: LocalFile[] = [];
+
+    for (const entry of entries) {
+      const rel = path.join(currentDir, entry.name);
+      const abs = path.join(rootDir, rel);
+
+      if (entry.isDirectory()) {
+        files.push(...(await this.walkDir(rootDir, rel)));
+      } else if (entry.isFile()) {
+        files.push({
+          absolutePath: abs,
+          relativePath: rel.replace(/\\/g, '/'),
+        });
+      }
+    }
+
+    return files;
+  }
+
+  /** 将单个文件的上传结果交给 Reporter */
+  protected async reportFileResult(result: UploadFileResult): Promise<void> {
+    const { reporter } = this.context;
+    if (reporter?.onFileResult) {
+      await reporter.onFileResult(result);
+    }
+  }
+}
+

package/src/core/fileProcessor.ts

@@ -0,0 +1,40 @@
+/**
+ * 上传前文件处理抽象。
+ * 可在 putObject 前对内容做转换，例如图片压缩、水印、格式转换等，便于后期扩展。
+ */
+
+/** 传入处理器的文件信息与内容 */
+export interface ProcessFileInput {
+  /** 本地绝对路径 */
+  localPath: string;
+  /** 相对 localDir 的路径 */
+  relativePath: string;
+  /** 文件内容，处理器可修改后返回 */
+  buffer: Buffer;
+}
+
+/** 处理器返回结果，将用于 putObject */
+export interface ProcessFileResult {
+  /** 处理后的内容（如压缩后的图片） */
+  buffer: Buffer;
+  /** 可选：覆盖上传时的 Content-Type（如压缩后统一为 image/jpeg） */
+  contentType?: string;
+}
+
+/**
+ * 上传前文件处理器接口。
+ * 实现后可在上传前对文件做压缩、转换等，未配置则直接上传原内容。
+ */
+export interface FileProcessor {
+  process(input: ProcessFileInput): Promise<ProcessFileResult>;
+}
+
+/**
+ * 默认实现：不做任何处理，直接返回原 buffer。
+ * 后续可替换为图片压缩等实现。
+ */
+export class NoOpFileProcessor implements FileProcessor {
+  async process(input: ProcessFileInput): Promise<ProcessFileResult> {
+    return { buffer: input.buffer };
+  }
+}

package/src/core/filters.ts

@@ -0,0 +1,31 @@
+import micromatch from 'micromatch';
+
+/**
+ * 根据 include/exclude 规则判断相对路径是否应参与上传。
+ * 使用 micromatch 支持 glob（如 **\/*.js）。
+ * @param relativePath 相对路径
+ * @param include 包含模式，不传则默认全部包含
+ * @param exclude 排除模式
+ * @returns 是否应包含该文件
+ */
+export function shouldInclude(
+  relativePath: string,
+  include?: string[],
+  exclude?: string[],
+): boolean {
+  let included = true;
+
+  if (include && include.length > 0) {
+    included = micromatch.isMatch(relativePath, include);
+  }
+  if (!included) return false;
+
+  if (exclude && exclude.length > 0) {
+    if (micromatch.isMatch(relativePath, exclude)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+

package/src/core/reporter.ts

@@ -0,0 +1,88 @@
+/**
+ * 上传结果上报抽象（Reporter）。
+ * 默认实现为控制台输出，可扩展为企业微信、钉钉等通知。
+ */
+
+export type UploadStatus = 'success' | 'failed' | 'skipped';
+
+/** 单个文件的上传结果，供 Reporter 使用 */
+export interface UploadFileResult {
+  localPath: string;
+  relativePath: string;
+  bucket: string;
+  key: string;
+  status: UploadStatus;
+  error?: Error;
+  /** 配置了 CDN 时的完整访问地址，由 buildCdnAccessUrl 生成 */
+  accessUrl?: string;
+}
+
+/** 整次上传的汇总统计 */
+export interface UploadSummary {
+  total: number;
+  success: number;
+  failed: number;
+  skipped: number;
+}
+
+/** Reporter 接口：上传开始、每个文件结果、全部完成时回调，便于接入不同通知方式 */
+export interface Reporter {
+  onStart?(context: {
+    env?: string;
+    bucket: string;
+    basePrefix: string;
+    pathPrefix?: string;
+    localDir: string;
+    cdnBaseUrl?: string;
+  }): void | Promise<void>;
+
+  onFileResult?(result: UploadFileResult): void | Promise<void>;
+
+  onComplete?(summary: UploadSummary): void | Promise<void>;
+}
+
+/** 默认实现：将上传进度与结果输出到控制台 */
+export class ConsoleReporter implements Reporter {
+  onStart(context: {
+    env?: string;
+    bucket: string;
+    basePrefix: string;
+    pathPrefix?: string;
+    localDir: string;
+    cdnBaseUrl?: string;
+  }): void {
+    const { env, bucket, basePrefix, pathPrefix, localDir, cdnBaseUrl } = context;
+    // console.log('开始上传目录:');
+    // console.log(`  环境: ${env ?? '未指定'}`);
+    // console.log(`  Bucket: ${bucket}`);
+    // console.log(`  Base 前缀: ${basePrefix || '(空)'}`);
+    // console.log(`  业务前缀(pathPrefix): ${pathPrefix || '(空)'}`);
+    // console.log(`  本地目录: ${localDir}`);
+    if (cdnBaseUrl) {
+      console.log(`  CDN 根地址: ${cdnBaseUrl}`);
+    }
+  }
+
+  onFileResult(result: UploadFileResult): void {
+    const { status, localPath, key, error, accessUrl } = result;
+    if (status === 'success') {
+      console.log(`[SUCCESS] ${localPath} -> ${key}`);
+      if (accessUrl) console.log(`  访问地址: ${accessUrl}`);
+    } else if (status === 'skipped') {
+      console.log(`[SKIPPED] ${localPath} -> ${key} (云端同名已存在)`);
+      if (accessUrl) console.log(`  访问地址: ${accessUrl}`);
+    } else {
+      console.error(`[FAILED]  ${localPath} -> ${key}`);
+      if (error) console.error(`  Error: ${error.message}`);
+    }
+  }
+
+  onComplete(summary: UploadSummary): void {
+    console.log('上传完成:');
+    console.log(`  总数: ${summary.total}`);
+    console.log(`  成功: ${summary.success}`);
+    console.log(`  失败: ${summary.failed}`);
+    console.log(`  跳过: ${summary.skipped}`);
+  }
+}
+

package/src/core/urlHelper.ts

@@ -0,0 +1,11 @@
+/**
+ * 根据 CDN 加速域名与对象 key 拼接完整的访问地址。
+ * @param cdnBaseUrl CDN 根地址（如 https://cdn.example.com），可带或不带末尾斜杠
+ * @param key 对象在桶内的 key（如 basePrefix/path/file.js）
+ * @returns 完整访问 URL，如 https://cdn.example.com/basePrefix/path/file.js
+ */
+export function buildCdnAccessUrl(cdnBaseUrl: string, key: string): string {
+  const base = cdnBaseUrl.replace(/\/+$/, '');
+  const pathPart = key.replace(/^\/+/, '');
+  return pathPart ? `${base}/${pathPart}` : base;
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * 包入口：显式导出所有对外 API 与类型，便于调用方按需引用。
+ */
+
+export { buildCdnAccessUrl } from './core/urlHelper';
+
+export {
+  type StorageClient,
+  type PutObjectOptions,
+  type HeadObjectResult,
+} from './core/StorageClient';
+
+export {
+  type Reporter,
+  type UploadFileResult,
+  type UploadSummary,
+  type UploadStatus,
+  ConsoleReporter,
+} from './core/reporter';
+
+export {
+  type FileProcessor,
+  type ProcessFileInput,
+  type ProcessFileResult,
+  NoOpFileProcessor,
+} from './core/fileProcessor';
+
+export {
+  UploadFlowTemplate,
+  type UploadContext,
+  type LocalFile,
+} from './core/UploadFlowTemplate';
+
+export {
+  DirectoryUploadFlow,
+} from './core/DirectoryUploadFlow';
+
+export {
+  createStorageClient,
+} from './core/StorageFactory';
+
+export {
+  OssService,
+  type UploadDirectoryInput,
+} from './middleware/OssService';
+
+export {
+  type HuaweiObsConfig,
+  type ProviderConfig,
+  type ProviderType,
+  type EnvConfigResolver,
+  type ResolvedProviderConfig,
+  type ProviderConfigResolver,
+} from './config/types';
+
+export {
+  EnvConfigResolverImpl,
+} from './config/EnvConfigResolverImpl';
+
+export {
+  ProviderConfigResolverImpl,
+} from './config/ProviderConfigResolverImpl';
+

package/src/middleware/OssService.ts

@@ -0,0 +1,54 @@
+import { Reporter, UploadSummary } from '../core/reporter';
+import { ProviderConfigResolver } from '../config/types';
+import { createStorageClient } from '../core/StorageFactory';
+import { DirectoryUploadFlow } from '../core/DirectoryUploadFlow';
+import type { FileProcessor } from '../core/fileProcessor';
+
+/** 上传目录的入参：环境、bucket、本地目录、路径前缀、过滤规则、Reporter、上传前文件处理器 */
+export interface UploadDirectoryInput {
+  env?: string;
+  bucket: string;
+  localDir: string;
+  pathPrefix?: string;
+  include?: string[];
+  exclude?: string[];
+  reporter?: Reporter;
+  /** 上传前对文件内容的处理器（如图片压缩），未配置则直接上传原内容 */
+  fileProcessor?: FileProcessor;
+}
+
+/**
+ * 中间件：对主流程暴露统一 API（Facade）。
+ * 内部只依赖 ProviderConfigResolver 得到当前 Provider 配置，再创建 StorageClient 与流程并执行。
+ * 切换云厂商时只需改 ProviderConfigResolver 的【一个实现文件】。
+ */
+export class OssService {
+  constructor(private readonly providerConfigResolver: ProviderConfigResolver) {}
+
+  /** 上传指定本地目录到 OSS，key 规则为 basePrefix/env/pathPrefix/相对路径，同名则跳过 */
+  async uploadDirectory(input: UploadDirectoryInput): Promise<UploadSummary> {
+    const { env, bucket= 'hr-uat', localDir, pathPrefix, include, exclude, reporter, fileProcessor } = input;
+
+    const resolved = this.providerConfigResolver.resolve();
+    const { providerConfig, basePrefix, cdnBaseUrl } = resolved;
+
+    const client = createStorageClient(providerConfig);
+
+    const flow = new DirectoryUploadFlow({
+      env,
+      bucket,
+      localDir,
+      pathPrefix,
+      include,
+      exclude,
+      basePrefix,
+      storageClient: client,
+      reporter,
+      cdnBaseUrl,
+      fileProcessor,
+    });
+
+    return flow.execute();
+  }
+}
+

package/src/providers/huawei/HuaweiObsClient.ts

@@ -0,0 +1,72 @@
+import { StorageClient, PutObjectOptions, HeadObjectResult } from '../../core/StorageClient';
+import { HuaweiObsConfig } from '../../config/types';
+
+// 华为 OBS Node.js SDK（CommonJS）
+const ObsClient = require('esdk-obs-nodejs');
+
+/**
+ * 华为 OBS 的 StorageClient 实现（Adapter）。
+ * 通过 SDK 的 getObjectMetadata 查元数据判断是否存在，putObject 上传对象。
+ */
+export class HuaweiObsClient implements StorageClient {
+  private readonly client: InstanceType<typeof ObsClient>;
+
+  constructor(private readonly config: HuaweiObsConfig) {
+    this.client = new ObsClient({
+      access_key_id: config.accessKey,
+      secret_access_key: config.secretKey,
+      server: config.endpoint,
+    });
+  }
+
+  /**
+   * 调用 OBS getObjectMetadata 查元数据，判断对象是否存在（同路径即跳过上传）。
+   */
+  async headObject(bucket: string, key: string): Promise<HeadObjectResult> {
+    try {
+      const result = await this.client.getObjectMetadata({
+        Bucket: bucket,
+        Key: key,
+      });
+
+      if (result.CommonMsg.Status <= 300) {
+        return { exists: true };
+      }
+
+      // 对象不存在
+      if (result.CommonMsg.Status === 404 || result.CommonMsg.Code === 'NoSuchKey' || result.CommonMsg.Code === 'NotFound') {
+        return { exists: false };
+      }
+
+      throw new Error(`OBS getObjectMetadata 失败: ${result.CommonMsg.Status} ${result.CommonMsg.Code} ${result.CommonMsg.Message}`);
+    } catch (err: unknown) {
+      const msg = err && typeof (err as any).message === 'string' ? (err as Error).message : String(err);
+      const code = (err as any)?.Code ?? (err as any)?.code;
+      if (code === 'NoSuchKey' || code === 'NotFound' || msg.includes('404') || msg.includes('NoSuchKey')) {
+        return { exists: false };
+      }
+      throw err;
+    }
+  }
+
+  /** 调用 OBS putObject 上传对象 */
+  async putObject(options: PutObjectOptions): Promise<void> {
+    const { bucket, key, body, contentType } = options;
+    // console.log('putObject', { bucket, key, endpoint: this.config.endpoint, accessKey: this.config.accessKey, secretKey: this.config.secretKey })
+    const result = await this.client.putObject({
+      Bucket: bucket,
+      Key: key,
+      Body: body,
+      // ContentType: contentType,
+    });
+
+    if (result.CommonMsg.Status > 300) {
+      const { Status, Code, Message, RequestId } = result.CommonMsg;
+      const detail = [Status, Code, Message, RequestId].filter(Boolean).join(' ');
+      throw new Error(
+        `OBS putObject 失败 (${detail || '无详情'}). ` +
+          '请检查: 1) 桶名是否正确且已创建 2) OBS_ENDPOINT 是否与该桶所在区域一致，如 https://obs.xx-xx-1.myhuaweicloud.com'
+      );
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}