midway-fatcms 0.0.6 → 0.0.7

package/src/libs/crud-pro/models/RequestModel.ts

@@ -1,6 +1,7 @@
 import * as _ from 'lodash';
 import { ILimitOffset, IOrderByItem, IRequestModel, IVisitor } from '../interfaces';
 import { MixinUtils } from '../utils/MixinUtils';
+import { OrderByUtils } from '../utils/OrderByUtils';
 import { CommonException, Exceptions } from '../exceptions';
 import { DEFAULT_LIMIT } from '../defaultConfigs';
 
@@ -19,119 +20,12 @@ class RequestModel {
     Object.assign(this, req);
     this.visitor = visitor;
     this.columns = MixinUtils.parseColumns(req.columns);
-    this.orderBys = this.parseOrderBys(req.orderBy);
+    this.orderBys = OrderByUtils.parseOrderBys(req.orderBy);
     const limitOffset = this.parseOffsetList(req);
     this.limit = limitOffset.limit;
     this.offset = limitOffset.offset;
   }
 
-  /**
-   * 解析 orderBy 参数为 IOrderByItem 数组
-   *
-   * 支持的格式：
-   * 1. 字符串格式（逗号分隔多个字段）：
-   *    - 标准 SQL 格式：'created_at DESC, amount ASC'
-   *    - 简写 +/- 格式：'created_at-, amount+'（'-' 表示 DESC，'+' 或省略表示 ASC）
-   *    - 默认升序：'order_id'（无后缀时默认为 ASC）
-   *
-   * 2. 数组格式：
-   *    - 纯对象数组：[{ fieldName: 'created_at', orderType: 'desc' }]
-   *    - 混合数组1（字符串+对象）：['order_id', { fieldName: 'amount', orderType: 'asc' }]
-   *    - 混合数组2（字符串+对象）：['order_id+', { fieldName: 'amount', orderType: 'asc' }]
-   *    - 混合数组3（字符串+对象）：['order_id DESC', { fieldName: 'amount', orderType: 'asc' }]
-   *      注：数组中的字符串元素支持标准 SQL 格式和简写格式，与字符串参数格式一致。
-   *
-   * SQL 注入防护：
-   * - 所有字段名必须通过 MixinUtils.isValidFieldName() 校验
-   * - 只允许 ASC/DESC 作为排序方向
-   *
-   * @param orderByStr 排序参数，可以是字符串或数组
-   * @returns IOrderByItem[] 解析后的排序项数组
-   */
-  private parseOrderBys(orderByStr: any): IOrderByItem[] {
-    if (MixinUtils.isEmpty(orderByStr)) {
-      return [];
-    }
-
-    // 数组格式：支持字符串和对象混合
-    if (Array.isArray(orderByStr)) {
-      return orderByStr
-        .map(item => this.parseOrderByItem(item))
-        .filter((o): o is IOrderByItem => !!o);
-    }
-
-    // 字符串格式：逗号分隔多个字段
-    return orderByStr
-      .split(',')
-      .map(s => s.trim())
-      .filter(s => !!s)
-      .map(item => this.parseOrderByString(item))
-      .filter((o): o is IOrderByItem => !!o);
-  }
-
-  /**
-   * 解析单个排序项（数组元素）
-   */
-  private parseOrderByItem(item: any): IOrderByItem | null {
-    // 字符串格式：解析标准 SQL 格式或简写格式
-    if (typeof item === 'string') {
-      return this.parseOrderByString(item);
-    }
-
-    // 对象格式：提取 fieldName 和 orderType
-    const { fieldName, orderType = 'asc' } = item || {};
-    if (!fieldName) {
-      return null;
-    }
-
-    this.validateFieldName(fieldName, fieldName);
-    return { fieldName, orderType };
-  }
-
-  /**
-   * 解析字符串格式的排序项（支持标准 SQL 和简写格式）
-   */
-  private parseOrderByString(orderByStr: string): IOrderByItem | null {
-    let orderType = 'asc';
-    let fieldName = orderByStr;
-
-    // 检查是否为空格分隔的标准 SQL 格式（如 'created_at DESC'）
-    const spaceIndex = orderByStr.lastIndexOf(' ');
-    if (spaceIndex > 0) {
-      const beforeSpace = orderByStr.substring(0, spaceIndex).trim();
-      const afterSpace = orderByStr.substring(spaceIndex + 1).trim().toUpperCase();
-
-      if (afterSpace === 'ASC' || afterSpace === 'DESC') {
-        fieldName = beforeSpace;
-        orderType = afterSpace.toLowerCase() as 'asc' | 'desc';
-      } else {
-        throw new CommonException(Exceptions.REQUEST_MODEL_PARSE_ORDER_BY_FAILED, orderByStr);
-      }
-    } else if (orderByStr.endsWith('+')) {
-      // 简写格式：+ 表示升序
-      fieldName = orderByStr.slice(0, -1);
-      orderType = 'asc';
-    } else if (orderByStr.endsWith('-')) {
-      // 简写格式：- 表示降序
-      fieldName = orderByStr.slice(0, -1);
-      orderType = 'desc';
-    }
-
-    fieldName = fieldName.trim();
-    this.validateFieldName(fieldName, orderByStr);
-
-    return { fieldName, orderType };
-  }
-
-  /**
-   * SQL 注入防护：校验字段名格式
-   */
-  private validateFieldName(fieldName: string, originalValue: string): void {
-    if (MixinUtils.isEmpty(fieldName) || !MixinUtils.isValidFieldName(fieldName)) {
-      throw new CommonException(Exceptions.REQUEST_MODEL_PARSE_ORDER_BY_FAILED, originalValue);
-    }
-  }
-
   private parseOffsetList(req: IRequestModel): ILimitOffset {
     const { limit, offset, pageSize, pageNo } = req;
 

package/src/libs/crud-pro/utils/OrderByUtils.ts

@@ -0,0 +1,169 @@
+import { IOrderByItem } from '../interfaces';
+import { MixinUtils } from './MixinUtils';
+import { CommonException, Exceptions } from '../exceptions';
+
+/**
+ * OrderBy 解析工具类
+ *
+ * 提供统一的 orderBy 参数解析功能，支持多种格式：
+ * 1. 字符串格式（逗号分隔多个字段）：
+ *    - 标准 SQL 格式：'created_at DESC, amount ASC'
+ *    - 简写 +/- 格式：'created_at-, amount+'（'-' 表示 DESC，'+' 或省略表示 ASC）
+ *    - 默认升序：'order_id'（无后缀时默认为 ASC）
+ *
+ * 2. 数组格式：
+ *    - 纯对象数组：[{ fieldName: 'created_at', orderType: 'desc' }]
+ *    - 混合数组（字符串+对象）：['order_id+', { fieldName: 'amount', orderType: 'asc' }]
+ *
+ * SQL 注入防护：
+ * - 所有字段名必须通过 MixinUtils.isValidFieldName() 校验
+ * - 只允许 ASC/DESC 作为排序方向
+ */
+export class OrderByUtils {
+
+  /**
+   * 解析 orderBy 参数为 IOrderByItem 数组
+   *
+   * @param orderByStr 排序参数，可以是字符串或数组
+   * @returns IOrderByItem[] 解析后的排序项数组
+   */
+  public static parseOrderBys(orderByStr: any): IOrderByItem[] {
+    if (MixinUtils.isEmpty(orderByStr)) {
+      return [];
+    }
+
+    // 数组格式：支持字符串和对象混合
+    if (Array.isArray(orderByStr)) {
+      return orderByStr
+        .map(item => this.parseOrderByItem(item))
+        .filter((o): o is IOrderByItem => !!o);
+    }
+
+    // 字符串格式：逗号分隔多个字段
+    return orderByStr
+      .split(',')
+      .map(s => s.trim())
+      .filter(s => !!s)
+      .map(item => this.parseOrderByString(item))
+      .filter((o): o is IOrderByItem => !!o);
+  }
+
+  /**
+   * 获取第一个排序项
+   *
+   * @param orderByStr 排序参数
+   * @returns IOrderByItem | null 第一个排序项，无则返回 null
+   */
+  public static getFirstOrderBy(orderByStr: any): IOrderByItem | null {
+    const orderBys = this.parseOrderBys(orderByStr);
+    return orderBys.length > 0 ? orderBys[0] : null;
+  }
+
+  /**
+   * 判断是否为 ASC 升序排序
+   *
+   * @param orderByStr 排序参数
+   * @returns true 表示 ASC，false 表示 DESC 或无排序
+   */
+  public static isFirstOrderByAsc(orderByStr: any): boolean {
+    const first = this.getFirstOrderBy(orderByStr);
+    if (!first) {
+      return false;
+    }
+    return first.orderType.toUpperCase() === 'ASC';
+  }
+
+  /**
+   * 判断是否为 DESC 降序排序
+   *
+   * @param orderByStr 排序参数
+   * @returns true 表示 DESC，false 表示 ASC 或无排序
+   */
+  public static isFirstOrderByDesc(orderByStr: any): boolean {
+    const first = this.getFirstOrderBy(orderByStr);
+    if (!first) {
+      return false;
+    }
+    return first.orderType.toUpperCase() === 'DESC';
+  }
+
+  /**
+   * 判断排序字段是否匹配指定的时间字段
+   *
+   * 用于分表查询时校验排序字段是否为分表字段
+   *
+   * @param orderByStr 排序参数
+   * @param timeColumn 时间字段名
+   * @returns true 表示匹配，false 表示不匹配或无排序
+   */
+  public static isOrderByTimeColumn(orderByStr: any, timeColumn: string): boolean {
+    const first = this.getFirstOrderBy(orderByStr);
+    if (!first) {
+      return false;
+    }
+    return first.fieldName === timeColumn;
+  }
+
+  /**
+   * 解析单个排序项（数组元素）
+   */
+  private static parseOrderByItem(item: any): IOrderByItem | null {
+    // 字符串格式：解析标准 SQL 格式或简写格式
+    if (typeof item === 'string') {
+      return this.parseOrderByString(item);
+    }
+
+    // 对象格式：提取 fieldName 和 orderType
+    const { fieldName, orderType = 'asc' } = item || {};
+    if (!fieldName) {
+      return null;
+    }
+
+    this.validateFieldName(fieldName, fieldName);
+    return { fieldName, orderType };
+  }
+
+  /**
+   * 解析字符串格式的排序项（支持标准 SQL 和简写格式）
+   */
+  private static parseOrderByString(orderByStr: string): IOrderByItem | null {
+    let orderType = 'asc';
+    let fieldName = orderByStr;
+
+    // 检查是否为空格分隔的标准 SQL 格式（如 'created_at DESC'）
+    const spaceIndex = orderByStr.lastIndexOf(' ');
+    if (spaceIndex > 0) {
+      const beforeSpace = orderByStr.substring(0, spaceIndex).trim();
+      const afterSpace = orderByStr.substring(spaceIndex + 1).trim().toUpperCase();
+
+      if (afterSpace === 'ASC' || afterSpace === 'DESC') {
+        fieldName = beforeSpace;
+        orderType = afterSpace.toLowerCase() as 'asc' | 'desc';
+      } else {
+        throw new CommonException(Exceptions.REQUEST_MODEL_PARSE_ORDER_BY_FAILED, orderByStr);
+      }
+    } else if (orderByStr.endsWith('+')) {
+      // 简写格式：+ 表示升序
+      fieldName = orderByStr.slice(0, -1);
+      orderType = 'asc';
+    } else if (orderByStr.endsWith('-')) {
+      // 简写格式：- 表示降序
+      fieldName = orderByStr.slice(0, -1);
+      orderType = 'desc';
+    }
+
+    fieldName = fieldName.trim();
+    this.validateFieldName(fieldName, orderByStr);
+
+    return { fieldName, orderType };
+  }
+
+  /**
+   * SQL 注入防护：校验字段名格式
+   */
+  private static validateFieldName(fieldName: string, originalValue: string): void {
+    if (MixinUtils.isEmpty(fieldName) || !MixinUtils.isValidFieldName(fieldName)) {
+      throw new CommonException(Exceptions.REQUEST_MODEL_PARSE_ORDER_BY_FAILED, originalValue);
+    }
+  }
+}

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

@@ -1,5 +1,6 @@
 import { CrudPro } from '@/libs/crud-pro/CrudPro';
 import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
+import { OrderByUtils } from '@/libs/crud-pro/utils/OrderByUtils';
 import { ExecuteContext } from '@/libs/crud-pro/models/ExecuteContext';
 import { KeysOfSimpleSQL } from '@/libs/crud-pro/models/keys';
 import { ShardingType, IShardingConfig, IShardingRouterContext } from './ShardingConfig';
@@ -30,10 +31,10 @@ export interface IShardingSmartBatchInsertResult {
 
 /**
  * 分表 CRUD 操作封装器
- * 
+ *
  * 在 CrudPro 之上封装分表功能，不修改 CrudPro 内部代码。
  * 提供透明的分表路由和多表查询结果合并能力。
- * 
+ *
  * 支持的分表策略：
  * - YEAR: 按年分表，如 order_2024, order_2025
  * - MONTH: 按月分表，如 order_202401, order_202402
@@ -41,7 +42,7 @@ export interface IShardingSmartBatchInsertResult {
  * - RANGE: 按范围分表，如 user_0 ~ user_99
  * - HASH: 按哈希分表，如 order_01 ~ order_16
  * - CUSTOM: 自定义分表规则
- * 
+ *
  * @example
  * // 按月分表
  * const sharding = new ShardingCrudPro(crudPro, {
@@ -49,10 +50,10 @@ export interface IShardingSmartBatchInsertResult {
  *   baseTable: 't_order',
  *   timeColumn: 'created_at',
  * });
- * 
+ *
  * // 插入数据（自动路由到正确分表）
  * await sharding.insert({ data: { order_id: '001', amount: 100, created_at: '2024-03-15' } });
- * 
+ *
  * // 分页查询（自动合并多表结果）
  * const result = await sharding.queryPage({
  *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
@@ -100,10 +101,10 @@ export class ShardingCrudPro {
 
   /**
    * 设置基础配置（会应用到所有操作）
-   * 
+   *
    * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
    * @returns this，支持链式调用
-   * 
+   *
    * @example
    * sharding.setBaseCfg({
    *   sqlDatabase: 'mydb',
@@ -156,18 +157,18 @@ export class ShardingCrudPro {
 
   /**
    * 批量插入数据（支持跨分表）
-   * 
+   *
    * 自动将数据按分表分组，并行插入到对应的分表。
-   * 
+   *
    * @param reqJson 请求参数，data 为要插入的数据数组
    * @returns 批量插入结果
-   * 
+   *
    * 执行流程：
    * 1. 遍历所有数据，根据分表字段计算目标分表
    * 2. 将数据按分表分组
    * 3. 并行执行各分表的批量插入
    * 4. 汇总结果返回
-   * 
+   *
    * @example
    * // 数据分布在不同月份的分表
    * const result = await sharding.batchInsert({
@@ -178,7 +179,7 @@ export class ShardingCrudPro {
    *     { order_id: '004', amount: 300, created_at: '2024-03-05' },  // -> t_order_202403
    *   ],
    * });
-   * 
+   *
    * console.log(result.totalAffected);    // 4
    * console.log(result.tableCount);       // 3
    * console.log(result.tableResults);
@@ -256,12 +257,12 @@ export class ShardingCrudPro {
 
   /**
    * 更新数据
-   * 
+   *
    * 根据条件中的分表字段自动路由到目标分表。
-   * 
+   *
    * @param reqJson 请求参数，condition 为更新条件，data 为更新数据
    * @returns 执行上下文
-   * 
+   *
    * @example
    * await sharding.update({
    *   condition: { order_id: 'ORD001', created_at: '2024-03-15' },
@@ -275,9 +276,9 @@ export class ShardingCrudPro {
 
   /**
    * 删除数据
-   * 
+   *
    * 根据条件中的分表字段自动路由到目标分表。
-   * 
+   *
    * @param reqJson 请求参数，condition 为删除条件
    * @returns 执行上下文
    */
@@ -288,9 +289,9 @@ export class ShardingCrudPro {
 
   /**
    * 插入或更新（存在则更新，不存在则插入）
-   * 
+   *
    * 路由逻辑：根据 condition 路由（先查询是否存在）
-   * 
+   *
    * @param reqJson 请求参数
    * @returns 执行上下文
    */
@@ -301,9 +302,9 @@ export class ShardingCrudPro {
 
   /**
    * 插入或更新（ON DUPLICATE KEY UPDATE）
-   * 
+   *
    * 路由逻辑：根据 condition 路由（先查询是否存在）
-   * 
+   *
    * @param reqJson 请求参数
    * @returns 执行上下文
    */
@@ -316,13 +317,13 @@ export class ShardingCrudPro {
 
   /**
    * 查询单条记录
-   * 
+   *
    * 如果能根据条件确定单一分表，则查询单表；
    * 否则按顺序查询各分表，返回第一条匹配记录。
-   * 
+   *
    * @param reqJson 请求参数，condition 为查询条件
    * @returns 单条记录，未找到返回 null
-   * 
+   *
    * @example
    * const order = await sharding.queryOne({
    *   condition: { order_id: 'ORD001' },
@@ -443,9 +444,9 @@ export class ShardingCrudPro {
 
   /**
    * 查询记录总数
-   * 
+   *
    * 如果涉及多个分表，会并行查询各分表并汇总。
-   * 
+   *
    * @param reqJson 请求参数
    * @returns 记录总数
    */
@@ -471,9 +472,9 @@ export class ShardingCrudPro {
 
   /**
    * 判断记录是否存在
-   * 
+   *
    * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
-   * 
+   *
    * @param reqJson 请求参数
    * @returns 是否存在
    */
@@ -680,12 +681,12 @@ export class ShardingCrudPro {
 
   /**
    * 创建分表（如果需要）
-   * 
+   *
    * 根据配置检查分表是否存在：
    * - 如果分表已存在，直接返回
    * - 如果分表不存在且 autoCreateTable=true，自动创建
    * - 如果分表不存在且 autoCreateTable=false，抛出异常
-   * 
+   *
    * @param tableName 目标分表名
    */
   private async createShardingTableIfNeeded(tableName: string): Promise<void> {
@@ -743,8 +744,6 @@ export class ShardingCrudPro {
     }
 
     const orderBy = reqJson.orderBy;
-    const expectedDesc = `${timeColumn} DESC`;
-    const expectedAsc = `${timeColumn} ASC`;
 
     // 1. 必须传 orderBy
     if (!orderBy) {
@@ -754,36 +753,29 @@ export class ShardingCrudPro {
       );
     }
 
-    // 2. 校验 orderBy 格式（直接字符串比较，避免正则转义问题）
-    if (typeof orderBy === 'string') {
-      const upper = orderBy.trim().toUpperCase();
-      if (upper !== expectedDesc.toUpperCase() && upper !== expectedAsc.toUpperCase()) {
-        throw new Error(
-          `[ShardingCrudPro] orderBy 参数必须是 '${timeColumn} DESC' 或 '${timeColumn} ASC'，` +
-          `当前值: '${orderBy}'`
-        );
-      }
-    } else if (Array.isArray(orderBy)) {
-      // 数组格式：首个排序字段必须是 timeColumn DESC/ASC，允许附加次级排序
-      if (orderBy.length === 0) {
-        throw new Error(
-          `[ShardingCrudPro] orderBy 数组不能为空，首个排序字段必须为 '${timeColumn} DESC' 或 '${timeColumn} ASC'`
-        );
-      }
-      const firstItem = orderBy[0];
-      const firstItemStr = typeof firstItem === 'string'
-        ? firstItem
-        : `${firstItem.fieldName} ${firstItem.orderType || 'ASC'}`;
-      const upper = firstItemStr.trim().toUpperCase();
-      if (upper !== expectedDesc.toUpperCase() && upper !== expectedAsc.toUpperCase()) {
-        throw new Error(
-          `[ShardingCrudPro] orderBy 数组首个排序字段必须为 '${timeColumn} DESC' 或 '${timeColumn} ASC'，` +
-          `当前值: '${firstItemStr}'`
-        );
-      }
-    } else {
+    // 2. 使用工具类解析并校验首个排序字段是否为 timeColumn
+    const firstOrderBy = OrderByUtils.getFirstOrderBy(orderBy);
+
+    if (!firstOrderBy) {
       throw new Error(
-        `[ShardingCrudPro] orderBy 参数格式错误，期望字符串或数组。`
+        `[ShardingCrudPro] orderBy 参数格式错误，无法解析。` +
+        `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`
+      );
+    }
+
+    if (firstOrderBy.fieldName !== timeColumn) {
+      throw new Error(
+        `[ShardingCrudPro] orderBy 首个排序字段必须为 '${timeColumn}'，` +
+        `当前值: '${firstOrderBy.fieldName}'`
+      );
+    }
+
+    // 校验排序方向是否为 ASC 或 DESC
+    const orderType = firstOrderBy.orderType.toUpperCase();
+    if (orderType !== 'ASC' && orderType !== 'DESC') {
+      throw new Error(
+        `[ShardingCrudPro] orderBy 排序方向必须是 'ASC' 或 'DESC'，` +
+        `当前值: '${firstOrderBy.orderType}'`
       );
     }
   }
@@ -797,20 +789,7 @@ export class ShardingCrudPro {
    * @returns true 表示 ASC，false 表示 DESC
    */
   private isAscOrderBy(reqJson: IRequestModel): boolean {
-    const orderBy = reqJson.orderBy;
-    if (!orderBy) return false;
-
-    if (typeof orderBy === 'string') {
-      return orderBy.trim().toUpperCase().endsWith('ASC');
-    }
-    if (Array.isArray(orderBy) && orderBy.length > 0) {
-      const firstItem = orderBy[0];
-      const firstItemStr = typeof firstItem === 'string'
-        ? firstItem
-        : `${firstItem.fieldName} ${firstItem.orderType || 'ASC'}`;
-      return firstItemStr.trim().toUpperCase().endsWith('ASC');
-    }
-    return false;
+    return OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
   }
 
   /**
@@ -853,4 +832,4 @@ export class ShardingCrudPro {
     // 委托给 ShardingRouter 处理查询路由
     return this.router.resolveQuery(this.config, context, tableInfoProvider);
   }
-}
+}

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

@@ -102,8 +102,8 @@ export class ShardingMerger {
    * - orderBy 为 timeColumn DESC 或 timeColumn ASC
    *
    * 执行流程：
-   * 1. 并行查询所有分表
-   * 2. 按表顺序拼接结果（无需排序）
+   * 1. 串行查询分表，按表顺序拼接
+   * 2. 达到 maxRows 上限后立即停止，避免查询无关表
    *
    * @param crudPro CrudPro 实例
    * @param tables 分表列表（DESC: 新→旧，ASC: 旧→新）
@@ -119,17 +119,19 @@ export class ShardingMerger {
     cfgJson: IRequestCfgModel,
     maxRows: number = 10000
   ): Promise<any[]> {
-    // 并行查询所有分表
-    const dataPromises = tables.map(table =>
-      this.queryRowsSafe(crudPro, table, reqJson, cfgJson, maxRows)
-    );
-    const dataResults = await Promise.all(dataPromises);
-
-    // 按表顺序拼接（表顺序即数据顺序，无需排序）
+    // 串行查询分表，按表顺序拼接，达到上限即停
     let allRows: any[] = [];
-    for (let i = 0; i < dataResults.length; i++) {
-      allRows = allRows.concat(dataResults[i]);
-      // 达到上限后停止
+
+    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;