midway-fatcms 0.0.4 → 0.0.6

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

@@ -0,0 +1,218 @@
+/**
+ * 分表配置模型
+ *
+ * 支持多种分表策略：
+ * - YEAR: 按年分表，如 order_2024, order_2025
+ * - MONTH: 按月分表，如 order_202401, order_202402
+ * - DAY: 按日分表，如 order_20240101
+ * - RANGE: 按范围分表，如 user_0 ~ user_99
+ * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - CUSTOM: 自定义分表规则
+ */
+/**
+ * 分表类型
+ */
+export declare enum ShardingType {
+    /** 按年分表：table_2024, table_2025 */
+    YEAR = "year",
+    /** 按月分表：table_202401, table_202402 */
+    MONTH = "month",
+    /** 按日分表：table_20240101 */
+    DAY = "day",
+    /** 按范围分表：table_0 ~ table_99 */
+    RANGE = "range",
+    /** 按哈希分表：table_01 ~ table_16 */
+    HASH = "hash",
+    /** 自定义分表规则 */
+    CUSTOM = "custom"
+}
+/**
+ * 分表配置接口
+ */
+export interface IShardingConfig {
+    /**
+     * 分表类型
+     */
+    type: ShardingType;
+    /**
+     * 基础表名
+     * 例如：t_order
+     */
+    baseTable: string;
+    /**
+     * 分表数量
+     * 用于 RANGE 和 HASH 类型
+     * 默认值：RANGE 为 10，HASH 为 16
+     */
+    tableCount?: number;
+    /**
+     * 分表字段
+     * 用于 RANGE 和 HASH 类型，根据字段值计算分表
+     * 例如：user_id, order_id
+     */
+    shardingColumn?: string;
+    /**
+     * 时间字段
+     * 用于时间分表类型（YEAR/MONTH/DAY），使用时间分表时必填
+     */
+    timeColumn?: string;
+    /**
+     * 自定义分表路由函数
+     * 用于 CUSTOM 类型
+     * @param context 分表路由上下文
+     * @returns 单个表名或表名数组
+     */
+    customRouter?: IShardingRouterFunc;
+    /**
+     * 分表后缀格式化函数
+     * 可自定义后缀格式
+     * @param suffix 原始后缀
+     * @returns 格式化后的后缀
+     */
+    suffixFormatter?: (suffix: string) => string;
+    /**
+     * 最近分表数量
+     *
+     * 当查询无法确定具体时间范围时，返回最近N个分表。
+     * 适用于时间分表类型（YEAR/MONTH/DAY）。
+     *
+     * 默认值：
+     * - YEAR: 3（最近3年）
+     * - MONTH: 12（最近12个月）
+     * - DAY: 7（最近7天）
+     *
+     * @example
+     * // 查询最近6个月的订单
+     * const config: IShardingConfig = {
+     *   type: ShardingType.MONTH,
+     *   baseTable: 't_order',
+     *   recentTableCount: 6,
+     * };
+     */
+    recentTableCount?: number;
+    /**
+     * 是否自动创建分表
+     *
+     * 当插入/更新数据时分表不存在，是否自动根据基表结构创建分表。
+     * 默认值：false（不自动创建，抛出异常）
+     *
+     * @example
+     * const config: IShardingConfig = {
+     *   type: ShardingType.MONTH,
+     *   baseTable: 't_order',
+     *   timeColumn: 'created_at',
+     *   autoCreateTable: true,  // 自动创建分表
+     * };
+     */
+    autoCreateTable?: boolean;
+    /**
+   * 分表创建选项
+   *
+     * 当 autoCreateTable 为 true 时，传递给 ShardingTableCreator 的选项。
+     *
+     * @example
+     * const config: IShardingConfig = {
+     *   type: ShardingType.MONTH,
+     *   baseTable: 't_order',
+     *   autoCreateTable: true,
+     *   tableCreateOptions: {
+     *     copyIndexes: true,
+     *     tableOptions: 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4',
+     *   },
+     * };
+     */
+    tableCreateOptions?: IShardingTableCreateOptions;
+    /**
+     * COUNT 查询缓存配置
+     *
+     * 仅对时间分表（YEAR/MONTH/DAY）生效。历史表启用缓存，当前表实时查询。
+     *
+     * @example
+     * const config: IShardingConfig = {
+     *   type: ShardingType.MONTH,
+     *   baseTable: 't_order',
+     *   timeColumn: 'created_at',
+     *   countCache: {
+     *     ttlSeconds: 300,  // 缓存5分钟
+     *     maxSize: 1000,    // 最多缓存1000个表的COUNT
+     *   },
+     * };
+     */
+    countCache?: IShardingCountCacheConfig;
+}
+/**
+ * COUNT 缓存配置
+ */
+export interface IShardingCountCacheConfig {
+    /**
+     * 缓存有效期（秒）
+     * 默认值：300（5分钟）
+     */
+    ttlSeconds?: number;
+    /**
+     * 缓存最大条目数（LRU淘汰）
+     * 默认值：1000
+     */
+    maxSize?: number;
+}
+/**
+ * 分表创建选项
+ */
+export interface IShardingTableCreateOptions {
+    /** 是否复制索引（默认 false） */
+    copyIndexes?: boolean;
+    /** 是否忽略外键约束（默认 true） */
+    ignoreForeignKeys?: boolean;
+    /** 表选项（如 MySQL 的 ENGINE、CHARSET） */
+    tableOptions?: string;
+}
+/**
+ * 分表创建结果
+ */
+export interface IShardingTableCreateResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 表名 */
+    tableName: string;
+    /** 建表 SQL（用于调试） */
+    createSql?: string;
+    /** 错误信息 */
+    error?: Error;
+}
+/**
+ * 分表路由函数类型
+ * @param context 分表路由上下文
+ * @returns 单个表名或表名数组（查询时可能返回多个）
+ */
+export declare type IShardingRouterFunc = (context: IShardingRouterContext) => string | string[];
+/**
+ * 分表路由上下文
+ */
+export interface IShardingRouterContext {
+    /**
+     * 分表配置
+     */
+    config: IShardingConfig;
+    /**
+     * 操作数据
+     * 用于 INSERT 操作时确定分表（resolveForInsert）
+     */
+    data?: Record<string, any>;
+    /**
+     * 查询条件
+     * 用于 UPDATE/DELETE/QUERY 等操作时确定分表（resolveForCondition）
+     */
+    condition?: Record<string, any>;
+    /**
+     * SQL 简单名称
+     * 用于判断具体的查询类型
+     */
+    sqlSimpleName?: string;
+}
+/**
+ * 时间范围
+ */
+export interface IShardingTimeRange {
+    start: Date;
+    end: Date;
+}

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

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * 分表配置模型
+ *
+ * 支持多种分表策略：
+ * - YEAR: 按年分表，如 order_2024, order_2025
+ * - MONTH: 按月分表，如 order_202401, order_202402
+ * - DAY: 按日分表，如 order_20240101
+ * - RANGE: 按范围分表，如 user_0 ~ user_99
+ * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - CUSTOM: 自定义分表规则
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingType = void 0;
+/**
+ * 分表类型
+ */
+var ShardingType;
+(function (ShardingType) {
+    /** 按年分表：table_2024, table_2025 */
+    ShardingType["YEAR"] = "year";
+    /** 按月分表：table_202401, table_202402 */
+    ShardingType["MONTH"] = "month";
+    /** 按日分表：table_20240101 */
+    ShardingType["DAY"] = "day";
+    /** 按范围分表：table_0 ~ table_99 */
+    ShardingType["RANGE"] = "range";
+    /** 按哈希分表：table_01 ~ table_16 */
+    ShardingType["HASH"] = "hash";
+    /** 自定义分表规则 */
+    ShardingType["CUSTOM"] = "custom";
+})(ShardingType = exports.ShardingType || (exports.ShardingType = {}));

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

@@ -0,0 +1,69 @@
+import { ShardingType } from './ShardingConfig';
+/**
+ * COUNT 查询缓存管理器
+ *
+ * 特性：
+ * 1. 仅对历史时间分表启用缓存，当前时间分表实时查询
+ * 2. 基于 LRU 算法淘汰旧缓存
+ * 3. 支持 TTL（生存时间）自动过期
+ * 4. 缓存键包含表名和查询条件哈希
+ */
+export declare class ShardingCountCache {
+    private readonly cache;
+    private readonly ttlMs;
+    private readonly maxSize;
+    private readonly shardingType;
+    private readonly baseTable;
+    constructor(shardingType: ShardingType | undefined, baseTable: string, ttlSeconds?: number, maxSize?: number);
+    /**
+     * 获取缓存的 COUNT 值
+     *
+     * @param tableName 表名
+     * @param conditionHash 查询条件哈希（用于区分不同条件的 COUNT）
+     * @returns 缓存值（未命中或过期返回 undefined）
+     */
+    get(tableName: string, conditionHash: string): number | undefined;
+    /**
+     * 设置 COUNT 缓存
+     *
+     * @param tableName 表名
+     * @param conditionHash 查询条件哈希
+     * @param count COUNT 值
+     */
+    set(tableName: string, conditionHash: string, count: number): void;
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        ttlSeconds: number;
+    };
+    /**
+     * 判断是否为时间分表类型
+     */
+    private isTimeSharding;
+    /**
+     * 判断是否为当前时间周期的表
+     *
+     * 当前表不启用缓存，确保数据实时性
+     */
+    private checkIsCurrentTable;
+    /**
+     * 构建缓存键
+     */
+    private buildCacheKey;
+    /**
+     * LRU 淘汰：当缓存满时淘汰最久未使用的条目
+     */
+    private evictIfNeeded;
+}
+/**
+ * 计算查询条件的简单哈希
+ * 用于生成缓存键
+ */
+export declare function shardingHashCondition(condition: Record<string, any> | undefined): string;

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

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shardingHashCondition = exports.ShardingCountCache = void 0;
+const ShardingConfig_1 = require("./ShardingConfig");
+const ShardingUtils_1 = require("./ShardingUtils");
+/**
+ * COUNT 查询缓存管理器
+ *
+ * 特性：
+ * 1. 仅对历史时间分表启用缓存，当前时间分表实时查询
+ * 2. 基于 LRU 算法淘汰旧缓存
+ * 3. 支持 TTL（生存时间）自动过期
+ * 4. 缓存键包含表名和查询条件哈希
+ */
+class ShardingCountCache {
+    constructor(shardingType, baseTable, ttlSeconds = 300, maxSize = 1000) {
+        this.cache = new Map();
+        this.shardingType = shardingType;
+        this.baseTable = baseTable;
+        this.ttlMs = ttlSeconds * 1000;
+        this.maxSize = maxSize;
+    }
+    /**
+     * 获取缓存的 COUNT 值
+     *
+     * @param tableName 表名
+     * @param conditionHash 查询条件哈希（用于区分不同条件的 COUNT）
+     * @returns 缓存值（未命中或过期返回 undefined）
+     */
+    get(tableName, conditionHash) {
+        // 非时间分表不启用缓存
+        if (!this.isTimeSharding()) {
+            return undefined;
+        }
+        // 当前表不启用缓存
+        if (this.checkIsCurrentTable(tableName)) {
+            return undefined;
+        }
+        const key = this.buildCacheKey(tableName, conditionHash);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // 检查是否过期
+        const now = Date.now();
+        if (now - entry.cachedAt > this.ttlMs) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // 更新访问顺序（LRU：移到末尾表示最近使用）
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.count;
+    }
+    /**
+     * 设置 COUNT 缓存
+     *
+     * @param tableName 表名
+     * @param conditionHash 查询条件哈希
+     * @param count COUNT 值
+     */
+    set(tableName, conditionHash, count) {
+        // 非时间分表不启用缓存
+        if (!this.isTimeSharding()) {
+            return;
+        }
+        // 当前表不缓存
+        if (this.checkIsCurrentTable(tableName)) {
+            return;
+        }
+        // 执行 LRU 淘汰
+        this.evictIfNeeded();
+        const key = this.buildCacheKey(tableName, conditionHash);
+        const entry = {
+            count,
+            cachedAt: Date.now(),
+            key,
+        };
+        this.cache.set(key, entry);
+    }
+    /**
+     * 清空缓存
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * 获取缓存统计信息
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlSeconds: this.ttlMs / 1000,
+        };
+    }
+    /**
+     * 判断是否为时间分表类型
+     */
+    isTimeSharding() {
+        return (this.shardingType === ShardingConfig_1.ShardingType.YEAR ||
+            this.shardingType === ShardingConfig_1.ShardingType.MONTH ||
+            this.shardingType === ShardingConfig_1.ShardingType.DAY);
+    }
+    /**
+     * 判断是否为当前时间周期的表
+     *
+     * 当前表不启用缓存，确保数据实时性
+     */
+    checkIsCurrentTable(tableName) {
+        return (0, ShardingUtils_1.isCurrentTable)(tableName, this.baseTable, this.shardingType);
+    }
+    /**
+     * 构建缓存键
+     */
+    buildCacheKey(tableName, conditionHash) {
+        return `${tableName}#${conditionHash}`;
+    }
+    /**
+     * LRU 淘汰：当缓存满时淘汰最久未使用的条目
+     */
+    evictIfNeeded() {
+        if (this.cache.size >= this.maxSize) {
+            // 删除最久未使用的（Map 的第一个元素）
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+    }
+}
+exports.ShardingCountCache = ShardingCountCache;
+/**
+ * 计算查询条件的简单哈希
+ * 用于生成缓存键
+ */
+function shardingHashCondition(condition) {
+    if (!condition || Object.keys(condition).length === 0) {
+        return '*';
+    }
+    try {
+        // 排序键后序列化，确保相同条件生成相同哈希
+        const sortedKeys = Object.keys(condition).sort();
+        const sortedObj = {};
+        for (const key of sortedKeys) {
+            sortedObj[key] = condition[key];
+        }
+        const str = JSON.stringify(sortedObj);
+        // 简单的哈希算法（djb2）
+        let hash = 5381;
+        for (let i = 0; i < str.length; i++) {
+            hash = ((hash << 5) + hash) + str.charCodeAt(i);
+        }
+        return (hash >>> 0).toString(36); // 转为无符号整数，再用36进制压缩
+    }
+    catch (_a) {
+        return '*';
+    }
+}
+exports.shardingHashCondition = shardingHashCondition;