JSON-Endpunkte
Kombinieren Sie http4s mit Circe.
JSON-Endpunkte ist eine kostenlose Scala for Backend Engineering & Functional Programming-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Scala for Backend Engineering & Functional Programming-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Scala for Backend Engineering & Functional Programming-Kurs umfasst insgesamt 4 Lektionen.
JSON mit circe
http4s integriert JSON über das Modul http4s-circe, das circe-Codecs mit EntityDecoder und EntityEncoder verbindet. circe ist die De-facto-Bibliothek für funktionales JSON in Scala.
Sie definieren Encoder- und Decoder-Instanzen für Ihre Typen und überlassen http4s die Verarbeitung des Übertragungsformats.
// build.sbt
// "org.http4s" %% "http4s-circe" % http4sV
// "io.circe" %% "circe-generic" % circeVCodecs ableiten
Mit circe-generic leiten Sie Codecs automatisch über deriveEncoder/deriveDecoder oder die Annotation @JsonCodec ab. Sie ordnen die Felder von Case Classes anhand ihrer Namen JSON-Schlüsseln zu.
Für die Ableitung werden rekursiv Codecs für jeden Feldtyp benötigt.
import io.circe.generic.semiauto._
case class User(id: Int, name: String)
implicit val enc = deriveEncoder[User]
implicit val dec = deriveDecoder[User]EntityEncoder aus circe
Der Import org.http4s.circe.CirceEntityEncoder._ stellt für jedes A mit einem circe-Encoder einen impliziten EntityEncoder[F, A] bereit. Anschließend serialisiert Ok(user) den Wert mit application/json als JSON.
In Handlern ist keine manuelle Konvertierung in Json erforderlich.
import org.http4s.circe.CirceEntityEncoder._
HttpRoutes.of[IO] {
case GET -> Root / "me" => Ok(User(1, "Ada"))
}EntityDecoder aus circe
Das Gegenstück dazu: org.http4s.circe.CirceEntityDecoder._ stellt für jedes A mit einem circe-Decoder einen EntityDecoder[F, A] bereit. Anschließend parst req.as[User] den JSON-Body.
Beide Imports zusammen sind als CirceEntityCodec._ gebündelt.
import org.http4s.circe.CirceEntityDecoder._
case req @ POST -> Root / "users" =>
req.as[User].flatMap(u => Created(u))Ein vollständiger JSON-POST
Durch die Kombination von Dekodierung und Kodierung entsteht ein übersichtlicher Create-Endpunkt: Sie parsen das eingehende JSON in einen Domänentyp, führen die Geschäftslogik aus und kodieren das Ergebnis anschließend wieder als JSON.
Dekodierungsfehler werden über den circe-Decoder als 422 oder 400 sichtbar.
import org.http4s.circe.CirceEntityCodec._
case req @ POST -> Root / "users" =>
for {
in <- req.as[User]
out <- store.create(in)
res <- Created(out)
} yield resDer json-Interpolator
Für situationsbezogenes JSON erstellt circes json-String-Interpolator aus io.circe.literal direkt einen Json-Wert, einschließlich interpolierter Scala-Werte.
Das ist nützlich für kleine Antworten oder Test-Fixtures ohne Case Class.
import io.circe.literal._
val body = json"""{ "status": "ok", "count": 3 }"""
Ok(body)Benutzerdefinierte Feldnamen
Wenn sich JSON-Schlüssel von den Scala-Feldnamen unterscheiden, leiten Sie die Codecs mit einer Configuration aus circe-generic-extras ab, etwa mit snake_case, oder schreiben den Codec mithilfe von forProduct2 selbst.
So entkoppeln Sie den API-Vertrag von der internen Benennung.
import io.circe.Encoder
implicit val e: Encoder[User] =
Encoder.forProduct2("user_id", "full_name")(u => (u.id, u.name))Listen kodieren
circe stellt automatisch Codecs für List, Vector, Option und Map bereit, sobald der Codec für die Elemente vorhanden ist. Daher funktioniert die Rückgabe einer Collection direkt.
Eine leere Liste wird als [] kodiert und None entweder als fehlender Schlüssel oder als null.
import org.http4s.circe.CirceEntityEncoder._
case GET -> Root / "users" =>
store.all.flatMap(us => Ok(us)) // List[User] -> JSON arrayDekodiertes JSON validieren
Die Dekodierung liefert Ihnen einen syntaktisch gültigen Wert; für die semantische Validierung sind Sie zuständig. Führen Sie die Prüfungen nach as aus und brechen Sie bei ungültigen Werten mit BadRequest ab.
Halten Sie Domäneninvarianten zur besseren Verständlichkeit in Smart Constructors fest, die Either zurückgeben.
req.as[User].flatMap { u =>
if (u.name.nonEmpty) Created(u)
else BadRequest("name required")
}Fehlerantworten als JSON
Geben Sie strukturierte Fehler als JSON zurück, damit Clients sie parsen können. Definieren Sie eine Fehler-Case-Class mit einem circe-Encoder und übergeben Sie sie an den entsprechenden Status-Builder.
Einheitliche Fehlerstrukturen machen APIs wesentlich leichter nutzbar.
case class ApiError(code: String, message: String)
implicit val e = deriveEncoder[ApiError]
BadRequest(ApiError("E_NAME", "name required"))Streaming von JSON
Für große Collections können Sie JSON streamen, statt es zwischenzuspeichern. jsonEncoderOf zusammen mit einem fs2-Stream[F, A] gibt ein JSON-Array schrittweise aus.
So bleibt der Speicherverbrauch auch bei großen Ergebnismengen konstant, indem der Backpressure-Mechanismus von fs2 genutzt wird.
import org.http4s.circe.streamJsonArrayEncoder
case GET -> Root / "feed" =>
Ok(store.streamAll) // fs2.Stream[IO, Event]Kurze Überprüfung
Erinnern Sie sich, welcher Import die Dekodierung eines JSON-Bodys in eine Case Class aktiviert.
Zusammenfassung
Sie haben JSON mit http4s-circe eingebunden: Sie haben Codecs abgeleitet, CirceEntityCodec importiert und Ok(value) / req.as[A] für vollständige JSON-Ein- und -Ausgabe verwendet.
Sie haben Listen, benutzerdefinierte Feldnamen und strukturierte JSON-Fehler verarbeitet und sogar Arrays für große Nutzdaten gestreamt.
Häufig gestellte Fragen
Ist die Lektion „JSON-Endpunkte“ kostenlos?
Ja — der vollständige Text von „JSON-Endpunkte“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Scala for Backend Engineering & Functional Programming-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Scala for Backend Engineering & Functional Programming-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „JSON-Endpunkte“?
Kombinieren Sie http4s mit Circe. Du übst Scala for Backend Engineering & Functional Programming mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um Scala for Backend Engineering & Functional Programming zu starten?
Keine Vorkenntnisse erforderlich. Scala for Backend Engineering & Functional Programming auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.
Wie lange dauert die Lektion „JSON-Endpunkte“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser Scala for Backend Engineering & Functional Programming-Lektion Code schreiben und ausführen?
Ja. Jede Scala for Backend Engineering & Functional Programming-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.