Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Генерация типобезопасных структур запросов для фильтрации сущностей. Фильтрация позволяет реализовать пагинацию, поиск и запросы по диапазонам с безопасностью на этапе компиляции.

Быстрый старт

#[derive(Entity)]
#[entity(table = "products")]
pub struct Product {
    #[id]
    pub id: Uuid,

    #[field(create, update, response)]
    #[filter]
    pub name: String,

    #[field(create, update, response)]
    #[filter(like)]
    pub description: String,

    #[field(create, update, response)]
    #[filter(range)]
    pub price: i64,

    #[field(create, response)]
    #[filter]
    pub category_id: Uuid,

    #[field(response)]
    #[auto]
    #[filter(range)]
    pub created_at: DateTime<Utc>,
}

Генерируемый код

Структура запроса

/// Параметры запроса для фильтрации сущностей Product.
#[derive(Debug, Clone, Default)]
pub struct ProductQuery {
    /// Фильтр по точному совпадению name.
    pub name: Option<String>,

    /// Фильтр по шаблону description (ILIKE).
    pub description: Option<String>,

    /// Фильтр по минимальной цене.
    pub price_from: Option<i64>,

    /// Фильтр по максимальной цене.
    pub price_to: Option<i64>,

    /// Фильтр по точному совпадению category_id.
    pub category_id: Option<Uuid>,

    /// Фильтр по минимальному created_at.
    pub created_at_from: Option<DateTime<Utc>>,

    /// Фильтр по максимальному created_at.
    pub created_at_to: Option<DateTime<Utc>>,

    /// Максимальное количество результатов.
    pub limit: Option<i64>,

    /// Количество пропускаемых результатов.
    pub offset: Option<i64>,
}

Метод репозитория

#[async_trait]
pub trait ProductRepository: Send + Sync {
    // ... стандартные CRUD-методы

    /// Запрос продуктов с фильтрами.
    async fn query(&self, query: ProductQuery) -> Result<Vec<Product>, Self::Error>;
}

Генерируемый SQL

SELECT id, name, description, price, category_id, created_at
FROM products
WHERE ($1 IS NULL OR name = $1)
  AND ($2 IS NULL OR description ILIKE $2)
  AND ($3 IS NULL OR price >= $3)
  AND ($4 IS NULL OR price <= $4)
  AND ($5 IS NULL OR category_id = $5)
  AND ($6 IS NULL OR created_at >= $6)
  AND ($7 IS NULL OR created_at <= $7)
ORDER BY created_at DESC
LIMIT $8 OFFSET $9

Типы фильтров

Точное совпадение (#[filter] или #[filter(eq)])

Фильтрует записи, где поле равно указанному значению.

#[filter]
pub status: String,

#[filter(eq)]  // То же самое
pub category_id: Uuid,

Генерируется:

pub status: Option<String>,
pub category_id: Option<Uuid>,

SQL:

WHERE status = $1
  AND category_id = $2

Совпадение по шаблону (#[filter(like)])

Фильтрует с использованием регистронезависимого сопоставления по шаблону (ILIKE).

#[filter(like)]
pub name: String,

#[filter(like)]
pub description: String,

Генерируется:

pub name: Option<String>,
pub description: Option<String>,

SQL:

WHERE name ILIKE $1
  AND description ILIKE $2

Использование:

let query = ProductQuery {
    name: Some("%widget%".into()),  // Содержит "widget"
    description: Some("premium%".into()),  // Начинается с "premium"
    ..Default::default()
};

Фильтр по диапазону (#[filter(range)])

Фильтрует в пределах диапазона (включительно).

#[filter(range)]
pub price: i64,

#[filter(range)]
pub created_at: DateTime<Utc>,

Генерируется:

pub price_from: Option<i64>,
pub price_to: Option<i64>,
pub created_at_from: Option<DateTime<Utc>>,
pub created_at_to: Option<DateTime<Utc>>,

SQL:

WHERE price >= $1 AND price <= $2
  AND created_at >= $3 AND created_at <= $4

Примеры использования

Базовая фильтрация

// Поиск продуктов по категории
let query = ProductQuery {
    category_id: Some(electronics_category_id),
    ..Default::default()
};
let products = repo.query(query).await?;

Пагинация

// Получение страницы 2 (20 элементов на страницу)
let query = ProductQuery {
    limit: Some(20),
    offset: Some(20),
    ..Default::default()
};
let products = repo.query(query).await?;

Комбинированные фильтры

// Поиск недорогой электроники
let query = ProductQuery {
    category_id: Some(electronics_category_id),
    price_from: Some(0),
    price_to: Some(10000),  // $100.00
    name: Some("%phone%".into()),
    limit: Some(50),
    ..Default::default()
};
let products = repo.query(query).await?;

Диапазон дат

// Получение продуктов, созданных в этом месяце
let now = Utc::now();
let month_start = now.with_day(1).unwrap().date_naive().and_hms_opt(0, 0, 0).unwrap();

let query = ProductQuery {
    created_at_from: Some(month_start.and_utc()),
    created_at_to: Some(now),
    ..Default::default()
};
let products = repo.query(query).await?;

Интеграция с API-эндпоинтом

use axum::{extract::Query, Json};

#[derive(Deserialize)]
pub struct ProductQueryParams {
    pub name: Option<String>,
    pub category_id: Option<Uuid>,
    pub min_price: Option<i64>,
    pub max_price: Option<i64>,
    pub page: Option<i64>,
    pub per_page: Option<i64>,
}

async fn list_products(
    Query(params): Query<ProductQueryParams>,
    pool: Extension<PgPool>,
) -> Result<Json<Vec<ProductResponse>>, AppError> {
    let page = params.page.unwrap_or(1);
    let per_page = params.per_page.unwrap_or(20).min(100);

    let query = ProductQuery {
        name: params.name.map(|n| format!("%{}%", n)),
        category_id: params.category_id,
        price_from: params.min_price,
        price_to: params.max_price,
        limit: Some(per_page),
        offset: Some((page - 1) * per_page),
        ..Default::default()
    };

    let products = pool.query(query).await?;
    let responses: Vec<_> = products.into_iter().map(ProductResponse::from).collect();

    Ok(Json(responses))
}

С мягким удалением

При включённом soft_delete запрос автоматически исключает удалённые записи:

#[derive(Entity)]
#[entity(table = "documents", soft_delete)]
pub struct Document {
    #[id]
    pub id: Uuid,

    #[field(create, response)]
    #[filter(like)]
    pub title: String,

    #[field(skip)]
    pub deleted_at: Option<DateTime<Utc>>,
}

Генерируемый SQL:

SELECT * FROM documents
WHERE deleted_at IS NULL
  AND ($1 IS NULL OR title ILIKE $1)
LIMIT $2 OFFSET $3

Дополнительный метод для включения удалённых:

async fn query_with_deleted(&self, query: DocumentQuery) -> Result<Vec<Document>, Self::Error>;

Расширения пользовательских запросов

Для сложных запросов используйте sql = "trait" и реализуйте пользовательскую фильтрацию:

#[derive(Entity)]
#[entity(table = "products", sql = "trait")]
pub struct Product { /* ... */ }

pub trait ProductQueryExt {
    async fn search_fulltext(&self, term: &str, limit: i64) -> Result<Vec<Product>, sqlx::Error>;
    async fn find_by_tags(&self, tags: &[String]) -> Result<Vec<Product>, sqlx::Error>;
}

#[async_trait]
impl ProductQueryExt for PgPool {
    async fn search_fulltext(&self, term: &str, limit: i64) -> Result<Vec<Product>, sqlx::Error> {
        let rows: Vec<ProductRow> = sqlx::query_as(
            r#"
            SELECT * FROM products
            WHERE to_tsvector('english', name || ' ' || description)
                  @@ plainto_tsquery('english', $1)
            ORDER BY ts_rank(to_tsvector('english', name || ' ' || description),
                            plainto_tsquery('english', $1)) DESC
            LIMIT $2
            "#
        )
        .bind(term)
        .bind(limit)
        .fetch_all(self)
        .await?;

        Ok(rows.into_iter().map(Product::from).collect())
    }

    async fn find_by_tags(&self, tags: &[String]) -> Result<Vec<Product>, sqlx::Error> {
        let rows: Vec<ProductRow> = sqlx::query_as(
            "SELECT * FROM products WHERE tags && $1"
        )
        .bind(tags)
        .fetch_all(self)
        .await?;

        Ok(rows.into_iter().map(Product::from).collect())
    }
}

Лучшие практики

  1. Пагинация по умолчанию — Всегда применяйте разумные лимиты для предотвращения больших результатов
  2. Валидация шаблонов — Санитизируйте шаблоны LIKE для предотвращения проблем с SQL
  3. Индексация фильтруемых колонок — Создавайте индексы БД для часто фильтруемых полей
  4. Используйте конкретные фильтры — Предпочитайте точное совпадение шаблонному где возможно
  5. Комбинируйте с сортировкой — Рассмотрите добавление полей сортировки в структуру запроса

См. также

  • [[Атрибуты|Атрибуты]] — Полный справочник атрибутов
  • Кастомный SQL — Сложные пользовательские запросы
  • [[Связи|Связи]] — Фильтрация со связями

Сортировка и keyset-пагинация

Пометьте сортируемые колонки #[sort]: Query-структура получает whitelist-селектор {Entity}SortField (по варианту Asc/Desc на колонку, snake_case в JSON) — пользовательский ввод не может инъецировать SQL. Каждый репозиторий также получает keyset-пагинацию list_after: с UUIDv7 по умолчанию обход по id хронологически стабилен и не деградирует на глубоких страницах, в отличие от OFFSET.

#[derive(Entity)]
#[entity(table = "posts")]
pub struct Post {
    #[id]
    pub id: Uuid,

    #[field(create, update, response)]
    #[sort]
    #[filter(like)]
    pub title: String,

    #[field(create, response)]
    #[sort]
    pub views: i64,
}

let query = PostQuery {
    sort: Some(PostSortField::ViewsDesc),
    limit: Some(20),
    ..Default::default()
};
let top: Vec<Post> = pool.query(query).await?;

let page: Vec<Post> = pool.list_after(None, 20).await?;
let next: Vec<Post> = pool.list_after(page.last().map(|p| p.id), 20).await?;

Trigram-поиск

#[filter(search)] на текстовой колонке добавляет нечёткий substring-фильтр (col ILIKE '%' || $n || '%', термин биндится). При включённых migrations соответствующий индекс gin_trgm_ops попадает в MIGRATION_UP, а pg_trgm автоматически добавляется в MIGRATION_EXTENSIONS. Проверка на компиляции: поле должно быть String.

#[field(create, update, response)]
#[filter(search)]
pub title: String,

let hits = pool.query(ArticleQuery { title: Some("rust".into()), ..Default::default() }).await?;