sqlx-query-dsl

这是一个基于 sqlx (MySQL) 的动态查询构建工具库。它允许通过 JSON 结构定义复杂的查询条件（包括嵌套的 AND/OR 逻辑），并提供了安全的分页查询封装。

✨ 特性

• 🛡️ 安全优先: 内置字段白名单 (FieldWhitelist) 机制，严格校验字段名，防止 SQL 注入。
• 🌳 嵌套逻辑: 支持任意深度的 AND / OR 逻辑嵌套。
• 📄 分页封装: 自动处理 COUNT(*) 查询和分页 LIMIT/OFFSET 计算。
• 🔌 JSON 驱动: 查询参数结构体 QueryParams 设计用于直接反序列化前端传入的 JSON。

📦 安装

在你的 Cargo.toml 中添加：

[dependencies]
sqlx-query-dsl = { path = "." } # 或者指向你的 git 仓库/crates.io 版本
sqlx = { version = "0.8", features = ["mysql", "runtime-tokio-rustls"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

🚀 使用指南

1. 定义数据模型

use sqlx::FromRow;
use serde::Serialize;

#[derive(Debug, Serialize, FromRow)]
pub struct User {
    pub id: i32,
    pub name: String,
    pub email: String,
    pub role: String,
    pub active: bool,
}

2. 执行分页查询

use sqlx_query_dsl::params::QueryParams;
use sqlx_query_dsl::whitelist::FieldWhitelist;
use sqlx_query_dsl::page::query_page;
use sqlx::MySqlPool;

async fn list_users(pool: &MySqlPool, params: QueryParams) -> Result<(), sqlx::Error> {
    // 1. 定义允许过滤和排序的字段（白名单）
    let allowed_fields = &["name", "email", "role", "active", "created_at"];
    let whitelist = FieldWhitelist::new(allowed_fields);

    // 2. 定义基础 SQL
    let base_sql = "SELECT * FROM users";
    let count_sql = "SELECT COUNT(*) FROM users";

    // 3. 执行查询
    // query_page 会自动处理 WHERE 子句的构建和参数绑定
    let page_result = query_page::<User>(
        pool,
        base_sql,
        count_sql,
        params,
        whitelist
    ).await?;

    println!("总记录数: {}", page_result.total);
    for user in page_result.list {
        println!("{:?}", user);
    }

    Ok(())
}

3. 前端 JSON 参数示例

前端发送的 JSON 请求体示例：

{
  "page": 0,
  "page_size": 10,
  "sort": [
    { "field": "created_at", "desc": true }
  ],
  "filter": {
    "and": [
      {
        "field": "role",
        "op": "eq",
        "value": "admin"
      },
      {
        "or": [
          { "field": "active", "op": "eq", "value": true },
          { "field": "name", "op": "like", "value": "Alice" }
        ]
      }
    ]
  }
}

🛠️ 支持的操作符 (Op)