Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

rust-backend-design

/rust-backend-design

Projektuje dostęp do bazy i architekturę backendu Rust: przepływ żądań, pule połączeń, zadania Apalis, konfigurację i tracing.

Repozytorium
agents ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Projektuje dostęp do bazy i architekturę backendu Rust: przepływ żądań, pule połączeń, zadania Apalis, konfigurację i tracing.

Oryginalny opis (EN)

Architecture and data-access patterns for this backend — request flow, handler-owned DB access, bb8/tokio-postgres vs sqlx pools, query and transaction patterns, Apalis background jobs, config/secrets, and tracing. Use when adding handlers, touching the DB from routers, wiring the job queue, or reviewing backend structure.

Jak działa

  1. When to activate
  2. Request flow (no service or repository layer)
  3. Two connection pools (do not mix them)
  4. Query patterns
  5. Transactions
  6. Background jobs (Apalis + Postgres)
  7. Config, secrets & PII
  8. Logging & observability
  9. Error handling
  10. Module layout
Sekcje z nagłówków SKILL.md, w oryginale · 127 linii, 819 słów
Podgląd SKILL.md
---
name: rust-backend-design
description: Architecture and data-access patterns for this backend — request flow, handler-owned DB access, bb8/tokio-postgres vs sqlx pools, query and transaction patterns, Apalis background jobs, config/secrets, and tracing. Use when adding handlers, touching the DB from routers, wiring the job queue, or reviewing backend structure.
license: MIT
metadata:
  author: rainingdaemons/agents
  version: "1.0"
---

# Backend Patterns (Axum)

How this backend is structured and how to add to it without fighting its design. It describes the **architecture and data access**; axum wiring is in `axum-patterns`, REST contract design in `api-design`, SQL schema/index review in `postgresql-patterns` / `postgresql-optimization` / `database-design`, Rust language mechanics in `rust-patterns`.

## When to activate

- Adding or changing a handler that talks to the database
- Deciding where business logic lives
- Writing queries, avoiding N+1, or using a transaction
- Enqueuing or processing a background job
- Reading configuration / secrets

## Request flow (no service or repository layer)

```
HTTP → Router → AuthLayer (decode JWT → AuthUser extension) → RequireRoleLayer (RBAC check) → Handler
```

- **Handlers own their DB access directly.** There is deliberately **no** separate service or repository layer (see `agentwork/docs/architecture.md` §3). Keep business logic in the handler; do not introduce repository traits, `ProductService`, or a cache decorator.
- One file per resource in `src/routers/`. DB access lives there and in `connection.rs` — nowhere else.
- Auth, RBAC, and crypto live in `src/common/` (`middleware.rs`, `crypto.rs`).

## Two connection pools (do not mix them)

Typed in `src/connection.rs`:

```rust
pub type ConnectionPool = bb8::Pool<PostgresConnectionManager<NoTls>>; // handlers

pub async fn create_pool() -> ConnectionPool;        // bb8 + tokio-postgres
pub async fn create_sqlx_pool() -> sqlx::PgPool;     // Apalis queue ONLY
```

- **Handlers** use `ConnectionPool` (bb8 + `tokio-postgres`, runtime queries, no ORM).
- **`sqlx::PgPool`** is used **only** by the Apalis job queue storage. Do not use it for request-path queries.
- The pool is passed as `State` and is internally reference-counted — no `Arc` wrapper needed.

```rust
async fn get_all_products(
    State(pool): State<ConnectionPool>,
) -> Result<Json<ProductsListResponse>, (StatusCode, String)> {
    let conn = pool.get().await.map_err(internal_error)?;
    // ...
}
```

## Query patterns

Run queries on a pooled connection with `query` / `query_opt` / `query_one` / `execute`, mapping errors through the resource's `internal_error` helper.

- **Select only the columns you need** — avoid `SELECT *` (wide rows, TOAST fetches, serialization cost).
- **Avoid N+1:** fetch related rows in one JOIN, or batch with `WHERE id = ANY($1)` and build a `HashMap` in memory. See `products.rs::get_all_products` for a batched companion fetch.
- **Parameterize** with `$1, $2, …`; never format values into the SQL string. Own the parameter typing explicitly.
- **Soft deletes are the norm:** filter `is_deleted = false`.

```rust
let rows = conn
    .query(
        "SELECT id, name, slug FROM categories WHERE is_deleted = false ORDER BY sort_order, name",
        &[],
    )
    .await
    .map_err(internal_error)?;
```

## Transactions

`tokio-postgres` transactions borrow a connection and roll back on drop unless committed:

```rust
let mut conn = pool.get().await.map_err(internal_error)?;
let tx = conn.transaction().await.map_err(internal_error)?;
tx.execute("INSERT INTO orders (user_id, total) VALUES ($1, $2)", &[&user_id, &total])
    .await.map_err(internal_error)?;
tx.commit().await.map_err(internal_error)?;
```

Multi-statement writes that must be atomic should use a transaction. Several existing handlers issue sequential `execute` calls without one — when you touch such a handler, wrap the group in a transaction.

## Background jobs (Apalis + Postgres)

Email is never sent inline from a handler. Enqueue it; an Apalis worker delivers it.

- Storage: `apalis_postgres::PostgresStorage`; worker wiring in `src/queue/worker.rs`.
- Delivery is behind the `EmailSender` trait (`NoopEmailSender` in dev) — handlers stay testable.
- Worker layers: `JobTracingLayer`, `TimeoutLayer`, `ConcurrencyLimitLayer`; graceful shutdown via `tokio::select!` on `ctrl_c`.
- Enqueue via `storage.push(job)`. Job types live in `queue/types.rs`; handlers in `queue/handlers.rs`.

`tokio::spawn` is acceptable only for fire-and-forget work where losing the job on crash is fine; durable work goes through the queue.

## Config, secrets & PII

- Read configuration from the environment (`DB_URL`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `JWT_SECRET`, `RUT_ENCRYPTION_KEY`); `dotenvy::dotenv()` loads `backend/.env`.
- Never hardcode secrets or default them to real values. `main.rs` bootstrapping may `expect()` on missing critical vars; handlers may not.
- **Never store PII (RUT, etc.) in plaintext** — use `common/crypto.rs` (AES-256-GCM).

## Logging & observability

- Use the `tracing` crate with structured fields; `println!` / `dbg!` are banned in production code (`connection.rs` bootstrap prints are a known exception to clean up).
- Log the real error server-side; return a generic message to the client.

## Error handling

Handlers return `Result<Success, Rejection>`. Return a typed rejection, never `unwrap()`/`expect()` (except `main.rs` bootstrapping). Both rejection shapes and the target (log + generic message) are documented in `axum-patterns`.

## Module layout

```
src/main.rs        tracing init, env, pools, worker spawn, router assembly, bind :3000
src/lib.rs         library root for tests
src/connection.rs  create_pool() + create_sqlx_pool()
src/common/        crypto.rs, middleware.rs (JwtClaims, AuthUser, Role, layers)
src/queue/         Apalis email queue (worker, handlers, types, layers, sender trait)
src/routers/       one module per resource
```

## Checklist

- [ ] DB access stays in `src/routers/` + `connection.rs`; no new service/repository layer
- [ ] Handlers use `ConnectionPool`; `sqlx` only for the queue
- [ ] Queries select explicit columns; no N+1; values parameterized
- [ ] Multi-statement writes that must be atomic use a transaction
- [ ] Email is enqueued, not sent inline
- [ ] Secrets/PII come from env / `common/crypto.rs`; none hardcoded
- [ ] `tracing` used; no `println!`/`dbg!`; no `unwrap()`/`expect()` in handlers

Wersje

W bazie nie ma innych skilli o nazwie rust-backend-design.

Migawka bazy z 13.11.2026 · wersja paczki c02f87a6dbe8 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100rust-database
    Projektuje i testuje dostęp do baz w Rust: SQLx, Diesel, SeaORM, migracje, transakcje, pule połączeń i prawdziwe bazy testowe.
  • 90rc-sqlx
    Pisze i sprawdza dostęp do PostgreSQL w Rust przez SQLx 0.8+: pule, transakcje, migracje i testy bazy.
  • 100rust-web-backend
    Pomaga budować backend REST i HTTP w Rust: routing axum, extractory, współdzielony stan, middleware, odpowiedzi błędów i dostęp do bazy przez sqlx.
  • 100rust-backend
    Podaje wytyczne Rust dla backendu Windmill przy każdej zmianie kodu w katalogu backend.
  • 100sqlx-code-review
    Przegląda kod Rust z sqlx pod kątem sprawdzania zapytań w czasie kompilacji, zarządzania pulą połączeń, migracji i użycia PostgreSQL, w tym tryb offline, mapowanie typów i transakcje.
  • 100rust-backend
    Podaje wytyczne kodowania w Rust dla backendu Windmill, obowiązujące przy każdym pisaniu i zmianie kodu Rust w katalogu backend.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.