Requests und Responses

In http4s ist ein Request[F] ein unveränderlicher Wert mit Methode, URI, Headern, HTTP-Version und einem Streaming-Body. Sie untersuchen ihn mit reinen Zugriffsmethoden und verändern ihn niemals direkt.

Um eine Anfrage zu ändern, erstellen Sie mit withHeaders, withUri oder ähnlichen Kombinatoren eine Kopie.

Der Body einer Anfrage oder Antwort ist ein fs2.Stream[F, Byte]. Er wird verzögert und innerhalb eines Effekts verarbeitet, sodass große Nutzlasten nie vollständig im Speicher liegen müssen.

In der Regel greifen Sie nicht auf rohe Bytes zu; ein EntityDecoder übernimmt die Decodierung für Sie.

Ein EntityDecoder[F, A] weiß, wie der Body-Stream in ein A umgewandelt wird. Rufen Sie zum Decodieren req.as[A] auf. Das Ergebnis ist F[A], und bei einem fehlerhaften Body schlägt der Effekt fehl.

Für String gibt es einen integrierten Decoder; umfangreichere Decoder kommen aus JSON-Modulen.

Um innerhalb eines Falls auf das Anfrageobjekt zuzugreifen, binden Sie es mit @. Hier bezeichnet req die gesamte Anfrage, während das Muster weiterhin Methode und Pfad abgleicht.

Ohne den Binder stehen Ihnen nur die zerlegten Teile zur Verfügung, und Sie können weder den Body noch die Header lesen.

Header befinden sich in request.headers. Verwenden Sie headers.get[H] mit einem typisierten Header-Modell oder headers.get(CIString("X-Custom")) für beliebige Namen.

Typisierte Header wie Authorization und Content-Type parsen und validieren ihre Werte für Sie.

Die Antwort-Builder der DSL, etwa Ok, Created und NotFound, sind Funktionen, die F[Response[F]] zurückgeben. Durch die Übergabe eines Arguments wird der Body über einen EntityEncoder gesetzt.

Jeder Builder entspricht einem Statuscode, daher erzeugt Created(...) den Status 201.

Für einen Status ohne passenden Komfort-Builder oder zur individuellen Anpassung erstellen Sie eine Response[F] mit einem expliziten Status und verketten withEntity.

So haben Sie in einem Ausdruck vollständige Kontrolle über Status, Header und Body.

Ein EntityEncoder[F, A] serialisiert einen Wert in den Antwort-Body und setzt den Content-Type. Encoder für String und Bytes sind integriert; JSON-Encoder stammen aus Circe.

Wenn Sie Ok(value) einen Wert übergeben, sucht http4s implizit nach dem passenden Encoder.

Fügen Sie Header hinzu, indem Sie sie als zusätzliche Argumente an einen Builder übergeben, oder verketten Sie .map(_.putHeaders(...)) mit dem Antwort-Effekt.

Typisierte Header-Modelle stellen korrekt formatierte Werte sicher, beispielsweise einen Location-Header bei 201 Created.

req.as[A] lässt den F-Effekt fehlschlagen, wenn der Body nicht decodiert werden kann. Verwenden Sie req.attemptAs[A].value, um ein F[Either[DecodeFailure, A]] zu erhalten, und antworten Sie bei Left mit 400.

So bleibt die Behandlung fehlerhafter Eingaben explizit und total.

Setzen Sie Cookies mit response.addCookie(ResponseCookie(name, value)). Für Weiterleitungen verwenden Sie einen 3xx-Builder und einen Location-Header.

SeeOther(Location(uri)) führt zu 303, der idiomatischen Antwort für Post-Redirect-Get.

Denken Sie über das sichere Decodieren von Bodies nach.

Anfragen und Antworten sind unveränderliche Werte mit streamenden fs2-Bodies. Sie dekodieren sie mit as/attemptAs über EntityDecoder und kodieren sie mit EntityEncoder.

Builder legen Statuscodes fest, typisierte Header bleiben typsicher, und Cookies sowie Weiterleitungen sind lediglich Transformationen von Antworten.