jinbi-utils 1.0.19 → 1.0.21

package/src/http/apiBuilder/api-builder.ts

@@ -0,0 +1,502 @@
+/**
+ * API 请求参数构建工具
+ * @description 用于快速组装后端 JSON 格式请求参数
+ */
+
+export interface FieldCatalogItem {
+  type: 'number' | 'string' | 'date' | 'boolean' | 'json' | 'object' | 'bigint' | 'int' | 'tinyint' | 'varchar' | 'datetime';
+  label: string;
+  allowed_field: string;
+  nullable: boolean;
+  dict_field: boolean;
+  length?: number;
+}
+
+export interface FieldCatalog {
+  [key: string]: FieldCatalogItem;
+}
+
+export interface Filter {
+  field: string;
+  op: string;
+  value: any;
+}
+
+export interface NestedFilters {
+  logic: 'and' | 'or';
+  filters: (Filter | NestedFilters)[];
+}
+
+export interface OrderBy {
+  field: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface QueryParams {
+  filters: NestedFilters;
+  order_by: OrderBy[];
+  limit: number;
+  offset: number;
+  field_catalog?: FieldCatalog;
+}
+
+export interface InsertParams {
+  insert: Record<string, any>[];
+  field_catalog?: FieldCatalog;
+}
+
+export interface UpdateItem {
+  set: Record<string, any>;
+  where: Record<string, any>;
+}
+
+export interface UpdateParams {
+  update: UpdateItem[];
+  field_catalog?: FieldCatalog;
+}
+
+/**
+ * API 构建器基类
+ */
+abstract class BaseBuilder<T = any> {
+  protected fieldCatalog?: FieldCatalog;
+  protected params: T;
+
+  constructor(fieldCatalog?: FieldCatalog) {
+    this.fieldCatalog = fieldCatalog;
+    // 只有传入 fieldCatalog 时才添加到 params
+    this.params = (fieldCatalog ? { field_catalog: fieldCatalog } : {}) as T;
+  }
+
+  /**
+   * 获取构建的参数
+   */
+  build(): T {
+    return this.params;
+  }
+}
+
+/**
+ * API 构建器主类
+ */
+class ApiBuilder {
+  private fieldCatalog?: FieldCatalog;
+
+  constructor(fieldCatalog?: FieldCatalog) {
+    this.fieldCatalog = fieldCatalog;
+  }
+
+  /**
+   * 创建查询请求构建器
+   */
+  query(): QueryBuilder {
+    return new QueryBuilder(this.fieldCatalog);
+  }
+
+  /**
+   * 创建新增请求构建器
+   */
+  insert(): InsertBuilder {
+    return new InsertBuilder(this.fieldCatalog);
+  }
+
+  /**
+   * 创建更新请求构建器
+   */
+  update(): UpdateBuilder {
+    return new UpdateBuilder(this.fieldCatalog);
+  }
+
+  // 静态方法保持向后兼容
+  static query(fieldCatalog?: FieldCatalog): QueryBuilder {
+    return new QueryBuilder(fieldCatalog);
+  }
+
+  static insert(fieldCatalog?: FieldCatalog): InsertBuilder {
+    return new InsertBuilder(fieldCatalog);
+  }
+
+  static update(fieldCatalog?: FieldCatalog): UpdateBuilder {
+    return new UpdateBuilder(fieldCatalog);
+  }
+}
+
+/**
+ * 嵌套查询构建器类
+ * 用于构建嵌套的过滤条件
+ */
+class NestedQueryBuilder {
+  private parent: QueryBuilder | NestedQueryBuilder;
+  private nestedFilters: NestedFilters;
+
+  constructor(logic: 'and' | 'or', parent: QueryBuilder | NestedQueryBuilder) {
+    this.parent = parent;
+    this.nestedFilters = {
+      logic,
+      filters: []
+    };
+  }
+
+  /**
+   * 添加 WHERE 条件到嵌套查询中
+   */
+  where(field: string, op: string, value?: any): this;
+  where(field: string, value: any): this;
+  where(conditions: Record<string, any>): this;
+  where(fieldOrConditions: string | Record<string, any>, opOrValue?: any, value?: any): this {
+    // 对象形式: where({ user_id: 10086, status: 1 })
+    if (typeof fieldOrConditions === 'object') {
+      Object.entries(fieldOrConditions).forEach(([field, val]) => {
+        this.nestedFilters.filters.push({ field, op: '=', value: val });
+      });
+      return this;
+    }
+
+    // 两参数形式: where('user_id', 10086) - 默认 =
+    if (value === undefined) {
+      this.nestedFilters.filters.push({ field: fieldOrConditions, op: '=', value: opOrValue });
+      return this;
+    }
+
+    // 三参数形式: where('user_id', '=', 10086)
+    this.nestedFilters.filters.push({ field: fieldOrConditions, op: opOrValue, value });
+    return this;
+  }
+
+  /**
+   * 在嵌套查询中添加另一个嵌套组
+   */
+  group(logic: 'and' | 'or' = 'and'): NestedQueryBuilder {
+    return new NestedQueryBuilder(logic, this);
+  }
+
+  /**
+   * 结束当前嵌套组并返回父查询构建器或父嵌套构建器
+   */
+  endGroup(): QueryBuilder | NestedQueryBuilder {
+    if (this.parent instanceof NestedQueryBuilder) {
+      this.parent.addNestedFilters(this.nestedFilters);
+      return this.parent;
+    } else {
+      this.parent.whereNested(this.nestedFilters);
+      return this.parent;
+    }
+  }
+
+  /**
+   * 添加嵌套过滤条件到当前嵌套组
+   */
+  private addNestedFilters(nestedFilters: NestedFilters) {
+    this.nestedFilters.filters.push(nestedFilters);
+  }
+
+  /**
+   * 获取构建的嵌套过滤条件
+   */
+  build(): NestedFilters {
+    return this.nestedFilters;
+  }
+}
+
+/**
+ * 查询构建器
+ */
+export class QueryBuilder extends BaseBuilder<QueryParams> {
+  constructor(fieldCatalog?: FieldCatalog) {
+    super(fieldCatalog);
+    this.params = {
+      ...this.params,
+      filters: { logic: 'and', filters: [] },
+      order_by: [],
+      limit: 100,
+      offset: 0,
+    };
+  }
+
+  /**
+   * 添加 WHERE 条件（支持多种形式）
+   * @example
+   * .where('user_id', '=', 10086)
+   * .where('user_id', 10086)  // 默认 =
+   * .where({ user_id: 10086, status: 1 })  // 对象形式
+   */
+  where(field: string, op: string, value?: any): this;
+  where(field: string, value: any): this;
+  where(conditions: Record<string, any>): this;
+  where(fieldOrConditions: string | Record<string, any>, opOrValue?: any, value?: any): this {
+    // 对象形式: where({ user_id: 10086, status: 1 })
+    if (typeof fieldOrConditions === 'object') {
+      Object.entries(fieldOrConditions).forEach(([field, val]) => {
+        this.params.filters.filters.push({ field, op: '=', value: val });
+      });
+      return this;
+    }
+
+    // 两参数形式: where('user_id', 10086) - 默认 =
+    if (value === undefined) {
+      this.params.filters.filters.push({ field: fieldOrConditions, op: '=', value: opOrValue });
+      return this;
+    }
+
+    // 三参数形式: where('user_id', '=', 10086)
+    this.params.filters.filters.push({ field: fieldOrConditions, op: opOrValue, value });
+    return this;
+  }
+
+  /**
+   * 添加嵌套的 WHERE 条件
+   * @param nestedFilters 嵌套的过滤条件
+   */
+  whereNested(nestedFilters: NestedFilters): this {
+    this.params.filters.filters.push(nestedFilters);
+    return this;
+  }
+
+  /**
+   * 创建并返回一个嵌套查询构建器，用于构建复杂的嵌套条件
+   */
+  group(logic: 'and' | 'or' = 'and'): NestedQueryBuilder {
+    return new NestedQueryBuilder(logic, this);
+  }
+
+  /**
+   * OR WHERE 条件
+   */
+  orWhere(field: string, op: string, value?: any): this;
+  orWhere(field: string, value: any): this;
+  orWhere(conditions: Record<string, any>): this;
+  orWhere(fieldOrConditions: string | Record<string, any>, opOrValue?: any, value?: any): this {
+    // 创建一个新的 OR 组
+    const orGroup: NestedFilters = {
+      logic: 'or',
+      filters: []
+    };
+
+    // 对象形式: orWhere({ user_id: 10086, status: 1 })
+    if (typeof fieldOrConditions === 'object') {
+      Object.entries(fieldOrConditions).forEach(([field, val]) => {
+        orGroup.filters.push({ field, op: '=', value: val });
+      });
+    }
+    // 两参数形式: orWhere('user_id', 10086) - 默认 =
+    else if (value === undefined) {
+      orGroup.filters.push({ field: fieldOrConditions, op: '=', value: opOrValue });
+    }
+    // 三参数形式: orWhere('user_id', '=', 10086)
+    else {
+      orGroup.filters.push({ field: fieldOrConditions, op: opOrValue, value });
+    }
+
+    // 如果当前 filters 为空或者已经是 OR 逻辑，则直接添加
+    if (this.params.filters.filters.length === 0 || this.params.filters.logic === 'or') {
+      this.params.filters.filters.push(...orGroup.filters);
+      this.params.filters.logic = 'or';
+    } else {
+      // 否则将当前所有条件包装成一个 AND 组，然后与新的 OR 组一起放在顶层
+      const andGroup: NestedFilters = {
+        logic: 'and',
+        filters: [...this.params.filters.filters]
+      };
+      this.params.filters.filters = [andGroup, orGroup];
+      this.params.filters.logic = 'and';
+    }
+
+    return this;
+  }
+
+  /**
+   * WHERE IN
+   */
+  whereIn(field: string, values: any[]): this {
+    this.params.filters.filters.push({ field, op: 'in', value: values });
+    return this;
+  }
+
+  /**
+   * WHERE NOT IN
+   */
+  whereNotIn(field: string, values: any[]): this {
+    this.params.filters.filters.push({ field, op: 'not in', value: values });
+    return this;
+  }
+
+  /**
+   * WHERE LIKE
+   */
+  whereLike(field: string, value: string): this {
+    this.params.filters.filters.push({ field, op: 'like', value });
+    return this;
+  }
+
+  /**
+   * WHERE BETWEEN
+   */
+  whereBetween(field: string, min: any, max: any): this {
+    this.params.filters.filters.push({ field, op: 'between', value: [min, max] });
+    return this;
+  }
+
+  /**
+   * WHERE NULL
+   */
+  whereNull(field: string): this {
+    this.params.filters.filters.push({ field, op: 'is null', value: null });
+    return this;
+  }
+
+  /**
+   * WHERE NOT NULL
+   */
+  whereNotNull(field: string): this {
+    this.params.filters.filters.push({ field, op: 'is not null', value: null });
+    return this;
+  }
+
+  /**
+   * 设置逻辑运算符（不推荐直接使用，建议用 orWhere）
+   */
+  logic(logic: 'and' | 'or'): this {
+    this.params.filters.logic = logic;
+    return this;
+  }
+
+  /**
+   * 添加排序
+   */
+  orderBy(field: string, direction: 'asc' | 'desc' = 'asc'): this {
+    this.params.order_by.push({ field, direction });
+    return this;
+  }
+
+  /**
+   * 设置 LIMIT
+   */
+  limit(limit: number): this {
+    this.params.limit = limit;
+    return this;
+  }
+
+  /**
+   * 设置 OFFSET
+   */
+  offset(offset: number): this {
+    this.params.offset = offset;
+    return this;
+  }
+
+  /**
+   * 设置分页（便捷方法）
+   */
+  paginate(limit: number, offset: number = 0): this {
+    this.params.limit = limit;
+    this.params.offset = offset;
+    return this;
+  }
+}
+
+/**
+ * 新增构建器
+ */
+export class InsertBuilder extends BaseBuilder<InsertParams> {
+  constructor(fieldCatalog?: FieldCatalog) {
+    super(fieldCatalog);
+    this.params = {
+      ...this.params,
+      insert: [],
+    };
+  }
+
+  /**
+   * 添加一条记录
+   */
+  add(data: Record<string, any>): this {
+    this.params.insert.push(data);
+    return this;
+  }
+
+  /**
+   * 批量添加记录
+   */
+  addBatch(dataList: Record<string, any>[]): this {
+    this.params.insert.push(...dataList);
+    return this;
+  }
+}
+
+/**
+ * 更新构建器
+ */
+export class UpdateBuilder extends BaseBuilder<UpdateParams> {
+  private currentUpdate: UpdateItem | null = null;
+
+  constructor(fieldCatalog?: FieldCatalog) {
+    super(fieldCatalog);
+    this.params = {
+      ...this.params,
+      update: [],
+    };
+  }
+
+  /**
+   * 设置要更新的字段和值
+   */
+  set(fields: Record<string, any>): this {
+    this.currentUpdate = { set: fields, where: {} };
+    return this;
+  }
+
+  /**
+   * 设置更新条件（对象形式）
+   */
+  where(conditions: Record<string, any>): this;
+  /**
+   * 设置更新条件（键值对形式）
+   */
+  where(field: string, value: any): this;
+  where(fieldOrConditions: string | Record<string, any>, value?: any): this {
+    if (!this.currentUpdate) {
+      throw new Error('必须先调用 set() 方法');
+    }
+
+    if (typeof fieldOrConditions === 'object') {
+      this.currentUpdate.where = { ...this.currentUpdate.where, ...fieldOrConditions };
+    }
+    else {
+      this.currentUpdate.where[fieldOrConditions] = value;
+    }
+
+    return this;
+  }
+
+  /**
+   * 完成当前更新操作，开始下一个
+   */
+  and(): this {
+    if (this.currentUpdate) {
+      this.params.update.push(this.currentUpdate);
+      this.currentUpdate = null;
+    }
+    return this;
+  }
+
+  /**
+   * 批量添加更新操作
+   */
+  setBatch(updates: UpdateItem[]): this {
+    this.params.update.push(...updates);
+    return this;
+  }
+
+  /**
+   * 构建最终参数
+   */
+  build(): UpdateParams {
+    if (this.currentUpdate) {
+      this.params.update.push(this.currentUpdate);
+      this.currentUpdate = null;
+    }
+    return this.params;
+  }
+}
+
+export { ApiBuilder };