sqlx-query-dsl 0.1.0

# sqlx-query-dsl


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

## ✨ 特性


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

## 📦 安装


在你的 `Cargo.toml` 中添加：

```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. 定义数据模型


```rust
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. 执行分页查询


```rust
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 请求体示例：

```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)


| 操作符 | SQL 映射 | 说明 |
|--------|----------|------|
| `eq`, `ne` | `=`, `!=` | 相等/不相等 |
| `like` | `LIKE` | 模糊匹配 (自动包裹 `%value%`) |
| `gt`, `lt` | `>`, `<` | 大于/小于 |
| `gte`, `lte` | `>=`, `<=` | 大于等于/小于等于 |
| `in`, `not_in` | `IN`, `NOT IN` | 列表包含 |
| `between` | `BETWEEN` | 范围查询 (需传入数组 `[min, max]`) |
| `is_null`, `is_not_null` | `IS NULL` | 空值检查 |
| `json_contains` | `JSON_CONTAINS` | JSON 字段查询 |