TRUEPIC QueryQL 技术详解：构建灵活高效的查询系统

概述

TRUEPIC QueryQL 是一个强大的查询构建库，专为现代 Web 应用设计，提供了标准化的过滤、排序和分页功能。本文将深入解析 QueryQL 的核心概念和使用方法，帮助开发者构建灵活、高效的 API 查询系统。

核心概念

查询器(Queriers)

查询器是 QueryQL 的核心组件，每个查询器大致对应一个模型/表/资源。查询器的主要职责是：

1. 定义可用的查询参数
2. 验证输入数据
3. 构建最终查询

一个典型的查询器定义如下：

const QueryQL = require('@truepic/queryql')

class UserQuerier extends QueryQL {
  defineSchema(schema) {
    // 定义查询模式
  }
}

基础查询器模式

建议创建基础查询器作为所有具体查询器的父类：

class BaseQuerier extends QueryQL {
  get pageDefaults() {
    return {
      size: 10,  // 设置默认分页大小为10
    }
  }
}

class UserQuerier extends BaseQuerier {
  defineSchema(schema) {
    // 用户特定查询模式
  }
}

配置系统

QueryQL 提供了灵活的配置选项：

全局配置

const { Config } = require('@truepic/queryql')

Config.defaults = {
  adapter: MyCustomAdapter,  // 使用自定义适配器
  validator: MyValidator     // 使用自定义验证器
}

实例配置

const querier = new UserQuerier(query, builder, {
  adapter: MyInstanceAdapter  // 实例特定配置
})

过滤功能详解

查询字符串格式

支持多种过滤格式：

• ?filter[name]=value
• ?filter[name][operator]=value

运算符支持

Knex 适配器默认支持的运算符包括：

• 比较运算符：=, !=, >, >=, <, <=
• 空值检查：is, is not
• 集合操作：in, not in
• 模糊匹配：like, not like, ilike, not ilike
• 范围查询：between, not between

模式定义

defineSchema(schema) {
  schema.filter('id', 'in', { field: 'users.id' })
  schema.filter('status', ['=', '!='])
}

自定义查询逻辑

'filter:q[=]'(builder, { value }) {
  return builder
    .where('first_name', 'like', `%${value}%`)
    .orWhere('last_name', 'like', `%${value}%`)
}

排序功能

查询字符串格式

支持多种排序格式：

• ?sort=name
• ?sort[]=name
• ?sort[name]=desc

模式定义

defineSchema(schema) {
  schema.sort('name')
  schema.sort('status', { field: 'current_status' })
}

自定义排序逻辑

'sort:name'(builder, { order }) {
  return builder.orderBy('last_name', order).orderBy('first_name', order)
}

分页功能

查询字符串格式

支持两种分页格式：

• ?page=number
• ?page[number]=2&page[size]=20

模式定义

defineSchema(schema) {
  schema.page()
}

分页默认值

get pageDefaults() {
  return {
    size: 20,
    number: 1
  }
}

验证系统

QueryQL 提供了强大的验证机制：

自定义验证规则

defineValidation(schema) {
  return {
    'filter:status[=]': schema.string().valid('open', 'closed'),
    'page:size': schema.number().max(100)
  }
}

错误处理

const { ValidationError } = require('@truepic/queryql').errors

try {
  const result = await querier.run()
} catch (error) {
  if (error instanceof ValidationError) {
    // 处理验证错误
  } else {
    // 处理其他错误
  }
}

最佳实践

1. 创建基础查询器：封装通用逻辑和默认值
2. 合理设计过滤条件：考虑常用查询场景
3. 设置合理的验证规则：防止无效查询到达数据库
4. 自定义复杂查询：对于特殊查询需求，使用自定义方法
5. 统一错误处理：为验证错误提供一致的响应格式

通过 TRUEPIC QueryQL，开发者可以快速构建出灵活、强大且安全的查询接口，大大提升 API 的开发效率和用户体验。