midway-fatcms 0.0.6 → 0.0.8

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);
+    }
+  }
+}