midway-fatcms 0.0.5 → 0.0.6

package/dist/libs/crud-sharding/ShardingRouter.js

@@ -0,0 +1,377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingRouter = void 0;
+const moment = require("moment");
+const ShardingConfig_1 = require("./ShardingConfig");
+const ShardingUtils_1 = require("./ShardingUtils");
+/**
+ * 空值合并（兼容低版本 Node.js）
+ * 返回第一个非 null/undefined 的值
+ */
+function coalesce(a, b) {
+    return a !== null && a !== undefined ? a : b;
+}
+/**
+ * 分表路由器
+ */
+class ShardingRouter {
+    // ============ Public 方法 ============
+    /**
+     * 插入类操作专用路由（从 data 提取字段）
+     */
+    resolveForInsert(config, context) {
+        this.validateConfig(config);
+        switch (config.type) {
+            case ShardingConfig_1.ShardingType.YEAR:
+                return this.resolveTimeForInsert(config, context, 'year');
+            case ShardingConfig_1.ShardingType.MONTH:
+                return this.resolveTimeForInsert(config, context, 'month');
+            case ShardingConfig_1.ShardingType.DAY:
+                return this.resolveTimeForInsert(config, context, 'day');
+            case ShardingConfig_1.ShardingType.RANGE:
+                return this.resolveRangeForInsert(config, context);
+            case ShardingConfig_1.ShardingType.HASH:
+                return this.resolveHashForInsert(config, context);
+            case ShardingConfig_1.ShardingType.CUSTOM:
+                return this.resolveCustomForInsert(config, context);
+            default:
+                return config.baseTable;
+        }
+    }
+    /**
+     * 条件类操作专用路由（从 condition 提取字段）
+     */
+    resolveForCondition(config, context) {
+        this.validateConfig(config);
+        switch (config.type) {
+            case ShardingConfig_1.ShardingType.YEAR:
+                return this.resolveTimeForCondition(config, context, 'year');
+            case ShardingConfig_1.ShardingType.MONTH:
+                return this.resolveTimeForCondition(config, context, 'month');
+            case ShardingConfig_1.ShardingType.DAY:
+                return this.resolveTimeForCondition(config, context, 'day');
+            case ShardingConfig_1.ShardingType.RANGE:
+                return this.resolveRangeForCondition(config, context);
+            case ShardingConfig_1.ShardingType.HASH:
+                return this.resolveHashForCondition(config, context);
+            case ShardingConfig_1.ShardingType.CUSTOM:
+                return this.resolveCustomForCondition(config, context);
+            default:
+                return config.baseTable;
+        }
+    }
+    /**
+     * 查询专用路由（带表存在性过滤）
+     */
+    async resolveQuery(config, context, tableInfoProvider) {
+        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);
+    }
+    /**
+     * 过滤出真实存在的分表
+     */
+    filterExistingTables(candidateTables, existingTables) {
+        const candidates = Array.isArray(candidateTables) ? candidateTables : [candidateTables];
+        return candidates.filter(table => existingTables.has(table));
+    }
+    // ============ 配置校验 ============
+    validateConfig(config) {
+        if (!config.baseTable) {
+            throw new Error('[ShardingRouter] baseTable 不能为空');
+        }
+        if ((config.type === ShardingConfig_1.ShardingType.RANGE || config.type === ShardingConfig_1.ShardingType.HASH) && !config.shardingColumn) {
+            throw new Error(`[ShardingRouter] ${config.type} 分表必须指定 shardingColumn`);
+        }
+        if (config.type === ShardingConfig_1.ShardingType.CUSTOM && !config.customRouter) {
+            throw new Error('[ShardingRouter] CUSTOM 分表必须提供 customRouter 函数');
+        }
+    }
+    // ============ 时间分表路由 ============
+    resolveTimeForInsert(config, context, granularity) {
+        const { baseTable, timeColumn } = config;
+        const timeValue = this.extractTimeFromData(context.data, timeColumn);
+        const suffix = (0, ShardingUtils_1.getTimeSuffix)(timeValue, granularity);
+        return this.formatTableName(baseTable, suffix, config);
+    }
+    resolveTimeForCondition(config, context, granularity) {
+        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 = (0, ShardingUtils_1.getTimeSuffix)(singleTimeValue, granularity);
+            return this.formatTableName(baseTable, suffix, config);
+        }
+        const recentCount = this.getRecentCountByGranularity(granularity, config);
+        return this.getRecentTables(baseTable, granularity, recentCount, config);
+    }
+    // ============ 范围分表路由 ============
+    resolveRangeForInsert(config, context) {
+        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);
+    }
+    resolveRangeForCondition(config, context) {
+        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);
+    }
+    // ============ 哈希分表路由 ============
+    resolveHashForInsert(config, context) {
+        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);
+    }
+    resolveHashForCondition(config, context) {
+        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);
+    }
+    // ============ 自定义分表路由 ============
+    resolveCustomForInsert(config, context) {
+        const result = config.customRouter(context);
+        return Array.isArray(result) ? result[0] : result;
+    }
+    resolveCustomForCondition(config, context) {
+        return config.customRouter(context);
+    }
+    // ============ 查询相关私有方法 ============
+    isTimeSharding(config) {
+        return [ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.ShardingType.DAY].includes(config.type);
+    }
+    getRecentExistingTablesFromAll(existingTables, config, condition) {
+        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);
+    }
+    intersectWithCondition(tables, config, condition) {
+        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 = (0, ShardingUtils_1.getTimeSuffix)(singleTimeValue, config.type);
+            const targetTable = `${config.baseTable}_${suffix}`;
+            return tables.includes(targetTable) ? [targetTable] : [];
+        }
+        return this.sortTablesByTimeDesc(tables);
+    }
+    intersectTablesByTimeRange(tables, timeRange, config) {
+        const startSuffix = (0, ShardingUtils_1.getTimeSuffix)(timeRange.start, config.type);
+        const endSuffix = (0, ShardingUtils_1.getTimeSuffix)(timeRange.end, config.type);
+        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），
+     * 字典序即时间序，降序即新→旧。
+     */
+    sortTablesByTimeDesc(tables) {
+        return [...tables].sort((a, b) => b.localeCompare(a));
+    }
+    // ============ 值提取：基础方法 ============
+    extractFromData(data, column) {
+        return data === null || data === void 0 ? void 0 : data[column];
+    }
+    extractFromCondition(condition, column) {
+        return condition === null || condition === void 0 ? void 0 : condition[column];
+    }
+    parseTimeValue(value, source, operation) {
+        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();
+    }
+    parseColumnValue(value, source, operation) {
+        if (value === undefined || value === null) {
+            throw new Error(`[ShardingRouter] ${operation} 操作无法从 ${source} 中获取分表字段的值`);
+        }
+        return value;
+    }
+    // ============ 值提取：时间字段 ============
+    extractTimeFromData(data, column) {
+        const value = this.extractFromData(data, column);
+        return this.parseTimeValue(value, 'data', 'insert');
+    }
+    tryExtractTimeFromCondition(condition, column) {
+        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();
+    }
+    extractTimeRange(condition, column) {
+        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;
+    }
+    // ============ 值提取：分表字段 ============
+    extractColumnFromData(data, column) {
+        const value = this.extractFromData(data, column);
+        return this.parseColumnValue(value, 'data', 'insert');
+    }
+    extractColumnFromCondition(condition, column) {
+        const value = this.extractFromCondition(condition, column);
+        return this.parseColumnValue(value, 'condition', '查询/更新/删除');
+    }
+    // ============ 时间处理 ============
+    generateTablesInRange(baseTable, start, end, granularity, config) {
+        const tables = [];
+        const current = moment(start);
+        const maxTables = 100;
+        while (current.toDate() <= end && tables.length < maxTables) {
+            const suffix = (0, ShardingUtils_1.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;
+    }
+    getRecentTables(baseTable, granularity, count, config) {
+        const tables = [];
+        const current = moment();
+        for (let i = 0; i < count; i++) {
+            const suffix = (0, ShardingUtils_1.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;
+    }
+    getRecentCountByGranularity(granularity, config) {
+        if (config.recentTableCount !== undefined && config.recentTableCount > 0) {
+            return config.recentTableCount;
+        }
+        switch (granularity) {
+            case 'year':
+                return 3;
+            case 'month':
+                return 12;
+            case 'day':
+                return 7;
+        }
+    }
+    // ============ 计算相关 ============
+    calculateRangeIndex(value, count) {
+        if (typeof value === 'number') {
+            return Math.abs(value) % count;
+        }
+        return Math.abs(this.simpleHash(String(value))) % count;
+    }
+    calculateHash(value, count) {
+        return Math.abs(this.simpleHash(String(value))) % count;
+    }
+    simpleHash(str) {
+        let hash = 5381;
+        for (let i = 0; i < str.length; i++) {
+            hash = ((hash << 5) + hash) + str.charCodeAt(i);
+            hash = hash & hash;
+        }
+        return hash;
+    }
+    // ============ 格式化 ============
+    formatTableName(baseTable, suffix, config) {
+        const formattedSuffix = config.suffixFormatter ? config.suffixFormatter(suffix) : suffix;
+        return `${baseTable}_${formattedSuffix}`;
+    }
+}
+exports.ShardingRouter = ShardingRouter;

package/dist/libs/crud-sharding/ShardingTableCreator.d.ts

@@ -0,0 +1,146 @@
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { SqlDbType } from '../../libs/crud-pro/models/keys';
+import { IShardingConfig, IShardingTableCreateOptions, IShardingTableCreateResult } from './ShardingConfig';
+/**
+ * 分表自动创建器
+ *
+ * 根据基表结构自动创建分表，支持 MySQL、PostgreSQL、SQL Server。
+ *
+ * @example
+ * const creator = new ShardingTableCreator(crudPro, config);
+ * await creator.createTableIfNeeded('t_order_202403', {
+ *   sqlDatabase: 'mydb',
+ *   sqlDbType: SqlDbType.mysql,
+ * });
+ */
+export declare class ShardingTableCreator {
+    private readonly crudPro;
+    private readonly config;
+    constructor(crudPro: CrudPro, config: IShardingConfig);
+    /**
+     * 校验表名格式，防止 SQL 注入
+     * 只允许合法的数据库标识符：以字母或下划线开头，后续只能包含字母数字下划线
+     */
+    private validateIdentifier;
+    /**
+     * 创建分表（如果不存在）
+     *
+     * @param tableName 目标分表名
+     * @param baseCfg 基础配置（sqlDatabase, sqlDbType）
+     * @param options 创建选项
+     * @returns 创建结果
+     */
+    createTableIfNeeded(tableName: string, baseCfg: {
+        sqlDatabase: string;
+        sqlDbType: SqlDbType;
+    }, options?: IShardingTableCreateOptions): Promise<IShardingTableCreateResult>;
+    /**
+     * 获取基表列信息
+     */
+    private getBaseTableMeta;
+    /**
+     * 根据数据库类型加载表列信息
+     */
+    private loadTableColumns;
+    /**
+     * 加载 MySQL 表列信息
+     */
+    private loadMySQLColumns;
+    /**
+     * 加载 PostgreSQL 表列信息
+     */
+    private loadPostgreSQLColumns;
+    /**
+     * 获取 PostgreSQL 表主键列
+     */
+    private getPostgreSQLPrimaryKeys;
+    /**
+     * 加载 SQL Server 表列信息
+     */
+    private loadSQLServerColumns;
+    /**
+     * 获取 SQL Server 表主键列
+     */
+    private getSQLServerPrimaryKeys;
+    /**
+     * 生成建表 SQL
+     */
+    private generateCreateTableSql;
+    private generateMySQLCreateSql;
+    private formatMySQLColumn;
+    private generatePostgreSQLCreateSql;
+    private formatPostgreSQLColumn;
+    private mapToPostgreSQLType;
+    private generateSQLServerCreateSql;
+    private formatSQLServerColumn;
+    private mapToSQLServerType;
+    /**
+     * 清理 SQL Server 系统目录中的默认值表达式
+     *
+     * sys.default_constraints.definition 返回格式如 ((1)), ('abc'), (getdate())
+     * 需要去除最外层括号，还原为可用的默认值
+     */
+    private normalizeSQLServerDefaultValue;
+    /**
+     * 清理 PostgreSQL 系统目录中的默认值表达式
+     *
+     * column_default 返回值如：
+     * - nextval('xxx_seq'::regclass) → 序列自增，不应作为 DEFAULT
+     * - 'hello'::character varying → 带类型后缀的字符串默认值
+     * - 1, true, now() 等
+     */
+    private normalizePostgreSQLDefaultValue;
+    /**
+     * 格式化默认值
+     */
+    private formatDefaultValue;
+    /**
+     * 转义字符串
+     */
+    private escapeString;
+    /**
+     * 执行建表 SQL
+     */
+    private executeCreateSql;
+    /**
+     * 复制索引（可选功能）
+     *
+     * 从基表复制索引到分表。
+     * 注意：主键索引已在建表时创建，此处只复制普通索引。
+     */
+    private copyIndexes;
+    /**
+     * 在索引 SQL 中替换表名
+     *
+     * 支持 MySQL(反引号)、PostgreSQL(双引号)、SQL Server(方括号) 的标识符语法
+     */
+    private replaceTableNameInIndexSql;
+    /**
+     * 获取基表的索引定义
+     *
+     * 支持 MySQL、PostgreSQL、SQL Server，返回可直接执行的 CREATE INDEX 语句
+     */
+    private getIndexDefinitions;
+    /**
+     * 获取 MySQL 索引定义
+     */
+    private getMySQLIndexDefinitions;
+    /**
+     * 获取 PostgreSQL 索引定义
+     */
+    private getPostgreSQLIndexDefinitions;
+    /**
+     * 获取 SQL Server 索引定义
+     */
+    private getSQLServerIndexDefinitions;
+    /**
+     * 重命名索引（避免不同分表索引名冲突）
+     *
+     * 支持 MySQL、PostgreSQL、SQL Server 的标识符语法
+     */
+    private renameIndex;
+    /**
+     * 转义正则特殊字符
+     */
+    private escapeRegExp;
+}