Routing¶

Beim Routing geht es um das Verteilen der eingehenden Serveranfragen, an die richtigen Anwendungsendpunkte. Endpunkte sind Einheiten zur Verarbeitung der Anfragen. Sie werden im Controller definiert und beim Starten der Anwendung registriert.

Grundlagen¶

Um das Ganze besser zu verstehen, werfen wir einen Blick auf den Aufbau einer solchen Serveranfrage.

GET /hello/vapor HTTP/1.1
host: vapor.codes
content-length: 0

Im Beispiel handelt es sich eine typische Anfrage an die URL /hello/vapor/. Die selbe Anfrage wird erstellt, wenn wir im Browser folgenden Link aufrufen:

http://vapor.codes/hello/vapor

Anfragemethode¶

Ganz am Anfang der Serveranfrage steht die Anfragemethode. Wie im Beispiel, ist GET die meistgenutzte Methode, jedoch gibt es noch weitere Methoden, die zumeist in Verbindung mit CRUD zum Einsatz kommen.

Methode	Aktion	Beschreibung
GET	Read	Daten werden vom Server angefordert.
POST	Create	Daten werden an den Server gesendet.
PUT	Replace	Daten werden an den Server gesendet.
PATCH	Update	Daten werden an den Server gesendet
DELETE	Delete	Daten werden vom Server gelöscht.

Anfragepfad¶

Auf die Methode folgt der Zielpfad der Anfrage. Die Zielpfad besteht aus einem Pfad und einer optionalen Zeichenabfolge ?. Vapor benutzt beides um die Anfrage an den richtigen Endpunkt weiterzuleiten.

Endpunktmethoden¶

Vapor stellt alle Anfragemethoden als Methoden über die Application-Instanz zur Verfügung. Die Methoden akzeptieren einen oder mehrere Pfadangaben vom Typ String, die nachfolgend mit einem '/' getrennt zu einem Pfad zusammengestellt werden.

/// [controller.swift]

app.get("hello", "vapor") { req in 
    return "Hello, vapor!"
}

/// Die .on()-Variante ist ebenfalls möglich.
app.on(.GET, "hello", "vapor") { ... }

HTTP/1.1 200 OK
content-length: 13
content-type: text/plain; charset=utf-8

Hello, vapor!

Endpunktargumente¶

Durch das Voransetzen eines Doppelpunktes vor Parameterangabe zum Beispiel :name, erkennt Vapor, dass es sich hierbei um einem variablen Angabe handeln soll und somit jeder Parameter von Typ String akzeptiert wird. Über die Eigenschaft Parameters können wir nun auf den Angabe zugreifen.

/// [controllers.swift]

app.get("hello", ":name") { req -> String in
    let name = req.parameters.get("name")!
    return "Hello, \(name)!"
}

Wenn wir nun die Anfrage im Beispiel erneut ausführen, bekommen wir immer noch die selbe Antwort. Allerdings können wir nun hinter /hello/ einen beliebige Angabe machen, zum Beispiel /hello/swift und bekommen folgende Antwort zurück:

GET /hello/swift HTTP/1.1
content-length: 0

HTTP/1.1 200 OK
content-length: 13
content-type: text/plain; charset=utf-8

Hello, swift!

Nachdem wir uns die Einführung angesehen haben, können wir uns den nachfolgenden Abschnitten widmen.

Endpunktdefinition¶

Methoden¶

Endpunkte können der Anwendung über die Instanz Application und den Methoden bekannt gemacht werden.

// [controllers.swift]

app.get("foo", "bar", "baz") { req in
    ...
}

Die Methode kann auch mit einem Rückgabewert versehen werden. Der Rückgabewert muss zwingend vom Typ ResponseEncodable sein.

app.get("foo") { req -> String in
    return "bar"
}

// responds to OPTIONS /foo/bar/baz
app.on(.OPTIONS, "foo", "bar", "baz") { req in
    ...
}

Argumente¶

Die Endpunktmethoden akzeptieren eine Vielzahl von Argumenten. Es gibt vier Arten davon

Konstanten
Parameter
Sternchen
Doppelsternchen

Konstante¶

Bei der Konstante handelt es sich um eine statische Angabe. Somit werden von der Methode nur Anfragen mit einem übereinstimmen Pfad angenommen.

// responds to GET /foo/bar/baz
app.get("foo", "bar", "baz") { req in
    ...
}

Parameter¶

Beim Parameter handelt sich um eine variable Angabe. Somit werden jegliche Angaben entgegegen genommen. Dem Parameter muss ein Doppelpunkt vorangestellt werden. Die Deklaration nach dem Doppelpunkt steht für den Parameternamen. Mit dem Namen können wir später den Wert abfragen.

// responds to GET /foo/bar/baz
// responds to GET /foo/qux/baz
// ...
app.get("foo", ":bar", "baz") { req in
    ...
}

Wenn wir einen Parameter festlegen, wird der Wert der Angabe in der Eigenschaft Parameters auf der Instanz Request abgelegt und kann über den Namen abgefragt werden.

// responds to GET /hello/foo
// responds to GET /hello/bar
// ...
app.get("hello", ":name") { req -> String in
    let name = req.parameters.get("name")!
    return "Hello, \(name)!"
}

Tip

We can be sure that req.parameters.get will never return nil here since our route path includes :name. However, if you are accessing route parameters in middleware or in code triggered by multiple routes, you will want to handle the possibility of nil.

Tip

If you want to retrieve URL query params, e.g. /hello/?name=foo you need to use Vapor's Content APIs to handle URL encoded data in the URL's query string. See Content reference for more details.

req.parameters.get also supports casting the parameter to LosslessStringConvertible types automatically.

// responds to GET /number/42
// responds to GET /number/1337
// ...
app.get("number", ":x") { req -> String in 
    guard let int = req.parameters.get("x", as: Int.self) else {
        throw Abort(.badRequest)
    }
    return "\(int) is a great number"
}

Sternchen¶

Für eine beliebige Angabe in einem Pfadabschnitt kann ein einfacher Asterisk angegeben werden. Es verhält sich ähnlich zu einer Parameterangabe, allerdings wird in diesem Fall der Wert verworfen.

// responds to GET /foo/bar/baz
// responds to GET /foo/qux/baz
// ...
app.get("foo", "*", "baz") { req in
    ...
}

Doppelsternchen¶

Für eine beliebige Angabe über mehrere Pfadabschnitte hinweg, können zwei Asterisk angegeben werden.

// responds to GET /foo/bar
// responds to GET /foo/bar/baz
// ...
app.get("foo", "**") { req in 
    ...
}

Werte, die mit dem Pfadabschnitt übereinstimmen werden in der Eigenschaft parameters abgelegt und können mit der Methode getCatchall(:) abgerufen werden.

// responds to GET /hello/foo
// responds to GET /hello/foo/bar
// ...
app.get("hello", "**") { req -> String in
    let name = req.parameters.getCatchall().joined(separator: " ")
    return "Hello, \(name)!"
}

Verarbeitung¶

Wenn wir einen Endpunkt mit der Methode on(:) festlegen, können wir definieren, wie mit dem Inhalt umgegangen werden soll. Standardmäßig wird der Inhalt zwischengespeichert, bevor er an den Endpunkt übergeben wird. Das ist hilfreich, da Vapor den Anfrageinhalt nacheinander arbeiten kann, während zeitlgeich neue Anfrage eintreffen.

Vapor hat standardmäßig das Limit auf 16 KB festgelegt. Wir können allerdings den Wert mit der Eigenschaft Routes für alle Endpunkte überschreiben:

// Increases the streaming body collection limit to 500kb
app.routes.defaultMaxBodySize = "500kb"

Wenn das Limit erreicht wird, wird ein Fehler 413 (413 Payload Too Lage) ausgeworfen.

Der Wert kann aber auch für einen einzelnen Endpunkt abgeändert werden. Hierzu müssen wir der Methode beim Parameter body: einen Wert mitgeben. Wenn ein neuer Maximalwert mit angegeben wird, wird der Standardwert für den Endpunkt überschrieben.

// Collects streaming bodies (up to 1mb in size) before calling this route.
app.on(.POST, "listings", body: .collect(maxSize: "1mb")) { req in
    // Handle request. 
}

Bei leistungsintensivere Aufgaben, wie zum Beispiel das Hochladen von Dateien, kann das Zwischenspeichern des Inhalts den Arbeitsspeicher stark beanspruchen, daher ist es zu empfehlen, den Inhalt eher zu stream. In dem Fall bleibt req.body.data leer und die Daten müssen mit req.body.drain Stück für Stück entgegengenommen werden.

// Request body will not be collected into a buffer.
app.on(.POST, "upload", body: .stream) { req in
    ...
}

Groß- und Kleinschreibung¶

Grundsätzlich muss bei Endpunkten die Groß- und Kleinschreibung beachten werden. Bei Konstanten kann allerdings eine Ausnahme gemacht werden.

app.routes.caseInsensitive = true

Ansicht¶

Über die Eigenschaft all kann auf die Endpunkte zugegriffen werden.

print(app.routes.all) // [Route]

Vapor also ships with a routes command that prints all available routes in an ASCII formatted table.

$ swift run App routes
+--------+----------------+
| GET    | /              |
+--------+----------------+
| GET    | /hello         |
+--------+----------------+
| GET    | /todos         |
+--------+----------------+
| POST   | /todos         |
+--------+----------------+
| DELETE | /todos/:todoID |
+--------+----------------+

Metadaten¶

Alle Endpunktmethoden liefern ein Objekt von Typ Route zurück. Damit können wir ihr Metadaten über die Sammlung userInfo mitgeben oder andere vordefinierte Methoden verwenden wie zum Beispiel, hinzufügen einer Beschreibung:

app.get("hello", ":name") { req in
    ...
}.description("says hello")

Endpunktgruppen¶

Endpunkte können zu Gruppen zusammengefasst werden. Der Name der Gruppe wird als Pfadabschnitt den enhaltenen Endpunkten vorangestellt.

let users = app.grouped("users")
// GET /users
users.get { req in
    ...
}
// POST /users
users.post { req in
    ...
}
// GET /users/:id
users.get(":id") { req in
    let id = req.parameters.get("id")!
    ...
}

app.group("users") { users in
    // GET /users
    users.get { req in
        ...
    }
    // POST /users
    users.post { req in
        ...
    }
    // GET /users/:id
    users.get(":id") { req in
        let id = req.parameters.get("id")!
        ...
    }
}

Untergruppen¶

Gruppen können wiederum verschachteln werden.

app.group("users") { users in
    // GET /users
    users.get { ... }
    // POST /users
    users.post { ... }

    users.group(":id") { user in
        // GET /users/:id
        user.get { ... }
        // PATCH /users/:id
        user.patch { ... }
        // PUT /users/:id
        user.put { ... }
    }
}

Middleware¶

Gruppen können zudem mit Middlewares versehen werden.

app.get("fast-thing") { req in
    ...
}
app.group(RateLimitMiddleware(requestsPerMinute: 5)) { rateLimited in
    rateLimited.get("slow-thing") { req in
        ...
    }
}

app.post("login") { ... }
let auth = app.grouped(AuthMiddleware())
auth.get("dashboard") { ... }
auth.get("logout") { ... }

Weiterleitung¶

Für eine Weiterleitung kann es verschiedenste Gründe geben. Mit der Methode redirect(_:) über die Instanz Request können wir die Anfrage weiterleiten.

req.redirect(to: "/some/new/path")

/// redirect a page permanently
req.redirect(to: "/some/new/path", redirectType: .permanent)

Es gibt verschiedene Arten von Weiterleitungen:

Art	Statuscode	Beschreibung
permanent	301	Liefert einen Statuscode 301 zurück.
normal	303	This is the default by Vapor and tells the client to follow the redirect with a GET request.
temporary	307	This tells the client to preserve the HTTP method used in the request.
To choose the proper redirection status code check out the full list