midway-fatcms 0.0.5 → 0.0.7

package/src/libs/crud-sharding/ShardingRouter.ts

@@ -0,0 +1,512 @@
+import * as moment from 'moment';
+import { ShardingType, IShardingConfig, IShardingRouterContext, IShardingTimeRange } from './ShardingConfig';
+import { ShardingTimeGranularity, getTimeSuffix } from './ShardingUtils';
+
+/**
+ * 空值合并（兼容低版本 Node.js）
+ * 返回第一个非 null/undefined 的值
+ */
+function coalesce(a: any, b: any): any {
+  return a !== null && a !== undefined ? a : b;
+}
+
+/**
+ * 表信息提供者接口
+ * 用于获取数据库中真实存在的表
+ */
+export interface ITableInfoProvider {
+  /**
+   * 获取所有真实存在的表名
+   * @returns 表名集合
+   */
+  getExistingTables(): Promise<Set<string>>;
+}
+
+/**
+ * 分表路由器
+ */
+export class ShardingRouter {
+  // ============ Public 方法 ============
+
+  /**
+   * 插入类操作专用路由（从 data 提取字段）
+   */
+  public resolveForInsert(
+    config: IShardingConfig,
+    context: IShardingRouterContext
+  ): string {
+    this.validateConfig(config);
+
+    switch (config.type) {
+      case ShardingType.YEAR:
+        return this.resolveTimeForInsert(config, context, 'year');
+      case ShardingType.MONTH:
+        return this.resolveTimeForInsert(config, context, 'month');
+      case ShardingType.DAY:
+        return this.resolveTimeForInsert(config, context, 'day');
+      case ShardingType.RANGE:
+        return this.resolveRangeForInsert(config, context);
+      case ShardingType.HASH:
+        return this.resolveHashForInsert(config, context);
+      case ShardingType.CUSTOM:
+        return this.resolveCustomForInsert(config, context);
+      default:
+        return config.baseTable;
+    }
+  }
+
+  /**
+   * 条件类操作专用路由（从 condition 提取字段）
+   */
+  public resolveForCondition(
+    config: IShardingConfig,
+    context: IShardingRouterContext
+  ): string | string[] {
+    this.validateConfig(config);
+
+    switch (config.type) {
+      case ShardingType.YEAR:
+        return this.resolveTimeForCondition(config, context, 'year');
+      case ShardingType.MONTH:
+        return this.resolveTimeForCondition(config, context, 'month');
+      case ShardingType.DAY:
+        return this.resolveTimeForCondition(config, context, 'day');
+      case ShardingType.RANGE:
+        return this.resolveRangeForCondition(config, context);
+      case ShardingType.HASH:
+        return this.resolveHashForCondition(config, context);
+      case ShardingType.CUSTOM:
+        return this.resolveCustomForCondition(config, context);
+      default:
+        return config.baseTable;
+    }
+  }
+
+  /**
+   * 查询专用路由（带表存在性过滤）
+   */
+  public async resolveQuery(
+    config: IShardingConfig,
+    context: IShardingRouterContext,
+    tableInfoProvider: ITableInfoProvider
+  ): Promise<string[]> {
+    const existingTables = await tableInfoProvider.getExistingTables();
+
+    // 时间分表：从真实存在的表中取最近N张，再与条件取交集
+    if (this.isTimeSharding(config)) {
+      return this.getRecentExistingTablesFromAll(existingTables, config, context.condition);
+    }
+
+    // 非时间分表：先计算候选表，再过滤存在的表
+    const candidateResult = this.resolveForCondition(config, context);
+    const candidateTables = Array.isArray(candidateResult)
+      ? candidateResult
+      : [candidateResult];
+
+    return this.filterExistingTables(candidateTables, existingTables);
+  }
+
+  /**
+   * 过滤出真实存在的分表
+   */
+  public filterExistingTables(
+    candidateTables: string | string[],
+    existingTables: Set<string>
+  ): string[] {
+    const candidates = Array.isArray(candidateTables) ? candidateTables : [candidateTables];
+    return candidates.filter(table => existingTables.has(table));
+  }
+
+  // ============ 配置校验 ============
+
+  private validateConfig(config: IShardingConfig): void {
+    if (!config.baseTable) {
+      throw new Error('[ShardingRouter] baseTable 不能为空');
+    }
+
+    if ((config.type === ShardingType.RANGE || config.type === ShardingType.HASH) && !config.shardingColumn) {
+      throw new Error(`[ShardingRouter] ${config.type} 分表必须指定 shardingColumn`);
+    }
+
+    if (config.type === ShardingType.CUSTOM && !config.customRouter) {
+      throw new Error('[ShardingRouter] CUSTOM 分表必须提供 customRouter 函数');
+    }
+  }
+
+  // ============ 时间分表路由 ============
+
+  private resolveTimeForInsert(
+    config: IShardingConfig,
+    context: IShardingRouterContext,
+    granularity: ShardingTimeGranularity
+  ): string {
+    const { baseTable, timeColumn } = config;
+    const timeValue = this.extractTimeFromData(context.data, timeColumn!);
+    const suffix = getTimeSuffix(timeValue, granularity);
+    return this.formatTableName(baseTable, suffix, config);
+  }
+
+  private resolveTimeForCondition(
+    config: IShardingConfig,
+    context: IShardingRouterContext,
+    granularity: ShardingTimeGranularity
+  ): string | string[] {
+    const { baseTable, timeColumn } = config;
+    const condition = context.condition || {};
+
+    const timeRange = this.extractTimeRange(condition, timeColumn!);
+    const singleTimeValue = this.tryExtractTimeFromCondition(condition, timeColumn!);
+
+    if (timeRange) {
+      return this.generateTablesInRange(baseTable, timeRange.start, timeRange.end, granularity, config);
+    }
+
+    if (singleTimeValue) {
+      const suffix = getTimeSuffix(singleTimeValue, granularity);
+      return this.formatTableName(baseTable, suffix, config);
+    }
+
+    const recentCount = this.getRecentCountByGranularity(granularity, config);
+    return this.getRecentTables(baseTable, granularity, recentCount, config);
+  }
+
+  // ============ 范围分表路由 ============
+
+  private resolveRangeForInsert(config: IShardingConfig, context: IShardingRouterContext): string {
+    const { baseTable, tableCount = 10, shardingColumn } = config;
+    const value = this.extractColumnFromData(context.data, shardingColumn);
+    const index = this.calculateRangeIndex(value, tableCount);
+    return this.formatTableName(baseTable, String(index), config);
+  }
+
+  private resolveRangeForCondition(config: IShardingConfig, context: IShardingRouterContext): string {
+    const { baseTable, tableCount = 10, shardingColumn } = config;
+    const value = this.extractColumnFromCondition(context.condition, shardingColumn);
+    const index = this.calculateRangeIndex(value, tableCount);
+    return this.formatTableName(baseTable, String(index), config);
+  }
+
+  // ============ 哈希分表路由 ============
+
+  private resolveHashForInsert(config: IShardingConfig, context: IShardingRouterContext): string {
+    const { baseTable, tableCount = 16, shardingColumn } = config;
+    const value = this.extractColumnFromData(context.data, shardingColumn);
+    const index = this.calculateHash(value, tableCount);
+    return this.formatTableName(baseTable, String(index).padStart(2, '0'), config);
+  }
+
+  private resolveHashForCondition(config: IShardingConfig, context: IShardingRouterContext): string {
+    const { baseTable, tableCount = 16, shardingColumn } = config;
+    const value = this.extractColumnFromCondition(context.condition, shardingColumn);
+    const index = this.calculateHash(value, tableCount);
+    return this.formatTableName(baseTable, String(index).padStart(2, '0'), config);
+  }
+
+  // ============ 自定义分表路由 ============
+
+  private resolveCustomForInsert(config: IShardingConfig, context: IShardingRouterContext): string {
+    const result = config.customRouter!(context);
+    return Array.isArray(result) ? result[0] : result;
+  }
+
+  private resolveCustomForCondition(config: IShardingConfig, context: IShardingRouterContext): string | string[] {
+    return config.customRouter!(context);
+  }
+
+  // ============ 查询相关私有方法 ============
+
+  private isTimeSharding(config: IShardingConfig): boolean {
+    return [ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(config.type);
+  }
+
+  private getRecentExistingTablesFromAll(
+    existingTables: Set<string>,
+    config: IShardingConfig,
+    condition?: Record<string, any>
+  ): string[] {
+    const baseTablePrefix = `${config.baseTable}_`;
+    const shardingTables = Array.from(existingTables).filter(t =>
+      t.startsWith(baseTablePrefix)
+    );
+
+    if (shardingTables.length === 0) {
+      return [];
+    }
+
+    shardingTables.sort();
+
+    // 配置了 recentTableCount：取最近N张，再与条件取交集
+    if (config.recentTableCount !== undefined) {
+      const recentTables = shardingTables.slice(-config.recentTableCount);
+      return this.intersectWithCondition(recentTables, config, condition);
+    }
+
+    // 未配置 recentTableCount：所有表与条件取交集，最多取3张
+    const intersected = this.intersectWithCondition(shardingTables, config, condition);
+    return intersected.slice(0, 3);
+  }
+
+  private intersectWithCondition(
+    tables: string[],
+    config: IShardingConfig,
+    condition?: Record<string, any>
+  ): string[] {
+    if (!condition) {
+      return this.sortTablesByTimeDesc(tables);
+    }
+
+    const timeColumn = config.timeColumn!;
+    const timeRange = this.extractTimeRange(condition, timeColumn);
+    if (timeRange) {
+      return this.intersectTablesByTimeRange(tables, timeRange, config);
+    }
+
+    const singleTimeValue = this.tryExtractTimeFromCondition(condition, timeColumn);
+    if (singleTimeValue) {
+      const suffix = getTimeSuffix(singleTimeValue, config.type as any);
+      const targetTable = `${config.baseTable}_${suffix}`;
+      return tables.includes(targetTable) ? [targetTable] : [];
+    }
+
+    return this.sortTablesByTimeDesc(tables);
+  }
+
+  private intersectTablesByTimeRange(
+    tables: string[],
+    timeRange: IShardingTimeRange,
+    config: IShardingConfig
+  ): string[] {
+    const startSuffix = getTimeSuffix(timeRange.start, config.type as any);
+    const endSuffix = getTimeSuffix(timeRange.end, config.type as any);
+    const baseTablePrefix = `${config.baseTable}_`;
+
+    const prefixLen = baseTablePrefix.length;
+    return this.sortTablesByTimeDesc(tables.filter(table => {
+      const suffix = table.substring(prefixLen);
+      return suffix >= startSuffix && suffix <= endSuffix;
+    }));
+  }
+
+  // ============ 排序 ============
+
+  /**
+   * 将分表按时间后缀降序排列（新→旧）
+   *
+   * 分表名格式为 baseTable_suffix，后缀为时间格式（如 202403、20240101），
+   * 字典序即时间序，降序即新→旧。
+   */
+  private sortTablesByTimeDesc(tables: string[]): string[] {
+    return [...tables].sort((a, b) => b.localeCompare(a));
+  }
+
+  // ============ 值提取：基础方法 ============
+
+  private extractFromData(data: any, column: string): any {
+    return data?.[column];
+  }
+
+  private extractFromCondition(condition: any, column: string): any {
+    return condition?.[column];
+  }
+
+  private parseTimeValue(value: any, source: string, operation: string): Date {
+    if (value === undefined || value === null) {
+      throw new Error(`[ShardingRouter] ${operation} 操作无法从 ${source} 中获取时间分表字段的值`);
+    }
+
+    const m = moment(value);
+    if (!m.isValid()) {
+      throw new Error(`[ShardingRouter] 无法解析时间分表字段的值：${value}`);
+    }
+    return m.toDate();
+  }
+
+  private parseColumnValue(value: any, source: string, operation: string): any {
+    if (value === undefined || value === null) {
+      throw new Error(`[ShardingRouter] ${operation} 操作无法从 ${source} 中获取分表字段的值`);
+    }
+    return value;
+  }
+
+  // ============ 值提取：时间字段 ============
+
+  private extractTimeFromData(data: any, column: string): Date {
+    const value = this.extractFromData(data, column);
+    return this.parseTimeValue(value, 'data', 'insert');
+  }
+
+  private tryExtractTimeFromCondition(condition: any, column: string): Date | null {
+    const value = this.extractFromCondition(condition, column);
+    if (value === undefined || value === null) {
+      return null;
+    }
+
+    const m = moment(value);
+    if (!m.isValid()) {
+      return null;
+    }
+    return m.toDate();
+  }
+
+  private extractTimeRange(condition: any, column: string): IShardingTimeRange | null {
+    const colCond = condition[column];
+    if (!colCond || typeof colCond !== 'object') return null;
+
+    const start = coalesce(colCond.$gte, colCond.$gt);
+    const end = coalesce(colCond.$lte, colCond.$lt);
+
+    if (start && end) {
+      const startMoment = moment(start);
+      const endMoment = moment(end);
+      if (!startMoment.isValid() || !endMoment.isValid()) {
+        return null;
+      }
+      return {
+        start: startMoment.toDate(),
+        end: endMoment.toDate(),
+      };
+    }
+
+    if (start) {
+      const startMoment = moment(start);
+      if (!startMoment.isValid()) {
+        return null;
+      }
+      return {
+        start: startMoment.toDate(),
+        end: new Date(),
+      };
+    }
+
+    if (end) {
+      const endMoment = moment(end);
+      if (!endMoment.isValid()) {
+        return null;
+      }
+      return {
+        start: new Date(0),
+        end: endMoment.toDate(),
+      };
+    }
+
+    return null;
+  }
+
+  // ============ 值提取：分表字段 ============
+
+  private extractColumnFromData(data: any, column: string): any {
+    const value = this.extractFromData(data, column);
+    return this.parseColumnValue(value, 'data', 'insert');
+  }
+
+  private extractColumnFromCondition(condition: any, column: string): any {
+    const value = this.extractFromCondition(condition, column);
+    return this.parseColumnValue(value, 'condition', '查询/更新/删除');
+  }
+
+  // ============ 时间处理 ============
+
+  private generateTablesInRange(
+    baseTable: string,
+    start: Date,
+    end: Date,
+    granularity: ShardingTimeGranularity,
+    config: IShardingConfig
+  ): string[] {
+    const tables: string[] = [];
+    const current = moment(start);
+    const maxTables = 100;
+
+    while (current.toDate() <= end && tables.length < maxTables) {
+      const suffix = getTimeSuffix(current.toDate(), granularity);
+      tables.push(this.formatTableName(baseTable, suffix, config));
+
+      switch (granularity) {
+        case 'year':
+          current.add(1, 'year');
+          break;
+        case 'month':
+          current.add(1, 'month');
+          break;
+        case 'day':
+          current.add(1, 'day');
+          break;
+      }
+    }
+
+    return tables;
+  }
+
+  private getRecentTables(
+    baseTable: string,
+    granularity: ShardingTimeGranularity,
+    count: number,
+    config: IShardingConfig
+  ): string[] {
+    const tables: string[] = [];
+    const current = moment();
+
+    for (let i = 0; i < count; i++) {
+      const suffix = getTimeSuffix(current.toDate(), granularity);
+      tables.unshift(this.formatTableName(baseTable, suffix, config));
+
+      switch (granularity) {
+        case 'year':
+          current.subtract(1, 'year');
+          break;
+        case 'month':
+          current.subtract(1, 'month');
+          break;
+        case 'day':
+          current.subtract(1, 'day');
+          break;
+      }
+    }
+
+    return tables;
+  }
+
+  private getRecentCountByGranularity(granularity: ShardingTimeGranularity, config: IShardingConfig): number {
+    if (config.recentTableCount !== undefined && config.recentTableCount > 0) {
+      return config.recentTableCount;
+    }
+
+    switch (granularity) {
+      case 'year':
+        return 3;
+      case 'month':
+        return 12;
+      case 'day':
+        return 7;
+    }
+  }
+
+  // ============ 计算相关 ============
+
+  private calculateRangeIndex(value: any, count: number): number {
+    if (typeof value === 'number') {
+      return Math.abs(value) % count;
+    }
+    return Math.abs(this.simpleHash(String(value))) % count;
+  }
+
+  private calculateHash(value: any, count: number): number {
+    return Math.abs(this.simpleHash(String(value))) % count;
+  }
+
+  private simpleHash(str: string): number {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) + hash) + str.charCodeAt(i);
+      hash = hash & hash;
+    }
+    return hash;
+  }
+
+  // ============ 格式化 ============
+
+  private formatTableName(baseTable: string, suffix: string, config: IShardingConfig): string {
+    const formattedSuffix = config.suffixFormatter ? config.suffixFormatter(suffix) : suffix;
+    return `${baseTable}_${formattedSuffix}`;
+  }
+}