midway-fatcms 0.0.5 → 0.0.7

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

@@ -0,0 +1,130 @@
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { IRequestModel, IRequestCfgModel } from '../../libs/crud-pro/interfaces';
+import { ShardingCountCache } from './ShardingCountCache';
+/**
+ * 分页查询结果
+ */
+export interface IShardingPageQueryResult {
+    rows: any[];
+    total_count: number;
+}
+/**
+ * 分表查询结果合并器
+ *
+ * 处理跨多个分表的查询结果合并：
+ * - 分页查询：顺序累计查询 + 结果合并
+ * - 列表查询：并行查询 + 结果合并
+ *
+ * 使用约束（时间分表专用）：
+ * - 排序字段必须是分表字段（timeColumn/created_at）
+ * - 排序方向支持 DESC（最新在前）和 ASC（最旧在前）
+ * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由 ShardingCrudPro 保证）
+ *
+ * 在上述约束下，无需内存排序，直接按表顺序拼接即可。
+ */
+export declare class ShardingMerger {
+    private countCache;
+    /**
+     * 设置 COUNT 缓存实例
+     */
+    setCountCache(cache: ShardingCountCache): void;
+    /**
+     * 合并多表分页查询结果（时间分表专用，按表顺序拼接优化）
+     *
+     * 前提条件：
+     * - DESC 时 tables 已按时间倒序排列（新→旧），ASC 时已按时间正序排列（旧→新）
+     * - orderBy 为 timeColumn DESC 或 timeColumn ASC
+     *
+     * 执行流程：
+     * 1. 并行统计各分表记录数
+     * 2. 根据累计数量直接定位目标表，跳过无关表
+     * 3. 只查询包含目标数据的分表，精确计算表内偏移
+     *
+     * @param crudPro CrudPro 实例
+     * @param tables 分表列表（DESC: 新→旧，ASC: 旧→新）
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @returns 分页结果
+     */
+    mergePageQuery(crudPro: CrudPro, tables: string[], reqJson: IRequestModel, cfgJson: IRequestCfgModel): Promise<IShardingPageQueryResult>;
+    /**
+     * 合并多表普通查询结果（时间分表专用，按表顺序拼接优化）
+     *
+     * 前提条件：
+     * - DESC 时 tables 已按时间倒序排列（新→旧），ASC 时已按时间正序排列（旧→新）
+     * - orderBy 为 timeColumn DESC 或 timeColumn ASC
+     *
+     * 执行流程：
+     * 1. 串行查询分表，按表顺序拼接
+     * 2. 达到 maxRows 上限后立即停止，避免查询无关表
+     *
+     * @param crudPro CrudPro 实例
+     * @param tables 分表列表（DESC: 新→旧，ASC: 旧→新）
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @param maxRows 最大返回行数（默认 10000，防止 OOM）
+     * @returns 数据列表
+     */
+    mergeQuery(crudPro: CrudPro, tables: string[], reqJson: IRequestModel, cfgJson: IRequestCfgModel, maxRows?: number): Promise<any[]>;
+    /**
+     * 根据各表数量和分页偏移，直接定位目标表
+     *
+     * 核心优化：跳过不包含目标数据的分表，只返回需要查询的表及其表内偏移
+     *
+     * 示例：
+     * tables:  [t_order_202403, t_order_202402, t_order_202401]
+     * counts:  [5, 20, 1000]
+     * 累计:    [5, 25, 1025]
+     *
+     * offset=990, targetEnd=1000
+     * → 202403 累计5 < 990，跳过
+     * → 202402 累计25 < 990，跳过
+     * → 202401 累计1025 >= 990，命中
+     *   innerOffset = 990 - 25 = 965
+     *   innerLimit = min(1000-25, 1025-990) = 10
+     *
+     * @param tables 分表列表
+     * @param counts 各表记录数
+     * @param offset 全局偏移
+     * @param targetEnd 全局截止位置
+     */
+    private locateTargetTables;
+    /**
+     * 安全查询记录数（表不存在时返回0）
+     *
+     * 支持 COUNT 缓存：历史时间分表使用缓存，当前表实时查询
+     */
+    private queryCountSafe;
+    /**
+     * 安全查询数据行（表不存在时返回空数组）
+     */
+    private queryRowsSafe;
+    /**
+     * 安全查询数据行（支持表内偏移，表不存在时返回空数组）
+     *
+     * 用于分页定位后，直接从某张表指定偏移处取数据
+     *
+     * @param crudPro CrudPro 实例
+     * @param table 分表名
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @param innerOffset 表内偏移（跳过前 N 条）
+     * @param innerLimit 取多少条
+     */
+    private queryRowsSafeWithOffset;
+    /**
+     * 执行 COUNT 查询
+     */
+    private executeCountQuery;
+    /**
+     * 执行数据查询
+     */
+    private executeQuery;
+    /**
+     * 执行数据查询（带表内偏移）
+     *
+     * 用于分页定位后，直接从指定偏移处取数据
+     * innerOffset=965, innerLimit=10 表示跳过该表前 965 条，取 10 条
+     */
+    private executeQueryWithOffset;
+}

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

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingMerger = void 0;
+const keys_1 = require("../../libs/crud-pro/models/keys");
+const ShardingCountCache_1 = require("./ShardingCountCache");
+/**
+ * 分表查询结果合并器
+ *
+ * 处理跨多个分表的查询结果合并：
+ * - 分页查询：顺序累计查询 + 结果合并
+ * - 列表查询：并行查询 + 结果合并
+ *
+ * 使用约束（时间分表专用）：
+ * - 排序字段必须是分表字段（timeColumn/created_at）
+ * - 排序方向支持 DESC（最新在前）和 ASC（最旧在前）
+ * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由 ShardingCrudPro 保证）
+ *
+ * 在上述约束下，无需内存排序，直接按表顺序拼接即可。
+ */
+class ShardingMerger {
+    /**
+     * 设置 COUNT 缓存实例
+     */
+    setCountCache(cache) {
+        this.countCache = cache;
+    }
+    /**
+     * 合并多表分页查询结果（时间分表专用，按表顺序拼接优化）
+     *
+     * 前提条件：
+     * - DESC 时 tables 已按时间倒序排列（新→旧），ASC 时已按时间正序排列（旧→新）
+     * - orderBy 为 timeColumn DESC 或 timeColumn ASC
+     *
+     * 执行流程：
+     * 1. 并行统计各分表记录数
+     * 2. 根据累计数量直接定位目标表，跳过无关表
+     * 3. 只查询包含目标数据的分表，精确计算表内偏移
+     *
+     * @param crudPro CrudPro 实例
+     * @param tables 分表列表（DESC: 新→旧，ASC: 旧→新）
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @returns 分页结果
+     */
+    async mergePageQuery(crudPro, tables, reqJson, cfgJson) {
+        const { pageNo = 1, pageSize = 10 } = reqJson;
+        const offset = (pageNo - 1) * pageSize;
+        const targetEnd = offset + pageSize; // 需要取到第几条
+        // 1. 并行查询所有分表的记录数
+        const countPromises = tables.map(table => this.queryCountSafe(crudPro, table, reqJson, cfgJson));
+        const counts = await Promise.all(countPromises);
+        const totalCount = counts.reduce((sum, c) => sum + c, 0);
+        // 总数为0，直接返回
+        if (totalCount === 0) {
+            return { rows: [], total_count: 0 };
+        }
+        // 2. 根据累计数量直接定位目标表
+        const targetTables = this.locateTargetTables(tables, counts, offset, targetEnd);
+        // 3. 只查询包含目标数据的分表
+        let allRows = [];
+        for (const target of targetTables) {
+            const rows = await this.queryRowsSafeWithOffset(crudPro, target.table, reqJson, cfgJson, target.innerOffset, target.innerLimit);
+            allRows = allRows.concat(rows);
+        }
+        return {
+            rows: allRows,
+            total_count: totalCount,
+        };
+    }
+    /**
+     * 合并多表普通查询结果（时间分表专用，按表顺序拼接优化）
+     *
+     * 前提条件：
+     * - DESC 时 tables 已按时间倒序排列（新→旧），ASC 时已按时间正序排列（旧→新）
+     * - orderBy 为 timeColumn DESC 或 timeColumn ASC
+     *
+     * 执行流程：
+     * 1. 串行查询分表，按表顺序拼接
+     * 2. 达到 maxRows 上限后立即停止，避免查询无关表
+     *
+     * @param crudPro CrudPro 实例
+     * @param tables 分表列表（DESC: 新→旧，ASC: 旧→新）
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @param maxRows 最大返回行数（默认 10000，防止 OOM）
+     * @returns 数据列表
+     */
+    async mergeQuery(crudPro, tables, reqJson, cfgJson, maxRows = 10000) {
+        // 串行查询分表，按表顺序拼接，达到上限即停
+        let allRows = [];
+        for (const table of tables) {
+            const needMore = maxRows - allRows.length;
+            if (needMore <= 0) {
+                break;
+            }
+            const rows = await this.queryRowsSafe(crudPro, table, reqJson, cfgJson, needMore);
+            allRows = allRows.concat(rows);
+            // 达到上限后停止，不再查询后续表
+            if (allRows.length >= maxRows) {
+                allRows = allRows.slice(0, maxRows);
+                break;
+            }
+        }
+        return allRows;
+    }
+    // ============ 私有方法：分页定位 ============
+    /**
+     * 根据各表数量和分页偏移，直接定位目标表
+     *
+     * 核心优化：跳过不包含目标数据的分表，只返回需要查询的表及其表内偏移
+     *
+     * 示例：
+     * tables:  [t_order_202403, t_order_202402, t_order_202401]
+     * counts:  [5, 20, 1000]
+     * 累计:    [5, 25, 1025]
+     *
+     * offset=990, targetEnd=1000
+     * → 202403 累计5 < 990，跳过
+     * → 202402 累计25 < 990，跳过
+     * → 202401 累计1025 >= 990，命中
+     *   innerOffset = 990 - 25 = 965
+     *   innerLimit = min(1000-25, 1025-990) = 10
+     *
+     * @param tables 分表列表
+     * @param counts 各表记录数
+     * @param offset 全局偏移
+     * @param targetEnd 全局截止位置
+     */
+    locateTargetTables(tables, counts, offset, targetEnd) {
+        const result = [];
+        let accumulated = 0; // 累计已跳过的记录数
+        for (let i = 0; i < tables.length; i++) {
+            const count = counts[i];
+            // 跳过空表
+            if (count === 0)
+                continue;
+            // 当前表的累计终点
+            const tableEnd = accumulated + count;
+            // 当前表完全在目标范围之前，跳过
+            if (tableEnd <= offset) {
+                accumulated = tableEnd;
+                continue;
+            }
+            // 当前表完全在目标范围之后，停止
+            if (accumulated >= targetEnd) {
+                break;
+            }
+            // 当前表与目标范围有交集，计算表内偏移
+            const innerOffset = Math.max(0, offset - accumulated);
+            const innerEnd = Math.min(count, targetEnd - accumulated);
+            const innerLimit = innerEnd - innerOffset;
+            result.push({
+                table: tables[i],
+                innerOffset,
+                innerLimit,
+            });
+            accumulated = tableEnd;
+            // 已经取够数据，停止
+            if (accumulated >= targetEnd) {
+                break;
+            }
+        }
+        return result;
+    }
+    // ============ 私有方法：查询执行 ============
+    /**
+     * 安全查询记录数（表不存在时返回0）
+     *
+     * 支持 COUNT 缓存：历史时间分表使用缓存，当前表实时查询
+     */
+    async queryCountSafe(crudPro, table, reqJson, cfgJson) {
+        const conditionHash = (0, ShardingCountCache_1.shardingHashCondition)(reqJson.condition);
+        // 尝试从缓存获取（历史表）
+        if (this.countCache) {
+            const cachedCount = this.countCache.get(table, conditionHash);
+            if (cachedCount !== undefined) {
+                return cachedCount;
+            }
+        }
+        // 缓存未命中或当前表，执行真实查询
+        try {
+            const ctx = await this.executeCountQuery(crudPro, table, reqJson, cfgJson);
+            const count = ctx.getResModelItem('total_count') || 0;
+            // 写入缓存（仅历史表会被缓存）
+            if (this.countCache) {
+                this.countCache.set(table, conditionHash, count);
+            }
+            return count;
+        }
+        catch (e) {
+            // 表不存在或其他错误，返回0
+            return 0;
+        }
+    }
+    /**
+     * 安全查询数据行（表不存在时返回空数组）
+     */
+    async queryRowsSafe(crudPro, table, reqJson, cfgJson, limit) {
+        try {
+            const ctx = await this.executeQuery(crudPro, table, reqJson, cfgJson, limit);
+            return ctx.getResRows() || [];
+        }
+        catch (e) {
+            // 表不存在或其他错误，返回空数组
+            return [];
+        }
+    }
+    /**
+     * 安全查询数据行（支持表内偏移，表不存在时返回空数组）
+     *
+     * 用于分页定位后，直接从某张表指定偏移处取数据
+     *
+     * @param crudPro CrudPro 实例
+     * @param table 分表名
+     * @param reqJson 请求参数
+     * @param cfgJson 配置
+     * @param innerOffset 表内偏移（跳过前 N 条）
+     * @param innerLimit 取多少条
+     */
+    async queryRowsSafeWithOffset(crudPro, table, reqJson, cfgJson, innerOffset, innerLimit) {
+        try {
+            const ctx = await this.executeQueryWithOffset(crudPro, table, reqJson, cfgJson, innerOffset, innerLimit);
+            return ctx.getResRows() || [];
+        }
+        catch (e) {
+            // 表不存在或其他错误，返回空数组
+            return [];
+        }
+    }
+    /**
+     * 执行 COUNT 查询
+     */
+    async executeCountQuery(crudPro, table, reqJson, cfgJson) {
+        const tempCfg = {
+            ...cfgJson,
+            sqlTable: table,
+            sqlSimpleName: keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT,
+        };
+        return crudPro.executeCrudByCfg({ condition: reqJson.condition }, tempCfg);
+    }
+    /**
+     * 执行数据查询
+     */
+    async executeQuery(crudPro, table, reqJson, cfgJson, limit) {
+        const tempCfg = {
+            ...cfgJson,
+            sqlTable: table,
+        };
+        const queryReq = {
+            condition: reqJson.condition,
+            columns: reqJson.columns,
+            orderBy: reqJson.orderBy,
+        };
+        // 设置查询限制
+        if (limit) {
+            queryReq.pageNo = 1;
+            queryReq.pageSize = limit;
+        }
+        return crudPro.executeCrudByCfg(queryReq, tempCfg);
+    }
+    /**
+     * 执行数据查询（带表内偏移）
+     *
+     * 用于分页定位后，直接从指定偏移处取数据
+     * innerOffset=965, innerLimit=10 表示跳过该表前 965 条，取 10 条
+     */
+    async executeQueryWithOffset(crudPro, table, reqJson, cfgJson, innerOffset, innerLimit) {
+        const tempCfg = {
+            ...cfgJson,
+            sqlTable: table,
+        };
+        const queryReq = {
+            condition: reqJson.condition,
+            columns: reqJson.columns,
+            orderBy: reqJson.orderBy,
+            offset: innerOffset,
+            limit: innerLimit,
+        };
+        return crudPro.executeCrudByCfg(queryReq, tempCfg);
+    }
+}
+exports.ShardingMerger = ShardingMerger;

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

@@ -0,0 +1,69 @@
+import { IShardingConfig, IShardingRouterContext } from './ShardingConfig';
+/**
+ * 表信息提供者接口
+ * 用于获取数据库中真实存在的表
+ */
+export interface ITableInfoProvider {
+    /**
+     * 获取所有真实存在的表名
+     * @returns 表名集合
+     */
+    getExistingTables(): Promise<Set<string>>;
+}
+/**
+ * 分表路由器
+ */
+export declare class ShardingRouter {
+    /**
+     * 插入类操作专用路由（从 data 提取字段）
+     */
+    resolveForInsert(config: IShardingConfig, context: IShardingRouterContext): string;
+    /**
+     * 条件类操作专用路由（从 condition 提取字段）
+     */
+    resolveForCondition(config: IShardingConfig, context: IShardingRouterContext): string | string[];
+    /**
+     * 查询专用路由（带表存在性过滤）
+     */
+    resolveQuery(config: IShardingConfig, context: IShardingRouterContext, tableInfoProvider: ITableInfoProvider): Promise<string[]>;
+    /**
+     * 过滤出真实存在的分表
+     */
+    filterExistingTables(candidateTables: string | string[], existingTables: Set<string>): string[];
+    private validateConfig;
+    private resolveTimeForInsert;
+    private resolveTimeForCondition;
+    private resolveRangeForInsert;
+    private resolveRangeForCondition;
+    private resolveHashForInsert;
+    private resolveHashForCondition;
+    private resolveCustomForInsert;
+    private resolveCustomForCondition;
+    private isTimeSharding;
+    private getRecentExistingTablesFromAll;
+    private intersectWithCondition;
+    private intersectTablesByTimeRange;
+    /**
+     * 将分表按时间后缀降序排列（新→旧）
+     *
+     * 分表名格式为 baseTable_suffix，后缀为时间格式（如 202403、20240101），
+     * 字典序即时间序，降序即新→旧。
+     */
+    private sortTablesByTimeDesc;
+    private extractFromData;
+    private extractFromCondition;
+    private parseTimeValue;
+    private parseColumnValue;
+    private extractTimeFromData;
+    private tryExtractTimeFromCondition;
+    private extractTimeRange;
+    private extractColumnFromData;
+    private extractColumnFromCondition;
+    private generateTablesInRange;
+    private getRecentTables;
+    private getRecentCountByGranularity;
+    private calculateRangeIndex;
+    private calculateHash;
+    private simpleHash;
+    private formatTableName;
+}