Endpoints JSON

http4s integra JSON mediante el módulo http4s-circe, que conecta los codecs de circe con EntityDecoder y EntityEncoder. circe es la biblioteca JSON funcional de facto para Scala.

Defina instancias de Encoder y Decoder para sus tipos y deje que http4s gestione el formato de transmisión.

Con circe-generic puede derivar codecs automáticamente mediante deriveEncoder/deriveDecoder o la anotación @JsonCodec. Estos asocian los campos de las case classes con las claves JSON por nombre.

La derivación necesita codecs para todos los tipos de los campos, de forma recursiva.

La importación org.http4s.circe.CirceEntityEncoder._ proporciona un EntityEncoder[F, A] implícito para cualquier A que tenga un Encoder de circe. Entonces Ok(user) se serializa como JSON con application/json.

No es necesario convertir manualmente el valor a Json en los handlers.

Es la operación inversa: org.http4s.circe.CirceEntityDecoder._ proporciona un EntityDecoder[F, A] para cualquier A que tenga un Decoder de circe. Entonces req.as[User] analiza el cuerpo JSON.

Ambas importaciones juntas se agrupan como CirceEntityCodec._.

Combinar la decodificación y la codificación permite crear un endpoint limpio: analice el JSON entrante como un tipo de dominio, ejecute la lógica de negocio y vuelva a codificar el resultado como JSON.

Los errores de decodificación aparecen como 422 o 400 mediante el decoder de circe.

Para JSON puntual, el interpolador de cadenas json de circe, procedente de io.circe.literal, construye directamente un valor Json con valores de Scala interpolados.

Es útil para respuestas pequeñas o datos de prueba sin una case class.

Cuando las claves JSON difieren de los nombres de los campos de Scala, derive el codec con una Configuration de circe-generic-extras, por ejemplo snake_case, o escríbalo manualmente con forProduct2.

Esto desacopla el contrato de su API de los nombres internos.

circe proporciona automáticamente codecs para List, Vector, Option y Map una vez que existe el codec de los elementos. Por tanto, devolver una colección funciona directamente.

Una lista vacía se codifica como [] y None como una clave ausente o como null.

La decodificación le proporciona un valor sintácticamente válido; la validación semántica es responsabilidad suya. Ejecute las comprobaciones después de as y detenga el procesamiento con BadRequest cuando el valor no sea válido.

Mantenga las invariantes del dominio en constructores inteligentes que devuelvan Either para mayor claridad.

Devuelva los errores estructurados como JSON para que los clientes puedan analizarlos. Defina una clase de caso para el error con un codificador de circe y pásela al constructor de estado correspondiente.

Las estructuras de error coherentes hacen que las API sean mucho más fáciles de consumir.

Para colecciones grandes, puede transmitir el JSON en lugar de almacenarlo en un búfer. jsonEncoderOf junto con un Stream[F, A] de fs2 emite un array JSON de forma incremental.

Esto mantiene estable el uso de memoria para conjuntos de resultados grandes y aprovecha el control de presión de fs2.

Recuerde qué import permite decodificar un cuerpo JSON en una clase de caso.

Configuró JSON con http4s-circe: derivó códecs, importó CirceEntityCodec y usó Ok(value) / req.as[A] para gestionar completamente la entrada y salida de JSON.

Gestionó listas, nombres de campos personalizados y errores JSON estructurados, e incluso arrays transmitidos para cargas grandes.