GraphQL cho Perfex CRM: Chỉ truy vấn chính xác những gì bạn cần

Vấn đề Over-Fetching (Thừa dữ liệu) của REST API

Nếu bạn đang xây dựng một ứng dụng frontend dựa trên dữ liệu của Perfex CRM, bạn chắc chắn đã gặp phải kịch bản này:

Yêu cầu thực tế: "Tôi chỉ cần tên khách hàng, email và tổng tiền hóa đơn gần nhất của họ."

REST response trả về: Trả lại 47 trường thông tin của mỗi khách hàng, bao gồm các ID nội bộ, mốc thời gian, siêu dữ liệu metadata và các cột bạn không bao giờ dùng đến. Sau đó, bạn phải gọi API lần thứ hai để lấy danh sách hóa đơn. Tiếp đến là lần thứ ba để khớp nối chúng lại.

Ba lệnh gọi API. 90% băng thông dữ liệu bị lãng phí. Đây chính là hiện tượng over-fetching (thừa dữ liệu) — và đó là lý do tại sao các đội ngũ phát triển frontend hiện đại luôn yêu cầu sử dụng GraphQL.

Một yêu cầu. Dữ liệu chính xác. Không lãng phí.

Mô-đun Data Builder tích hợp một **endpoint GraphQL sẵn sàng vận hành** cho hệ thống Perfex CRM tại địa chỉ /api/v1/graphql. Bạn có thể truy vấn chính xác các trường mình cần, trên nhiều bảng dữ liệu khác nhau, chỉ trong một yêu cầu duy nhất:

{
  clients(filter: { active: 1 }, limit: 10) {
    userid
    company
    email
  }
}

Dữ liệu phản hồi: Chỉ gồm userid, company, và email. Không có gì thêm. Ứng dụng frontend của bạn nhận được định dạng dữ liệu chuẩn xác như mong muốn.

Tích hợp bộ lọc mạnh mẽ

Mỗi bảng cơ sở dữ liệu được tự động sinh ra các định dạng bộ lọc với các hậu tố toán tử:

{
  invoices(filter: {
    status: 2,
    total_gte: 1000,
    total_lt: 5000,
    duedate_lt: "2026-05-01"
  }) {
    id
    total
    duedate
    status
  }
}

Các toán tử hỗ trợ trên từng cột:

• eq (bằng nhau, mặc định)
• ne (không bằng)
• gt, gte, lt, lte (các toán tử so sánh lớn hơn, nhỏ hơn hoặc bằng)
• like (so khớp chuỗi chứa)
• in (so khớp trong một danh sách)
• is_null (kiểm tra rỗng)

Tất cả các bộ lọc được kết hợp với nhau bằng logic AND. Các cột nhạy cảm được bảo mật (mật khẩu, mã băm, token) sẽ tự động bị bỏ qua trong bộ lọc.

Hỗ trợ đầy đủ các thao tác ghi dữ liệu (Mutations)

GraphQL không chỉ dùng để đọc dữ liệu. Data Builder hỗ trợ đầy đủ các **mutation tạo mới, cập nhật và xóa** đồng bộ với phân quyền của API token:

mutation {
  createInvoice(input: {
    clientid: 42,
    total: 2500.00,
    status: 1
  }) {
    id
    total
    status
  }
}

Các mutation được tự động sinh ra dựa trên cấu trúc các bảng cơ sở dữ liệu của bạn mà không yêu cầu bạn phải viết schema thủ công.

Ràng buộc quyền hạn ghi (Write scope): Các mutation chỉ xuất hiện trong schema khi API token tương ứng có quyền thao tác ghi. Nếu token có quyền chỉ đọc (read-only), các trường mutation sẽ hoàn toàn ẩn đi (không tồn tại trong schema) thay vì chỉ bị chặn lại khi thực thi.

Các chốt chặn bảo mật an toàn

Sự linh hoạt của GraphQL rất mạnh mẽ, nhưng nếu không có các chốt chặn, nó có thể gây nguy hiểm cho máy chủ. Data Builder tích hợp các giải pháp bảo mật chuẩn sản xuất:

Màn hình API Explorer nội bộ cho phép sử dụng introspection phục vụ phát triển — nhưng các ứng dụng khách bên ngoài chỉ nhìn thấy schema giới hạn an toàn.

Tự động tạo Schema

Bạn không cần tự tay viết schema GraphQL. Data Builder tự động quét các bảng được cấu hình và sinh ra:

• Các định nghĩa Query cho mỗi bảng
• Các định nghĩa bộ lọc Input với đầy đủ hậu tố toán tử
• Các định nghĩa Mutation (create/update/delete) với khóa chính tự phát hiện
• Ánh xạ kiểu dữ liệu chính xác: MySQL BIGINT → GraphQL String, DECIMAL → String (để bảo toàn độ chính xác số thập phân tài chính)

Khi bạn thêm một bảng mới vào cấu hình cho phép, các kiểu GraphQL tương ứng sẽ xuất hiện ngay lập tức mà không cần bước build mã nguồn hay cập nhật tệp schema.

Trải nghiệm trực quan trong API Explorer

Màn hình API Explorer tích hợp sẵn một **GraphQL sandbox** hỗ trợ:

• Các mẫu truy vấn cho mỗi bảng
• Thực thi truy vấn trực tiếp trên database
• Xem trước kết quả được làm nổi bật trực quan
• Random hóa dữ liệu nhạy cảm (PII randomization) trong chế độ sandbox — giữ nguyên cấu trúc query thực tế nhưng thay thế bằng dữ liệu ngẫu nhiên để bảo mật

Ứng dụng của bạn nên truy vấn dữ liệu thay vì phải đánh vật với API

Dù bạn đang xây dựng một ứng dụng di động, một trang dashboard React/Vue hay tích hợp SaaS trên dữ liệu Perfex CRM — GraphQL mang lại sự linh hoạt tối đa cho đội ngũ phát triển mà không bị giới hạn bởi backend.

Một endpoint duy nhất. Bất kỳ cấu trúc dữ liệu nào. Không lãng phí băng thông.