ViewSets — CRUD-REST-APIs
Ein ViewSet verwandelt ein Model in eine vollständige REST-Ressource — Endpunkte zum Auflisten, Erstellen, Lesen, Aktualisieren und Löschen von Datensätzen — aus einer einzigen Deklaration. Du beschreibst das Model und den gewünschten Kontrakt; das Routing, die Paginierung und die Serialisierung liefert das Framework.
Neu bei REST-APIs? Diese Anleitung setzt voraus, dass du weißt, was ein Endpunkt, ein HTTP- Verb (GET / POST / …) und eine JSON-Anfrage und -Antwort sind. Falls dir davon etwas unklar ist, ist das Glossar eine Fünf-Minuten-Einführung — lies es zuerst und komm dann hierher zurück.
Kombiniere ein ViewSet mit einem Serializer — dem Baustein, der dein JSON formt — und es schützt beide Richtungen auf einmal: Der Serializer formatiert jede Antwort (Felder umbenennen, verbergen, berechnen oder verschachteln) und regelt jede Anfrage (er validiert eingehende Daten und ignoriert stillschweigend Felder, die ein Client nicht setzen dürfen sollte). Abgelehnte Eingaben kommen in einer gut lesbaren Form zurück — ein JSON-Objekt mit dem Feldnamen als Schlüssel. Das funktioniert überall gleich auf PostgreSQL, MySQL und SQLite.
Diese Anleitung ist tutorial-orientiert: Wir bauen eine vollständige REST-Blog-API von Anfang bis Ende — Gerüst, Models, ein Serializer, das ViewSet, alle sechs CRUD-Endpunkte, Eingabe- validierung, Filterung/Suche/Paginierung und Tests — und der Rest der Seite ist eine Referenz für jede Stellschraube.
Quelle:
rustango::viewset(ViewSet,#[derive(ViewSet)], die#[viewset(...)]-Optionen + derfor_model-Builder) — hinteradminodertenancygated. Darin braucht.serializer::<S>()das Featureserializer,tenant_router()/OwnedBybrauchentenancy, und die QUERY-Aktion brauchtadmin.Lauffähige Version: Der hier gebaute Blog spiegelt das getestete, kompilierbare
getting_started_blog- Beispiel (dessenPost/PostSerializer/PostViewSet), und jedes Verhalten ist durch die eigenen Live-Tests des Frameworks abgesichert —crates/rustango/tests/viewset_*.rs(insbesondereviewset_serializer_render_sqlite_liveundviewset_serializer_input_sqlite_live).
Inhaltsverzeichnis
- API-Views vs. HTML-Views — JSON für Clients oder HTML-Seiten?
- Eine REST-Blog-API bauen — die vollständige Anleitung
- Die Serializer-Ehe: Eingabe + Ausgabe
- Die zwei Wege, ein ViewSet zu definieren
- Die CRUD-Endpunkte · Auswahl, welche exponiert werden
#[viewset(...)]-Referenz · Builder-Referenz- Filterung, Suche & Sortierung · Paginierung
- Validierung · Berechtigungen & Drosselung · Eigene Aktionen
- Einbinden · Backends
API-Views vs. HTML-Views
Vor dem Tutorial noch eine Weggabelung. Rustango hat zwei Wege, ein Model in Endpunkte zu verwandeln, und ein ViewSet ist einer davon:
- Ein ViewSet (diese Anleitung) ist ein API-View — es spricht JSON, für Frontend-Frameworks, mobile Apps und andere Dienste.
- Ein Template-View (HTML-Views) ist ein HTML-View — es rendert serverseitige Seiten über Tera, für Browser und servergerenderte Websites.
Darunter dasselbe Model; was sich unterscheidet, ist, was herauskommt und wer aufruft.
| API-View — ViewSet (hier) | HTML-View — Template-Views | |
|---|---|---|
| Modul | rustango::viewset | rustango::template_views |
| Sendet zurück | JSON-Daten | eine servergerenderte HTML-Seite |
| Gebaut für | SPAs, Mobile, andere Dienste | Browser, servergerenderte Websites, admin-artiges CRUD |
| Ein „Erstellen" | POST JSON → 201 + das Objekt | POST eines Formulars → 303-Weiterleitung (Post/Redirect/Get) |
| Bei ungültiger Eingabe | 400 ApiError; Serializer-Fehler 422, Felder in details | das Formular mit angezeigten Fehlern neu rendern |
| Eine „Liste" ist | ein paginierter JSON-Umschlag | eine Schleife über Zeilen in deinem Template |
| Üblicherweise authentifiziert per | Tokens / JWT / API-Keys | Session-Cookies |
Wähle pro Ressource — und du kannst beide auf demselben Model einbinden (eine öffentliche JSON- API und interne CRUD-Seiten). Der Rest dieser Anleitung ist die JSON-/API-Seite; für die HTML-Seite siehe HTML-Views — servergerenderte Seiten.
Eine REST-Blog-API bauen
Wir bauen einen Blog mit zwei Models — Author und Post — und exponieren Post als
REST-Ressource unter /api/posts, deren JSON-Form und Validierung von einem
Serializer gesteuert werden. Am Ende kannst du jedes CRUD-Verb per curl aufrufen und beobachten, wie der Serializer
die Ausgabe formt und ungültige Eingaben ablehnt.
Diese Anleitung setzt ein mit cargo rustango new myblog erstelltes Projekt voraus
(siehe Erste Schritte für Projekteinrichtung und Datenbank).
Jeder Schritt ist ein echter Befehl oder eine echte Datei.
Schritt 1 — Die Blog-App erstellen
Apps sind eigenständige Feature-Module:
cargo run -- startapp blog
Das schreibt src/blog/{mod,models,views,urls,tests}.rs und bindet das Modul
in src/lib.rs + den urls::api()-Aggregator ein.
Schritt 2 — Die Models definieren
src/blog/models.rs — ein Author und ein Post (ein Fremdschlüssel verknüpft sie):
use rustango::{Auto, Model};
use chrono::{DateTime, Utc};
#[derive(Model, Clone, Debug)]
#[rustango(table = "authors", display = "name")]
pub struct Author {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(max_length = 120)]
pub name: String,
#[rustango(max_length = 200)]
pub email: String,
}
#[derive(Model, Clone, Debug)]
#[rustango(table = "posts", display = "title", index("status, published_at"))]
pub struct Post {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(max_length = 200)]
pub title: String,
pub body: String,
#[rustango(max_length = 20, default = "'draft'")]
pub status: String, // draft | published | archived
#[rustango(fk = "authors", on = "id")]
pub author_id: i64,
#[rustango(auto_now_add)]
pub published_at: Auto<DateTime<Utc>>,
}
Schritt 3 — Migrieren
Migration generieren und anwenden (wie makemigrations + migrate):
cargo run -- makemigrations
cargo run -- migrate
Schritt 4 — Den Serializer gerüsten
Der Serializer definiert den Anfrage-/Antwort-Kontrakt der API. Generiere das Grundgerüst:
cargo run -- make:serializer PostSerializer --model Post
Dann fülle es aus. Dieses hier nutzt die gesamte Eingabe-+-Ausgabe-Oberfläche — eine Umbenennung, ein berechnetes schreibgeschütztes Feld, ein schreibgeschütztes Server-Feld und einen Feld-Validator:
// src/blog/post_serializer.rs
use rustango::{Auto, Serializer};
use chrono::{DateTime, Utc};
use crate::blog::models::Post;
#[derive(Serializer, serde::Deserialize, Default)]
#[serializer(model = Post)]
pub struct PostSerializer {
pub id: Auto<i64>,
#[serializer(validate = "title_min_3")] // input: reject titles < 3 chars
pub title: String,
#[serializer(source = "body")] // JSON key `content`, column `body`
pub content: String,
pub status: String,
pub author_id: i64,
#[serializer(method = "summary")] // output: computed, never written
pub summary: String,
#[serializer(read_only)] // output: shown, ignored on write
pub published_at: Auto<DateTime<Utc>>,
}
impl PostSerializer {
fn title_min_3(t: &String) -> Result<(), String> {
if t.chars().count() < 3 {
Err("title must be at least 3 characters".into())
} else {
Ok(())
}
}
fn summary(p: &Post) -> String {
p.body.chars().take(80).collect::<String>()
}
}
Der Generator schreibt src/post_serializer.rs: Verschiebe die Datei nach
src/blog/post_serializer.rs und füge pub mod post_serializer; zu src/blog/mod.rs hinzu.
Beachte, dass wir nur einen Validator geschrieben haben (title_min_3); die Felder erben zudem
automatisch die Constraints des Models — title wird gegen die Längenvorgabe des Models
max_length = 200 geprüft, und eine choices/min/max-Spalte würde ebenfalls geprüft,
wobei alle beim Schreiben freundliche 422er zurückgeben. Füge max_length / min_length /
min / max als Serializer-Attribute hinzu, um die Grenze eines Feldes zu überschreiben. (Siehe die
Serializer-Anleitung für die vollständige Validierungsgeschichte.)
Schritt 5 — Das ViewSet gerüsten und den Serializer verdrahten
cargo run -- make:viewset PostViewSet --model Post
Bearbeite es, um die Ressource zu deklarieren und den Serializer mit dem serializer-
Attribut zu verdrahten — diese eine Zeile schaltet serializer-gesteuerte Ausgabe und Eingabe ein:
// src/blog/post_view_set.rs
use rustango::ViewSet;
use crate::blog::models::Post;
#[derive(ViewSet)]
#[viewset(
model = Post,
fields = "id, title, body, status, author_id, published_at",
serializer = crate::blog::post_serializer::PostSerializer,
filter_fields = "author_id, status",
search_fields = "title, body",
ordering = "-published_at",
page_size = 20,
allow_anonymous,
)]
pub struct PostViewSet;
Der Generator schreibt src/post_view_set.rs, startet read_only und importiert
Post aus crate::blog::models. Verschiebe die Datei wie gezeigt
nach src/blog/post_view_set.rs und füge pub mod post_view_set; zu
src/blog/mod.rs hinzu.
fieldsist Pflicht: Es ist die Schreib-Allowlist, ein Body kann also keine andere Spalte setzen (etwaauthor_id). Ein Serializer schränkt sie weiter ein; er erweitert sie nie.
Schritt 6 — Die Routen einbinden
startapp hat blog::urls::api() bereits in urls::api() gemergt. Lass diese
Funktion, wie sie ist: Sie nimmt keinen Pool. Erzeuge stattdessen mit
cargo run -- make:api_routes blog den Pool-nehmenden Composer der App und
fülle src/blog/api_routes.rs aus:
// src/blog/api_routes.rs
use axum::Router;
use rustango::sql::Pool;
pub fn api(pool: Pool) -> Router<()> {
Router::new()
.merge(crate::blog::post_view_set::PostViewSet::router("/posts", pool))
}
Füge pub mod api_routes; zu src/blog/mod.rs hinzu. Dann binde ihn in
src/main.rs nach .api(urls::api()) ein, wo die Cli ihm den Pool des Servers
gibt: .nest_with("/api", |pool| myblog::blog::api_routes::api(pool)). Das
ViewSet antwortet jetzt unter /api/posts. Hänge das Präfix /api nur einmal
ein: Ein ViewSet-Pfad, der es wiederholt, würde /api/api/posts bedienen.
Schritt 7 — Ausführen und jeden Endpunkt durchprobieren
Posts verweisen auf einen Autor (author_id ist ein Fremdschlüssel), also lade
zuerst einen. Speichere dies als fixtures/authors.json:
[{"model": "Author", "pk": 1, "fields": {"name": "Ada", "email": "[email protected]"}}]
cargo run -- loaddata fixtures/authors.json
cargo run # listening on http://127.0.0.1:8080
Erstellen (POST). Der Serializer validiert zuerst und schreibt dann nur die
Felder, die er akzeptiert:
# happy path — note `content` (the renamed `body`) on the way in
curl -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"Hello Rustango","content":"First post body.","status":"published","author_id":1}'
{
"id": 1,
"title": "Hello Rustango",
"content": "First post body.",
"status": "published",
"author_id": 1,
"summary": "First post body.",
"published_at": "2026-01-02T12:00:00Z"
}
Die Antwort hat die Form des Serializers: body kam als content zurück, das
berechnete summary erschien, und published_at (schreibgeschützt, servergesetzt) ist
vorhanden.
Die Validierung lehnt ungültige Eingaben mit einem 422 ab — feldbasierte Arrays von
Meldungen unter details:
curl -i -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"hi","content":"x","author_id":1}'
# HTTP/1.1 422 Unprocessable Entity
# {"error":"validation_failed","message":"invalid input","status":422,
# "details":{"title":["title must be at least 3 characters"]}}
Schreibgeschützte / berechnete Felder, die ein Client postet, werden ignoriert — sie können weder
published_at noch summary unterschieben:
curl -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"Sneaky","content":"x","author_id":1,"published_at":"1999-01-01T00:00:00Z","summary":"hax"}'
# → published_at is the server value, not 1999; summary is recomputed from body.
Auflisten (GET) — paginiert, jede Zeile in der Form des Serializers:
curl localhost:8080/api/posts
{ "count": 1, "page": 1, "page_size": 20, "last_page": 1, "results": [ { "id": 1, "title": "Hello Rustango", … } ] }
Abrufen / Aktualisieren / Teilaktualisieren / Löschen:
curl localhost:8080/api/posts/1 # retrieve → 200
curl -X PUT localhost:8080/api/posts/1 -H 'content-type: application/json' \
-d '{"title":"Edited","content":"new body","status":"published","author_id":1}' # full update → 200
curl -X PATCH localhost:8080/api/posts/1 -H 'content-type: application/json' \
-d '{"title":"Just the title"}' # partial update → 200 (other fields untouched)
curl -X DELETE localhost:8080/api/posts/1 # destroy → 204
Die PATCH-Validierung läuft über das, was du sendest; schreibgeschützte Felder behalten ihren Server-
Wert, selbst wenn sie gepostet werden.
Schritt 8 — Filtern, suchen, sortieren, paginieren
Alles am Listen-Endpunkt, ohne zusätzlichen Code (du hast die Felder in Schritt 5 deklariert):
curl 'localhost:8080/api/posts?status=published&author_id=1' # filter
curl 'localhost:8080/api/posts?status__in=published,archived' # lookup
curl 'localhost:8080/api/posts?search=rustango' # search title+body
curl 'localhost:8080/api/posts?ordering=title' # sort (asc)
curl 'localhost:8080/api/posts?page=2&page_size=10' # paginate
Schritt 9 — Testen
Das Framework liefert einen In-Process-Testclient — prüfe echte HTTP-Antworten ab, ohne einen Server hochzufahren:
// tests/post_api.rs
use myblog::blog::models::Author;
use myblog::blog::post_view_set::PostViewSet;
use rustango::sql::Pool;
use rustango::test_client::TestClient;
use rustango::Auto;
use serde_json::json;
/// The router, and a fresh author for the posts to point at (`author_id`
/// is a foreign key, so an id with no row fails the insert).
async fn app() -> (TestClient, i64) {
// `cargo test` does not read `.env`; load it as main.rs does.
let _ = dotenvy::dotenv();
// `Pool::connect` picks the backend from the URL scheme, so the
// same test runs against sqlite, Postgres or MySQL.
let pool = Pool::connect(&std::env::var("DATABASE_URL").unwrap()).await.unwrap();
let mut author = Author {
id: Auto::default(),
name: "Test author".into(),
email: "[email protected]".into(),
};
author.save(&pool).await.unwrap();
let author_id = *author.id.get().unwrap();
(TestClient::new(PostViewSet::router("/api/posts", pool)), author_id)
}
#[tokio::test]
async fn rejects_short_title() {
let (client, author_id) = app().await;
let res = client.post("/api/posts")
.json(&json!({"title":"hi","content":"x","author_id":author_id}))
.send().await;
assert_eq!(res.status, 422);
assert!(res.json_value()["details"]["title"].is_array()); // field-keyed error shape
}
#[tokio::test]
async fn create_then_list() {
let (client, author_id) = app().await;
let created = client.post("/api/posts")
.json(&json!({"title":"Hello","content":"b","status":"published","author_id":author_id}))
.send().await;
assert_eq!(created.status, 201);
let list = client.get("/api/posts").send().await;
assert!(list.json_value()["results"].is_array());
}
cargo test --test post_api
Das ist eine vollständige, validierte REST-Ressource. Der Rest dieser Seite ist die Referenz hinter jedem Schritt.
Die Serializer-Ehe: Eingabe + Ausgabe
Das Verdrahten eines Serializers (über serializer = … an der Derive oder .serializer::<S>()
am Builder) verändert beide Richtungen. Es funktioniert auf PostgreSQL, MySQL und
SQLite gleichermaßen.
Ausgabe — Antworten werden durch den Serializer gerendert
list-, retrieve-, create- und update-Antworten werden durch
S::from_model(&row) erzeugt, sodass die Overrides des Serializers das JSON formen:
| Serializer-Feld | Wirkung auf die Antwort |
|---|---|
#[serializer(source = "body")] | Spalte body wird unter dem Namen des Feldes ausgegeben (z. B. content) |
#[serializer(method = "fn")] | ein berechnetes Feld erscheint (aus Self::fn(&model)) |
#[serializer(read_only)] | in der Ausgabe enthalten |
#[serializer(write_only)] | weggelassen aus der Ausgabe |
nested/many-Vorbehalt. Verschachtelte und Sammlungs-Serializer-Felder werden nur gerendert, wenn die verwandten Zeilen geladen wurden (überselect_related/ ein Eager- Fetch); andernfalls fallen sie auf ihren Standardwert zurück. Die automatische ViewSet-Listen- Abfrage lädt die Basiszeile — verdrahte Beziehungen explizit, wenn ein verschachteltes Feld befüllt werden muss.
Eingabe — Anfragen werden validiert und gefiltert
Bei create und update, wenn ein Serializer registriert ist:
- Die Validierung läuft. Das
validate()des Serializers — jedes einzelne#[serializer(validate = "fn")]pro Feld plus das feldübergreifendevalidateauf Container- Ebene — läuft gegen den JSON-Body. Bei Fehlschlag wird die Anfrage abgelehnt mit422 Unprocessable Entity(validation_failed) und der feldgeschlüsselten Fehlerform indetails: ein JSON-Objekt mit dem Feldnamen als Schlüssel und Arrays von Meldungen, z. B.{"title":["title must be at least 3 characters"]}. - Filterung schreibbarer Felder. Nur die schreibbaren Felder des Serializers werden
gespeichert;
read_only- undmethod-/berechnete Felder, die ein Client postet, werden ignoriert (nicht geschrieben), undsource-Umbenennungen werden auf die Model- Spalte aufgelöst. So kann ein Client kein servergesteuertes Feld setzen, indem er es in den Body einschließt.
Form-urlencoded-Bodies (vs. JSON) überspringen
validate()— es gibt keinen typisierten Wert zu validieren — bekommen aber trotzdem die Filterung schreibbarer Felder.
Unter der Haube sind dies die Methoden validate(), writable_source_fields()
und from_writable_json() des ModelSerializer-Traits, alle generiert von
#[derive(Serializer)]. Siehe die Serializer-Anleitung dazu, wie man
die Validatoren schreibt.
Die zwei Wege, ein ViewSet zu definieren
Beide erzeugen einen axum::Router mit denselben CRUD-Routen.
1. Das Derive-Makro — deklarativ, Single-Tenant; verdrahte einen Serializer mit
serializer = …:
#[derive(ViewSet)]
#[viewset(
model = Post,
fields = "id, title, body, status, author_id, published_at",
serializer = crate::blog::post_serializer::PostSerializer,
filter_fields = "author_id, status",
search_fields = "title, body",
ordering = "-published_at",
page_size = 20,
allow_anonymous,
)]
pub struct PostViewSet;
let router = PostViewSet::router("/api/posts", pool);
2. Der Builder — ViewSet::for_model(...), programmatisch, tri-dialektfähig
(PostgreSQL / SQLite / MySQL) und mandantenfähig; verdrahte einen Serializer mit
.serializer::<S>():
use rustango::viewset::ViewSet;
use rustango::core::Model as _;
let router = ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.serializer::<PostSerializer>()
.filter_fields(&["author_id", "status"])
.search_fields(&["title", "body"])
.ordering(&[("published_at", true)]) // true = DESC
.page_size(20)
.router("/api/posts", pool); // tri-dialect Pool
Greife zum Builder, wenn du SQLite/MySQL, Mandantenfähigkeit, eine zur Laufzeit erstellte Konfiguration oder die Extras (Drosselung, eigene Filter-Backends, Cursor-Paginierung) brauchst.
Die CRUD-Endpunkte
Das Einbinden unter /api/posts verdrahtet alle sechs REST-Operationen:
| Verb | Pfad | Aktion | Erfolg | Body |
|---|---|---|---|---|
GET | /api/posts | list | 200 | paginierter Umschlag (siehe Paginierung) |
POST | /api/posts | create | 201 | das erstellte Objekt — oder ein Array bei Bulk-Create |
GET | /api/posts/{pk} | retrieve | 200 | das Objekt |
PUT | /api/posts/{pk} | update (vollständig) | 200 | das aktualisierte Objekt |
PATCH | /api/posts/{pk} | partial update | 200 | das aktualisierte Objekt (nur gelieferte Felder ändern sich) |
DELETE | /api/posts/{pk} | destroy | 204 | leer |
Ein abschließender Schrägstrich am Mount-Präfix ist optional. Diese sechs Verben werden verdrahtet,
dazu eine QUERY-Collection-Action nach RFC 10008, sobald das Feature admin
aktiv ist. Die Routen werden mit axum::routing::get gebaut, also beantwortet
axum HEAD automatisch aus dem GET-Handler; OPTIONS ist nicht verdrahtet. Bulk-Create gibt es gratis: POST ein JSON-
Array, und jedes Element wird der Reihe nach eingefügt, in einer Transaktion. Ein
fehlerhaftes Element lehnt die ganze Charge ab und hinterlässt nichts — gleich ob
die Validierung oder die Datenbank es abfängt.
Die zweite Hälfte stimmte in älteren Versionen nicht. Die Validierung war atomar; die Schreibvorgänge waren je ein
INSERTohne Transaktion, sodass ein Unique- oder Fremdschlüsselverstoß bei Element 5 die Elemente 0–4 committete,400 bulk entry 5zurückgab und keine der erzeugten Zeilen nannte. Genau diese Verstöße kann die Validierung vorab nicht entscheiden.
Eine Charge fasst höchstens 1000 Zeilen (max_bulk_create(n); mehr ist ein 413),
und jede Zeile verbraucht eine create-Throttle-Einheit.
Bei einem #[rustango(soft_delete)]-Modell stempelt DELETE die Spalte, statt zu
löschen, und jede Action behandelt eine soft-gelöschte Zeile als verschwunden.
Auswahl, welche Operationen exponiert werden
Für eine schreibgeschützte Ressource (nur list + retrieve) füge read_only hinzu:
#[viewset(model = Post, fields = "id, title", read_only)] // macro
ViewSet::for_model(Post::SCHEMA, &["id", "title"]).read_only() // builder
Es gibt keinen Umschalter pro Verb außer read_only. Für „alles außer Löschen" binde das ViewSet ein und überschreibe die eine Route mit deinem eigenen Handler (siehe Eigene Aktionen).
#[viewset(...)]-Attributreferenz
| Schlüssel | Beispiel | Standard | Was er tut |
|---|---|---|---|
model | model = Post | erforderlich | Das Model, auf dem die Ressource aufbaut. |
serializer | serializer = path::To::S | keiner | Einen Serializer für typisierte Ausgabe + Eingabe verdrahten (siehe oben). |
fields | "id, title, body" | Pflicht | Die einzigen Felder, die Antworten zeigen und Bodies schreiben dürfen; andere Schlüssel werden ignoriert. Ein Serializer schränkt sie ein. |
filter_fields | "author_id, status" | keiner | Über ?field=value filterbare Felder (+ Lookups). |
search_fields | "title, body" | keiner | Felder, die die ?search=-Box durchsucht (Groß-/Kleinschreibung-unabhängiges ODER). |
ordering | "-published_at, id" | keiner | Standardsortierung (- = DESC). |
page_size | 20 | 20 | Zeilen pro Seite (Client-?page_size= gedeckelt bei 100). |
read_only | (Flag) | aus | Nur GET (list + retrieve) exponieren. |
allow_anonymous | (Flag) | aus | Erklärt, dass Schreibaktionen ohne Codenamen offen sein sollen; ohne es (oder read_only) verweigern sie das Einhängen. |
permissions(...) | permissions(create = "posts.add") | keiner | Berechtigungs-Codenamen pro Aktion; braucht tenancy. |
Builder-Referenz
ViewSet::for_model(SCHEMA, &["id", "title"]) nimmt die Feldliste: die einzigen
Felder, die Antworten zeigen und Bodies schreiben dürfen. Jede weitere Methode gibt Self zurück:
| Methode | Zweck |
|---|---|
serializer::<S>() | Einen Serializer für typisierte Ausgabe + Eingabe verdrahten (tri-dialektfähig). |
filter_fields(&["…"]) | ?field=value-Filterung aktivieren. |
search_fields(&["…"]) | ?search= aktivieren. |
ordering(&[("field", desc)]) | Standardsortierreihenfolge. |
ordering_fields(&["…"]) | Festlegen, welche Felder ?ordering= verwenden darf. |
page_size(n) | Standard-Seitengröße (≤ 100). |
max_page_size(n) | Hebt oder senkt das Client-Limit selbst (Default 100). |
max_offset(n) | Tiefste Zeile für ?offset= / ?page=; darüber ein 400 (Default 10 000, 0 hebt es auf). |
count(false) | Lässt das COUNT(*) weg; count ist dann null. |
max_bulk_create(n) | Höchstzahl an Zeilen, die ein Bulk-Create tragen darf (Default 1000). |
pk_param(name) | Benennt den Pfadparameter der Detail-Routen um (pk_param_name() liest ihn zurück). |
openapi_query(bool) | Beschreibt die QUERY-Route im erzeugten OpenAPI-Dokument (braucht OpenAPI-3.2-Tooling). Standardmäßig aus; die Route wird in jedem Fall eingehängt. |
related_filter(fk_field, backend) | Begrenzt, welche Zielzeilen ein FK im Body nennen darf; jede andere ist ein 422. |
read_only() | Nur GET. |
allow_anonymous() | Schreibzugriffe ohne Codenamen sind gewollt; ohne es verweigern sie das Einhängen. |
permissions(ViewSetPerms{…}) / permissions_for_model::<T>() | Codename-Gates pro Aktion; beide brauchen tenancy. |
cursor_pagination("id") / cursor_pagination_desc("id") | Keyset-Paginierung (überspringt COUNT(*)). Jede total geordnete NOT-NULL-Spalte: Integer, Timestamp, Datum, UUID oder String. |
limit_offset_pagination() | ?limit=&offset=-Fensterung. |
pagination(PaginationStyle::…) | Den Stil explizit setzen. |
filter_backend(closure) | Eigene WHERE-Prädikate über filter_fields hinaus hinzufügen. |
throttle(…) / throttle_all(max, secs) | Rate-Limits pro Aktion mit festem Zeitfenster; QUERY verbraucht das Budget der Liste. |
skip_object_permissions() | Überspringt die Objekt-Berechtigungs-Hooks und Queryset-Scopes der App, für eine API, die ihre Zeilen selbst schützt. Die Hooks des Frameworks laufen weiter. |
view_hook_scan_cap(n) | Höchstens so viele Zeilen liest eine Liste für den "view"-Hook (Standard 2 000, im Admin 10 000; höchstens 100 000); darüber ist eine Seiten- oder Offset-Liste ein 400 (Cursor-Listen funktionieren weiter). Ein Serializer-Feld nested / many / slug auf eine Tabelle mit view-Hook oder Queryset-Scope lässt das Einhängen paniken, außer mit skip_object_permissions(). |
router(prefix, pool) | Tri-dialektfähig einbinden (PG / SQLite / MySQL). |
tenant_router(prefix) | (Mandantenfähigkeit) mit Mandantenauflösung pro Anfrage einbinden. |
Filterung, Suche und Sortierung
Alles gesteuert über Query-Parameter am Listen-Endpunkt.
Filterung — jeder filter_fields-Eintrag akzeptiert ?field=value (exakt) plus
Lookups über ein __suffix:
?status=published
?author_id__in=1,2,3
?published_at__gte=2026-01-01
?title__icontains=rust
?body__isnull=false
Unterstützte Lookups: ne, gt, gte, lt, lte, in, not_in, contains,
icontains, startswith, istartswith, endswith, iendswith, isnull
(kein Suffix = exakt). Felder, die nicht in filter_fields stehen, werden ignoriert.
Suche — ?search=term durchsucht search_fields mit einem Groß-/Kleinschreibung-unabhängigen ODER.
Sortierung — ?ordering=field,-other (- = DESC). Jedes Feld, das die Antwort
zeigt (mit Serializer: die Felder, die er rendert), ist sortierbar, sofern du es nicht mit .ordering_fields([...]) einschränkst. Ohne Parameter gilt der
ordering-Standard. Alle lassen sich kombinieren.
Paginierung
Fallstrick — paginiere über eine deterministische Reihenfolge. Seitenzahl- und Limit/Offset-Paginierung setzen eine stabile Sortierung voraus; das Sortieren über eine nicht-eindeutige Spalte (oder gar keine) lässt Zeilen zwischen den Seiten verrutschen — dupliziert oder übersprungen. Füge immer einen eindeutigen Tiebreaker hinzu, z. B.
ordering = "-published_at, id". (Beide führen zudemCOUNT(*)pro Aufruf aus; Cursor-Paginierung überspringt das bei großen Tabellen.)
Drei Stile; Seitenzahl ist der Standard. Der Listen-Umschlag unterscheidet sich je Stil:
Seitenzahl (Standard) — ?page=2&page_size=20:
{ "count": 137, "page": 2, "page_size": 20, "last_page": 7, "results": [ … ] }
Cursor — .cursor_pagination("id") (oder _desc); überspringt COUNT(*), ideal
für sehr große Tabellen. ?cursor=<token>&page_size=20:
{ "page_size": 20, "next": "<opaque-cursor-or-null>", "results": [ … ] }
Limit/Offset — .limit_offset_pagination(). ?limit=20&offset=40:
{ "count": 137, "limit": 20, "offset": 40, "results": [ … ] }
page_size / limit werden auf max_page_size begrenzt (Default 100).
Validierung
Mit einem verdrahteten Serializer führt der Create-/Update-Pfad die Validatoren des Serializers
aus und gibt feldgeschlüsselte 422er zurück — der empfohlene Weg zu validieren (siehe
die Ehe und die
Serializer-Anleitung). Drei Schichten laufen:
- Deklarative Constraints —
max_length/min_length/min/max, und standardmäßig erbt das Feld dasmax_length/min/max/choicesdes Models. So wird eine#[rustango(max_length = 200)]-Spalte an der API längengeprüft, ohne zusätzliche Konfiguration, wodurch potenzielle500er aus DB-Constraints in freundliche422er mitdetailsverwandelt werden wie{"title":["Ensure this value has at most 200 characters."]}. - Pro-Feld-
validate = "fn"und ein feldübergreifendervalidate-Hook — deine eigenen Regeln (Formate, feldübergreifend, Geschäftslogik).
Unabhängig von einem Serializer erzwingt der Schreibpfad immer das Schema:
- Typen werden konvertiert und geprüft — ein ungültiger
i64- /DateTime- /Uuid- /bool- Wert ergibt einen400, der das Feld nennt. - Erforderlich / NOT NULL — ein fehlendes nicht-nullbares Feld (oder ein leerer String für einen
nicht-nullbaren
String) ergibt einen400; nullbare Felder akzeptieren leer →NULL. In einem JSON-Body ist nurnullgleichNULL:""auf einem nullbarenStringbleibt"". - Zahlen — NaN und Unendlich ergeben einen
400; eine als JSON-Zahl gesendete Dezimalzahl behält alle Ziffern. - Datenbank-Constraints — Unique, Fremdschlüssel und Check-Constraints tauchen
als
400beim INSERT/UPDATE auf.
Also bekommst du selbst ohne Serializer Typ- + Erforderlich- + DB-Constraint-Validierung; verdrahte einen Serializer, um deklarative Längen-/Bereichs-/Auswahl-Prüfungen (automatisch geerbt) plus deine eigenen Pro-Feld- und feldübergreifenden Regeln zu erhalten.
Formen der Fehlerantwort
Jeder ViewSet-Fehler ist ein ApiError-Body, dieselbe Form,
die deine eigenen Handler senden:
{"error": "<machine code>", "message": "<sentence>", "status": 400}
errorist ein stabiler Code (bad_request,unauthorized,not_found,validation_failed,rate_limited,internal_error, …). Verzweige darüber.- Serializer-Validierung ist ein
422validation_failed, mit der Feld-Map indetails:{"title": ["Ensure this value has at most 200 characters."], "non_field_errors": [ … ]}. Die oben genannten400er aus Typkonvertierung und Pflichtfeldern sindbad_requestmit dem Grund inmessage; ein400aus einem Datenbank-Constraint hält den Treibertext zurück. - Ein
5xxträgt nie die Ursache, außerRUSTANGO_DISCLOSE_ERRORSist gesetzt. Sie wird geloggt;messageist generisch.
Berechtigungen und Drosselung
Lesen ist standardmäßig öffentlich, Schreiben nicht. Ein ViewSet ohne Codenamen liefert List und Retrieve an jeden und verweigert das Einhängen, solange Create, Update oder Destroy keine haben, außer mit
read_onlyoderallow_anonymous.
Berechtigungen sichern jede Aktion über Codenamen (ODER innerhalb einer Aktion):
use rustango::viewset::{ViewSet, ViewSetPerms};
ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.permissions(ViewSetPerms {
list: vec!["posts.view".into()],
retrieve: vec!["posts.view".into()],
create: vec!["posts.add".into()],
update: vec!["posts.change".into()],
destroy: vec!["posts.delete".into()],
})
.tenant_router("/api/posts");
An tenant_router muss der Benutzer zum gerouteten Tenant gehören. An einem
.router(prefix, pool) mit festem Pool zählt nur ein Benutzer aus deiner eigenen
Single-Database-Auth-Schicht; der Benutzer eines Tenants (require_auth, eine
Session) bekommt 403. Unter Tenancy hänge gesicherte ViewSets mit tenant_router ein.
Eine leere Aktionsliste = keine Prüfung. Die Durchsetzung liest einen authentifizierten Benutzer aus
der Anfrage (die tenancy-Auth-Integration); Superuser umgehen sie, ein fehlender Benutzer
wird abgelehnt. .permissions_for_model::<Post>() füllt automatisch die Standard-
Codenamen <table>.view / .add / .change / .delete (posts.view, … für die
Tabelle posts). Codenamen brauchen die tenancy-Feature: Ohne sie verweigert
ein ViewSet, das welche setzt, das Mounten mit einem Panic, der die Lösung nennt.
In einer Single-Database-App setze deine eigene Auth-Schicht davor und nutze
allow_anonymous oder read_only. Erste Schritte, Schritt 14 zeigt
eine solche Schicht vollständig: Lesen öffentlich, Schreiben mit Bearer-Token.
Objekt-Berechtigungen. Ein ViewSet führt dieselben Hooks wie der Admin aus
(register_object_permission!, register_queryset_scope!): add beim Create
(ein Bulk-Create ganz oder gar nicht, 403 mit {"details": {"index": i}});
view bei Retrieve, Update und Delete (verborgen ist 404), dann change bzw.
delete (403, auch beim Soft Delete); view in Listen (verborgene Zeilen
fehlen in Seite und count, ab view_hook_scan_cap ist eine Seiten- oder
Offset-Liste ein 400: Queryset-Scope ergänzen oder Cursor-Paginierung nutzen). Queryset-Scopes schränken jedes Lesen und Schreiben ein; ein Schreiben, dessen Zeile sie verließe, ist ein 403, ebenso ein Create, das der view-Hook verbergen würde. Hooks lesen die Zeile gesperrt in der Schreib-Transaktion; ein Credential eines anderen Mandanten ist ein 403.
change prüft nur die gespeicherte Zeile. object_permissions::Actor::of(&parts)
sagt einem Hook, wer fragt; ein Agent-Token ist nie Superuser.
rustango_api_keys, rustango_agents, rustango_agent_grants, rustango_operators,
rustango_admin_users und die SSO-Tabellen lehnen
ViewSet::for_model und die fünf Template-Views ab.
Drosselung wendet Limits pro Client mit festem Zeitfenster an, pro Aktion:
ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.throttle_all(60, 60) // 60 requests / 60s per client, every action
.router("/api/posts", pool);
Über dem Limit → 429 Too Many Requests + Retry-After. Die Zähler sind pro Prozess;
der Client-Schlüssel ist die vertrauenswürdige Client-IP (TrustedRealIp, sonst der Socket; siehe security.md).
Eigene Aktionen jenseits von CRUD
Es gibt kein Attribut, um weitere Routen an ein ViewSet zu hängen — es ist strikt auf die sechs CRUD- Routen beschränkt. Für zusätzliche Endpunkte binde deine eigenen Handler neben dem ViewSet ein:
use axum::{Router, routing::{get, post}};
let api = Router::new()
.merge(ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"]).router("/api/posts", pool.clone()))
.route("/api/posts/stats", get(post_stats))
.route("/api/posts/bulk_archive", post(bulk_archive));
Für zusätzliche WHERE-Logik trägt .filter_backend(…) Prädikate ohne eine
separate Route bei.
Zeilen auf den authentifizierten Principal beschränken
Ein Backend läuft bei jeder Aktion — list, retrieve, update, destroy —
es engt also das Basis-Queryset für alle Routen ein. Eine vom Backend ausgeschlossene Zeile ergibt einen
404 auf den Item-Routen, keinen 403: Ein 403 würde bestätigen, dass die ID existiert.
Die Identität muss aus der Credential kommen, niemals aus dem Query-String. Ein
?owner_id=-Filter ist kein Scope — er ist ein Parameter, den der Aufrufer wählt.
Ein Scope schränkt nur das Lesen ein. Ein Backend, dem eine Spalte gehört, implementiert
auch write_pins: Create speichert den Besitzer, Update kann ihn nicht ändern, und
WritePin::Deny lehnt den Schreibzugriff mit 403 ab.
Auch die statischen globalen Scopes eines Modells begrenzen, was gelesen wird, nicht was
geschrieben wird: Create oder Update darf den Scope verlassen (201 nur mit dem Schlüssel oder 204).
Für eine Sicherheitsgrenze nimm ein Filter-Backend mit write_pins.
Ein Schreibvorgang gibt seine volle Zeile nur an einen Aufrufer mit der
Berechtigung retrieve zurück; andere bekommen nur {"<pk>": …} (eine pro
Bulk-Zeile). Ein einzelnes Create sendet außerdem einen Location-Header, der
auf die Detail-Route zeigt.
Ein FK, den ein Body setzt, muss eine Zeile nennen, die die globalen Scopes des Ziels zeigen; ein Update darf den Wert erneut senden, den die Zeile bereits hat. Um ihn weiter einzugrenzen, ergänze ein Backend für dieses Feld; es läuft gegen das Zielmodell, und jede andere Zeile ist ein 422:
ViewSet::for_model(Comment::SCHEMA, &["id", "body", "post_id"])
.related_filter("post_id", OwnedBy::column("author_id"))
OwnedBy — das mitgelieferte Backend
Die meisten besitzgebundenen Ressourcen brauchen genau eine Regel: Zeilen, deren Besitzspalte der Aufrufer ist. Benenne die Spalte und binde es ein.
use rustango::tenancy::auth_routes::{require_bearer, Config, JwtAuth};
use rustango::viewset::{OwnedBy, ViewSet};
let auth = JwtAuth::new(Config::default()); // einer, der auch `auth.router()` bedient
ViewSet::for_model(Note::SCHEMA, &["id", "body"])
.filter_backend(OwnedBy::column("member_id"))
.tenant_router("/api/notes")
.layer(axum::middleware::from_fn_with_state(auth.clone(), require_bearer))
Jede Spalte funktioniert — owner_id, member_id, author_id — weil das Backend
den Namen entgegennimmt, statt eine Konvention anzunehmen. Es scheitert geschlossen bei den beiden
Arten, wie es falsch sein kann: Eine unauthentifizierte Anfrage und eine Spalte, die das Model nicht
hat, treffen beide auf nichts, sodass ein Tippfehler beim Einbinden nicht zu „keine
Prädikate, gib die Tabelle zurück" werden kann.
OwnedBy pinnt seine Spalte beim Schreiben: Create speichert den Aufrufer, egal was im
Body steht, Update verschiebt die Zeile nie, und ein Schreibzugriff ohne Principal ist 403.
Superuser sind standardmäßig nicht besonders; .superuser_sees_all() schaltet das frei, denn
„Admins sehen alles" ist eine Produktentscheidung, keine des Frameworks.
Woher die Identität kommt
[Principal] ist der eine Identitätstyp, aufgelöst aus dem, was die Anfrage
verifiziert hat — ein expliziter Principal, ein von einer Session- oder Bearer-Middleware hinterlassener
AuthenticatedUser oder ein MCP-Agent-Token (der als der Benutzer agiert, der ihn ausgestellt hat).
Er authentifiziert selbst nichts; er liest nur, was eine verifizierende Middleware
bereits nachgewiesen hat, sodass niemand einen einfügen darf, ohne zuerst eine Credential zu prüfen.
require_bearer ist diese Middleware für eine JSON-API: Sie verifiziert das Access-Token
gegen den aufgelösten Mandanten, liest die Benutzerzeile erneut (ein deaktiviertes Konto hört
bei der nächsten Anfrage auf zu funktionieren, nicht erst wenn das Token abläuft), und fügt sowohl
AuthenticatedUser als auch Principal ein. Verwende sie überall als Extraktor:
use rustango::tenancy::{OptionalPrincipal, Principal};
async fn mine(principal: Principal) -> String { // 401 when absent
format!("user {}", principal.user_id)
}
async fn home(OptionalPrincipal(who): OptionalPrincipal) -> String {
who.map_or("anonymous".into(), |p| format!("user {}", p.user_id))
}
Ein eigenes Backend schreiben
Wenn Besitz keine einzelne Spalte ist — ein geteiltes Team, eine soft-gelöschte Zeile, ein
Zeitfenster von Daten — implementiere das Trait und überschreibe filter_with, das
die Anfrage-Parts erhält:
use std::collections::HashMap;
use axum::http::request::Parts;
use rustango::core::{Filter, ModelSchema, Op, SqlValue, WhereExpr};
use rustango::tenancy::Principal;
use rustango::viewset::{match_nothing, ViewSetFilter};
struct OwnerFilter;
impl ViewSetFilter for OwnerFilter {
// No principal in hand — fail closed. `vec![]` here would be *no filter*,
// not a filter matching nothing, and would widen the query to every row.
fn filter(&self, _p: &HashMap<String, String>, schema: &'static ModelSchema) -> Vec<WhereExpr> {
vec![match_nothing(schema)]
}
fn filter_with(
&self,
parts: &Parts,
_p: &HashMap<String, String>,
schema: &'static ModelSchema,
) -> Vec<WhereExpr> {
let Some(principal) = Principal::from_parts(parts) else {
return vec![match_nothing(schema)];
};
vec![WhereExpr::Predicate(Filter::new(
schema.field("owner_id").expect("owner_id").column,
Op::Eq,
SqlValue::from(principal.user_id),
))]
}
}
ViewSet::for_model(Note::SCHEMA, &["id", "body"])
.filter_backend(OwnerFilter)
.tenant_router("/api/notes")
filter_with fällt standardmäßig auf filter zurück, sodass ein Backend, das die Anfrage nicht braucht
— einschließlich der schlichten Closure-Form — nur filter wie zuvor implementiert.
match_nothing ist der Fail-closed-Zweig, und es lohnt sich, ihn zu verwenden
statt selbst zu bauen: er liefert col IS NULL AND col IS NOT NULL, einen
Widerspruch, der keine Parameter bindet und auf jedem Backend gleich lautet.
Exportiert ist er überhaupt deshalb, weil der naheliegende Ersatz ein leerer
Vec ist — und in einer Filter-API bedeutet vec![] kein Filter, also das
Gegenteil dessen, wofür der Zweig da ist.
Einbinden
Setze den Router des ViewSets in deine App ein. Single-Tenant, statischer Pool:
let api = urls::api()
.merge(PostViewSet::router("/api/posts", pool.clone())) // macro
.merge(ViewSet::for_model(Author::SCHEMA, &["id", "name"]).router("/api/authors", pool.clone())); // builder
Multi-Tenant (kein Pool erfasst — jede Anfrage löst ihre Mandantenverbindung auf):
let api = urls::api()
.merge(ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"]).tenant_router("/api/posts"));
make:api_routes <app> generiert eine api() pro App, die diese
.merge(...)-Zeilen sammelt. Sie nimmt den Pool, also binde sie in main.rs mit
.nest_with("/api", |pool| myapp::<app>::api_routes::api(pool)) ein; die
--tenant-Variante nimmt keinen und wird in urls.rs gemergt.
Backend-Unterstützung
- Builder +
router/tenant_routerist tri-dialektfähig — PostgreSQL, SQLite und MySQL — und ist der empfohlene Weg. - Das
router(prefix, pool)des Derive-Makros nimmtimpl Into<rustango::sql::Pool>— einenPgPool,MySqlPool,SqlitePooloder dasPool-Enum. Es ist nicht Postgres-only. - Serializer-Eingabe + -Ausgabe funktioniert jetzt auf allen drei Backends (das Rendern pro Zeile ist tri-dialektfähig; das alte PG-only-Gate ist weg).
- Filterung, Suche, Sortierung, die drei Paginierungsmodi, Berechtigungen, Drosselung und Bulk-Create funktionieren alle über die unterstützten Backends hinweg auf dem Builder-Pfad.
Probier es aus
Der obige End-to-End-Ablauf spiegelt das kompilierbare getting_started_blog-Beispiel
(Schritte 12–13 der Erste-Schritte-Anleitung). Die
eigenen Live-Tests des Frameworks unter crates/rustango/tests/viewset_*.rs sind die
vollständigste lauffähige Referenz — einschließlich der Serializer-Eingabe-/Ausgabe-Tests.
Sie laufen auf In-Memory-SQLite, brauchen aber die passenden Feature-Flags, z. B.:
cd crates/rustango
cargo test --features sqlite,tenancy --test viewset_serializer_render_sqlite_live
cargo test --features sqlite,tenancy --test viewset_serializer_input_sqlite_live
cargo test --features sqlite,tenancy --test viewset_sqlite_live
Siehe auch
- Serializer — forme das JSON, das ein ViewSet sendet und validiert.
- HTML-Views — das servergerenderte Gegenstück zu dieser JSON-API.
- OpenAPI — generiere eine Spezifikation + Swagger-UI aus deinen ViewSets.
- URLs & Routing — setze ViewSet-Router in deine App ein.
![Ein Rustango-ViewSet, verdrahtet mit einem Serializer: Ein einziger #[viewset(serializer = …)]-Block liefert typisierte JSON-Ausgabe und validierte Eingabe über die sechs CRUD-Routen hinweg](/static/img/viewsets.png)