midway-fatcms 0.0.5 → 0.0.7

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

@@ -3,6 +3,85 @@ import { CommonException, Exceptions } from '../exceptions';
 //  至少需要2个字符
 const FIELD_NAME_REG_EXP = /^[a-zA-Z][0-9a-zA-Z_]+$/;
 
+// ===================== 雪花ID =====================
+let snowflakeSeq = 0;
+let snowflakeLastTs = -1;
+
+/**
+ * 生成雪花ID（64位整数，JS 中以 string 返回）
+ * 结构：1位符号 + 41位时间戳(ms) + 10位机器ID + 12位序列号
+ * - 时间戳：相对于 2024-01-01 00:00:00 的毫秒偏移，可用约 69 年
+ * - 机器ID：0-1023，优先取参数 > 环境变量 SNOWFLAKE_MACHINE_ID > process.pid 低10位
+ * - 序列号：0-4095，同一毫秒内自增
+ *
+ * @param machineId 机器ID（0-1023），不传则依次从环境变量 SNOWFLAKE_MACHINE_ID、process.pid 获取
+ * @returns 雪花ID字符串
+ */
+function generateSnowflakeId(machineId?: number): string {
+  const EPOCH = 1704067200000; // 2024-01-01 00:00:00 UTC
+
+  let mid = machineId;
+  if (mid === undefined || mid === null) {
+    // 优先从环境变量获取，适配多实例部署场景
+    const envMid = typeof process !== 'undefined' && process.env && process.env.SNOWFLAKE_MACHINE_ID
+      ? parseInt(process.env.SNOWFLAKE_MACHINE_ID, 10)
+      : NaN;
+    mid = !isNaN(envMid) ? envMid : (typeof process !== 'undefined' && process.pid ? process.pid & 0x3ff : 0);
+  }
+  mid = mid & 0x3ff; // 确保在 0-1023 范围
+
+  let now = Date.now();
+  let ts = now - EPOCH;
+
+  if (ts === snowflakeLastTs) {
+    snowflakeSeq = (snowflakeSeq + 1) & 0xfff; // 0-4095 循环
+    if (snowflakeSeq === 0) {
+      // 本毫秒序列号耗尽，等待下一毫秒
+      while (now <= Date.now()) {
+        now = Date.now();
+      }
+      ts = now - EPOCH;
+    }
+  } else {
+    snowflakeSeq = 0;
+  }
+
+  snowflakeLastTs = ts;
+
+  // 雪花ID超过JS安全整数范围(2^53)，不能用Number位运算，采用字符串拼接
+  const tsPart = ts * 4194304; // ts << 22，等价于 ts * 2^22
+  const midPart = mid * 4096;  // mid << 12，等价于 mid * 2^12
+  return '' + (tsPart + midPart + snowflakeSeq);
+}
+
+
+
+  /**
+   * 生成 UUID v4 字符串（纯随机，无外部依赖）
+   * 格式：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx，其中 y 为 8/9/a/b 之一
+   * @returns 符合 RFC 4122 v4 规范的 UUID 字符串
+   */
+  function uuid(): string {
+    // crypto.getRandomValues 在 Node.js >= 11 和现代浏览器中可用
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      const bytes = new Uint8Array(16);
+      crypto.getRandomValues(bytes);
+      // 版本位：第6字节高4位设为 0100 (v4)
+      bytes[6] = (bytes[6] & 0x0f) | 0x40;
+      // 变体位：第8字节高2位设为 10
+      bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+      return hex.slice(0, 8) + '-' + hex.slice(8, 12) + '-' + hex.slice(12, 16) + '-' + hex.slice(16, 20) + '-' + hex.slice(20);
+    }
+    // 降级方案：Math.random
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+      const r = Math.random() * 16 | 0;
+      const v = c === 'x' ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+
+
 const MixinUtils = {
   isNil(obj: any): boolean {
     return typeof obj === 'undefined' || obj === null;
@@ -284,7 +363,24 @@ const MixinUtils = {
   },
   sleepMs(ms: number): Promise<any> {
     return new Promise(resolve => setTimeout(resolve, ms));
-  }
+  },
+
+  /**
+   * 生成 UUID v4 字符串（纯随机，无外部依赖）
+   * 格式：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx，其中 y 为 8/9/a/b 之一
+   * @returns 符合 RFC 4122 v4 规范的 UUID 字符串
+   */
+  uuid: uuid,
+
+  /**
+   * 生成雪花ID（64位整数，以字符串返回）
+   * 结构：1位符号 + 41位时间戳(ms) + 10位机器ID + 12位序列号
+   * 同一毫秒内可生成 4096 个不重复ID，单机每秒可生成约 400 万个
+   *
+   * @param machineId 机器ID（0-1023），不传则依次从环境变量 SNOWFLAKE_MACHINE_ID、process.pid 获取
+   * @returns 雪花ID字符串
+   */
+  generateSnowflakeId: generateSnowflakeId,
 };
 
 export { MixinUtils };

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-pro/utils/ValidateUtils.ts

@@ -50,7 +50,7 @@ const validatorUtils = {
   },
 
   isMomentValid(itemCfg: string, itemValue: any): boolean {
-    const cfgPart = itemCfg.substring(KeysOfValidators.ENUM.length).trim();
+    const cfgPart = itemCfg.substring(KeysOfValidators.MOMENT.length).trim();
     return moment(itemValue, cfgPart, true).isValid();
   },