Rustango docs
← Anleitungen

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.

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

Quelle: rustango::viewset (ViewSet, #[derive(ViewSet)], die #[viewset(...)]-Optionen + der for_model-Builder) — hinter admin oder tenancy gated. Darin braucht .serializer::<S>() das Feature serializer, tenant_router() / OwnedBy brauchen tenancy, und die QUERY-Aktion braucht admin.

Lauffähige Version: Der hier gebaute Blog spiegelt das getestete, kompilierbare getting_started_blog- Beispiel (dessen Post / PostSerializer / PostViewSet), und jedes Verhalten ist durch die eigenen Live-Tests des Frameworks abgesichert — crates/rustango/tests/viewset_*.rs (insbesondere viewset_serializer_render_sqlite_live und viewset_serializer_input_sqlite_live).


Inhaltsverzeichnis


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
Modulrustango::viewsetrustango::template_views
Sendet zurückJSON-Dateneine servergerenderte HTML-Seite
Gebaut fürSPAs, Mobile, andere DiensteBrowser, servergerenderte Websites, admin-artiges CRUD
Ein „Erstellen"POST JSON → 201 + das ObjektPOST eines Formulars → 303-Weiterleitung (Post/Redirect/Get)
Bei ungültiger Eingabe400 ApiError; Serializer-Fehler 422, Felder in detailsdas Formular mit angezeigten Fehlern neu rendern
Eine „Liste" istein paginierter JSON-Umschlageine Schleife über Zeilen in deinem Template
Üblicherweise authentifiziert perTokens / JWT / API-KeysSession-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.

fields ist Pflicht: Es ist die Schreib-Allowlist, ein Body kann also keine andere Spalte setzen (etwa author_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-FeldWirkung 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 (über select_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:

  1. Die Validierung läuft. Das validate() des Serializers — jedes einzelne #[serializer(validate = "fn")] pro Feld plus das feldübergreifende validate auf Container- Ebene — läuft gegen den JSON-Body. Bei Fehlschlag wird die Anfrage abgelehnt mit 422 Unprocessable Entity (validation_failed) und der feldgeschlüsselten Fehlerform in details: ein JSON-Objekt mit dem Feldnamen als Schlüssel und Arrays von Meldungen, z. B. {"title":["title must be at least 3 characters"]}.
  2. Filterung schreibbarer Felder. Nur die schreibbaren Felder des Serializers werden gespeichert; read_only- und method-/berechnete Felder, die ein Client postet, werden ignoriert (nicht geschrieben), und source-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:

VerbPfadAktionErfolgBody
GET/api/postslist200paginierter Umschlag (siehe Paginierung)
POST/api/postscreate201das erstellte Objekt — oder ein Array bei Bulk-Create
GET/api/posts/{pk}retrieve200das Objekt
PUT/api/posts/{pk}update (vollständig)200das aktualisierte Objekt
PATCH/api/posts/{pk}partial update200das aktualisierte Objekt (nur gelieferte Felder ändern sich)
DELETE/api/posts/{pk}destroy204leer

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 INSERT ohne Transaktion, sodass ein Unique- oder Fremdschlüsselverstoß bei Element 5 die Elemente 0–4 committete, 400 bulk entry 5 zurü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üsselBeispielStandardWas er tut
modelmodel = PosterforderlichDas Model, auf dem die Ressource aufbaut.
serializerserializer = path::To::SkeinerEinen Serializer für typisierte Ausgabe + Eingabe verdrahten (siehe oben).
fields"id, title, body"PflichtDie 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"keinerFelder, die die ?search=-Box durchsucht (Groß-/Kleinschreibung-unabhängiges ODER).
ordering"-published_at, id"keinerStandardsortierung (- = DESC).
page_size2020Zeilen pro Seite (Client-?page_size= gedeckelt bei 100).
read_only(Flag)ausNur GET (list + retrieve) exponieren.
allow_anonymous(Flag)ausErklärt, dass Schreibaktionen ohne Codenamen offen sein sollen; ohne es (oder read_only) verweigern sie das Einhängen.
permissions(...)permissions(create = "posts.add")keinerBerechtigungs-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:

MethodeZweck
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 zudem COUNT(*) 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 das max_length / min / max / choices des Models. So wird eine #[rustango(max_length = 200)]-Spalte an der API längengeprüft, ohne zusätzliche Konfiguration, wodurch potenzielle 500er aus DB-Constraints in freundliche 422er mit details verwandelt werden wie {"title":["Ensure this value has at most 200 characters."]}.
  • Pro-Feld- validate = "fn" und ein feldübergreifender validate-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 einen 400, der das Feld nennt.
  • Erforderlich / NOT NULL — ein fehlendes nicht-nullbares Feld (oder ein leerer String für einen nicht-nullbaren String) ergibt einen 400; nullbare Felder akzeptieren leer → NULL. In einem JSON-Body ist nur null gleich NULL: "" auf einem nullbaren String bleibt "".
  • 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 400 beim 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}
  • error ist ein stabiler Code (bad_request, unauthorized, not_found, validation_failed, rate_limited, internal_error, …). Verzweige darüber.
  • Serializer-Validierung ist ein 422 validation_failed, mit der Feld-Map in details: {"title": ["Ensure this value has at most 200 characters."], "non_field_errors": [ … ]}. Die oben genannten 400er aus Typkonvertierung und Pflichtfeldern sind bad_request mit dem Grund in message; ein 400 aus einem Datenbank-Constraint hält den Treibertext zurück.
  • Ein 5xx trägt nie die Ursache, außer RUSTANGO_DISCLOSE_ERRORS ist gesetzt. Sie wird geloggt; message ist 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_only oder allow_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_router ist tri-dialektfähig — PostgreSQL, SQLite und MySQL — und ist der empfohlene Weg.
  • Das router(prefix, pool) des Derive-Makros nimmt impl Into<rustango::sql::Pool> — einen PgPool, MySqlPool, SqlitePool oder das Pool-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.