Фильтрация
Генерация типобезопасных структур запросов для фильтрации сущностей. Фильтрация позволяет реализовать пагинацию, поиск и запросы по диапазонам с безопасностью на этапе компиляции.
#[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>;
}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]
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Фильтрует с использованием регистронезависимого сопоставления по шаблону (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)]
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?;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())
}
}- Пагинация по умолчанию — Всегда применяйте разумные лимиты для предотвращения больших результатов
- Валидация шаблонов — Санитизируйте шаблоны LIKE для предотвращения проблем с SQL
- Индексация фильтруемых колонок — Создавайте индексы БД для часто фильтруемых полей
- Используйте конкретные фильтры — Предпочитайте точное совпадение шаблонному где возможно
- Комбинируйте с сортировкой — Рассмотрите добавление полей сортировки в структуру запроса
- Атрибуты — Полный справочник атрибутов
- Кастомный SQL — Сложные пользовательские запросы
- Связи — Фильтрация со связями
🇬🇧 English | 🇷🇺 Русский | 🇰🇷 한국어 | 🇪🇸 Español | 🇨🇳 中文