Tự tay xây 'Thợ Xây SQL' xịn xò với TypeScript: Nâng tầm code database của bạn!

Lê Lân

01/07/2025

Xây Dựng Query Builder Tùy Chỉnh Cho SQLite Bằng TypeScript: Hành Trình Và Bài Học Từ Ứng Dụng Từ Điển Gốc Ả Rập

Mở Đầu

Là một lập trình viên, bạn thường xuyên phải viết lại những câu truy vấn SQL lặp đi lặp lại, đặc biệt khi làm việc với cơ sở dữ liệu client-side như SQLite trên các ứng dụng di động hoặc desktop.

SQL thô tuy cho phép kiểm soát tối đa nhưng nhanh chóng trở nên phức tạp, dễ sai sót và khó bảo trì khi ứng dụng mở rộng. Trong quá trình phát triển ứng dụng Từ Điển Gốc Ả Rập, tôi đã gặp phải chính thử thách này. Ứng dụng cần rất nhiều câu truy vấn động để tìm kiếm các gốc từ, dẫn xuất và quản lý dữ liệu từ điển. Thay vì rải rác các chuỗi SQL thô khắp nơi, tôi đã quyết định xây dựng một query builder tùy chỉnh dành riêng cho SQLite bằng TypeScript. Qua bài viết này, tôi muốn chia sẻ những bài học, kiến trúc và kinh nghiệm từ dự án này.

Tại Sao Cần Xây Dựng Query Builder Tùy Chỉnh?

Tối ưu cho SQLite: Tận dụng đặc thù của SQLite mà không bị cồng kềnh bởi các thư viện tổng quát.

Nhẹ và hiệu quả: Không phải kéo theo các phụ thuộc lớn có thể ảnh hưởng đến kích thước gói và hiệu năng, đặc biệt trên mobile.

An toàn kiểu với TypeScript: Kiểm tra lỗi sớm qua kiểu dữ liệu tĩnh (column names, operators, outputs).

Toàn quyền kiểm soát SQL: Dễ dàng debug và tối ưu hiệu năng nhờ hiểu rõ câu lệnh sinh ra.

Đào sâu kiến thức: Học hỏi sâu hơn về tương tác cơ sở dữ liệu và thiết kế phần mềm.

Một giải pháp tùy chỉnh phù hợp sẽ không chỉ giúp tăng hiệu quả phát triển mà còn nâng cao chất lượng sản phẩm.

Kiến Trúc Cốt Lõi: API Chuỗi và An Toàn Kiểu

Mục tiêu là tạo ra một API mượt mà, dễ viết như các ORM nổi tiếng, nhưng vẫn đảm bảo tính an toàn kiểu nghiêm ngặt. Cấu trúc bao gồm lớp cha BaseQueryBuilder và các lớp con chuyên biệt cho SELECT, INSERT, UPDATE, DELETE.

1. Định Nghĩa Các Khối Xây Dựng (Types)

TypeScript được sử dụng để mô tả rõ ràng các điều kiện WHERE, JOIN và ORDER BY:

export interface WhereCondition {
  column: string;
  operator:
    | '='
    | '!='
    | '>'
    | '<'
    | '>='
    | '<='
    | 'LIKE'
    | 'IN'
    | 'NOT IN'
    | 'IS NULL'
    | 'IS NOT NULL';
  value?: any;
}

export interface JoinCondition {
  type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL OUTER';
  table: string;
  on: string;
}

export interface OrderByCondition {
  column: string;
  direction: 'ASC' | 'DESC';
}

2. BaseQueryBuilder: Xử Lý Những Thành Phần Chung

BaseQueryBuilder giữ các thành phần chung như bảng truy vấn, điều kiện WHERE, các phép JOIN, ORDER BY, LIMIT và OFFSET. Nó cũng cung cấp các phương thức chuỗi và chuẩn bị phần SQL con cho các lớp con:

export abstract class BaseQueryBuilder {
  protected _table: string = '';
  protected _whereConditions: WhereCondition[] = [];
  protected _joins: JoinCondition[] = [];
  protected _orderBy: OrderByCondition[] = [];
  protected _limit?: number;
  protected _offset?: number;

  // Ví dụ: Chuỗi fluent, trả về this để hỗ trợ chaining
  // Phương thức xây dựng phần WHERE, JOIN, ORDER BY, LIMIT tương ứng đi kèm

  abstract toSQL(): { query: string; params: any[] };
}

Bài học quan trọng:

Phương thức trả về this tạo thành API chuỗi liền mạch.

Truy vấn tham số hóa giúp tránh lỗi SQL Injection và chuẩn hóa kiểu dữ liệu.

Phương thức trừu tượng toSQL() buộc các builder con phải định nghĩa cách sinh SQL riêng.

3. Các Lớp Builder Chuyên Biệt

Mỗi loại truy vấn SELECT, INSERT, UPDATE, DELETE sẽ được mở rộng từ BaseQueryBuilder và bổ sung các tính năng riêng.

SelectQueryBuilder

Chọn cột, DISTINCT, GROUP BY, HAVING.

Hỗ trợ chainable các phương thức.

export class SelectQueryBuilder extends BaseQueryBuilder {
  private _columns: string[] = ['*'];
  private _distinct: boolean = false;
  private _groupBy: string[] = [];
  private _having: WhereCondition[] = [];

  select(columns: string | string[] = '*'): this { /* ... */ }
  distinct(): this { /* ... */ }
  groupBy(columns: string | string[]): this { /* ... */ }
  having(column: string, operator: WhereCondition['operator'], value?: any): this { /* ... */ }

  toSQL(): { query: string; params: any[] } {
    // Xây dựng SELECT từ các thành phần đã lưu
  }
}

UpdateQueryBuilder (với kiểm tra an toàn)

Bắt buộc có điều kiện WHERE để tránh cập nhật toàn bộ bảng.

Gán dữ liệu cập nhật an toàn.

export class UpdateQueryBuilder extends BaseQueryBuilder {
  private _data: Record<string, any> = {};

  set(columnOrData: string | Record<string, any>, value?: any): this { /* ... */ }

  toSQL(): { query: string; params: any[] } {
    const { clause: whereClause, params: whereParams } = this.buildWhereClause();
    if (!whereClause) {
      throw new Error('WHERE clause is required for UPDATE queries');
    }
    // Xây dựng câu lệnh UPDATE an toàn...
  }
}

4. Factory QueryBuilder

Dễ dàng tạo và sử dụng các builder thông qua một lớp factory tĩnh:

export class QueryBuilder {
  static select(columns?: string | string[]): SelectQueryBuilder {
    return new SelectQueryBuilder().select(columns);
  }

  static from(table: string): SelectQueryBuilder {
    return new SelectQueryBuilder().select().from(table);
  }

  // Tương tự với insert(), update(), delete()
}

5. Database Executor Kết Nối Với SQLite

Executor đóng vai trò làm cầu nối, nhận builder trả về câu truy vấn kèm tham số, rồi gọi API SQLite tương ứng.

export interface DatabaseInterface {
  execAsync(query: string, params?: any[]): Promise<any>;
  getAllAsync(query: string, params?: any[]): Promise<any[]>;
  getFirstAsync(query: string, params?: any[]): Promise<any>;
  runAsync(query: string, params?: any[]): Promise<{ lastInsertRowId: number; changes: number }>;
}

export class DatabaseExecutor {
  constructor(private db: DatabaseInterface) {}

  async select(builder: SelectQueryBuilder): Promise<any[]> {
    const { query, params } = builder.toSQL();
    return await this.db.getAllAsync(query, params);
  }

  // Các phương thức insert(), update(), delete() tương tự
}

Tích Hợp Với Ứng Dụng Từ Điển Gốc Ả Rập

Trước (Raw SQL)

async searchRootsRaw(query: string): Promise<Root[]> {
  const sql = `SELECT * FROM roots WHERE root_normalized LIKE ? LIMIT 50`;
  return await this.db.getAllAsync(sql, [`%${query.trim()}%`]);
}

Sau (Sử Dụng Query Builder)

async searchRootsWithQueryBuilder(
  query: string,
  dictionaryFilter?: string | null,
  limit = 50
): Promise<Root[]> {
  this.ensureInitialized();
  if (!query.trim()) return [];

  const normalizedQuery = query.trim();

  let queryBuilder = QueryBuilder
    .select([
      'r.id',
      'r.root_display',
      'r.root_normalized',
      'r.root_no_diacritics',
      'r.total_derivatives_count',
      'r.main_derivatives_count',
      'r.extracted_derivatives_count',
      'r.dictionary_source',
      'r.root_length',
      'r.full_text'
    ])
    .from('roots r')
    .where('r.root_normalized', 'LIKE', `%${normalizedQuery}%`)
    .orderBy('r.root_length')
    .orderBy('r.root_display')
    .limit(limit);

  if (dictionaryFilter) {
    queryBuilder = queryBuilder.where('r.dictionary_source', '=', dictionaryFilter);
  }

  return await this.executor!.select(queryBuilder);
}

Lợi ích thấy rõ:

Truy vấn rõ ràng, dễ hiểu hơn.

Giảm sai sót nhờ kiểu an toàn và tham số hóa.

Dễ dàng mở rộng hoặc thay đổi truy vấn bằng cách thêm các method chaining.

An toàn hơn với các truy vấn UPDATE hoặc DELETE nhờ bắt buộc WHERE.

Những Thách Thức Và Hướng Phát Triển

Xử lý các truy vấn phức tạp với UNION hoặc con trỏ: Đôi khi SQL thuần vẫn là lựa chọn tối ưu.

Ý thức về Schema: Kết hợp schema chi tiết để tăng cường an toàn kiểu và phát hiện lỗi sớm hơn.

Xử lý lỗi: Cần xây dựng cơ chế bắt và xử lý lỗi hiệu quả bên lớp executor.

Khả năng mở rộng: Hỗ trợ thêm các tính năng SQL nâng cao như stored procedures, trigger, hay CTEs.

Kết Luận

Việc tự xây dựng một query builder cho SQLite bằng TypeScript không chỉ giúp mã nguồn trở nên gọn gàng, dễ bảo trì mà còn tạo ra kiến trúc linh hoạt, bảo mật và tối ưu. Qua dự án Từ Điển Gốc Ả Rập, tôi đã hiểu rõ sức mạnh của mẫu thiết kế Builder, vai trò của kiểu tĩnh trong tương tác dữ liệu, và cách thức cải thiện trải nghiệm phát triển database.

Nếu bạn đang làm việc với cơ sở dữ liệu client-side và cảm thấy việc viết SQL thủ công ngày càng khó khăn, đừng ngần ngại thử sức với việc xây dựng một bộ công cụ query builder riêng. Đó sẽ là một thử thách giá trị, đồng thời nâng tầm chất lượng sản phẩm và trải nghiệm lập trình viên.

Tham Khảo

Vogels, W. (2023). Building SQL Query Builders with TypeScript.

SQLite Official Documentation. https://sqlite.org/docs.html

Microsoft TypeScript Documentation. https://www.typescriptlang.org/docs/

Fowler, M. (2004). Patterns of Enterprise Application Architecture. Addison-Wesley.

ORM vs Query Builder - Pros and Cons. https://db-engines.com/en/blog/post/orm-vs-query-builder