Основы библиотеки Circe или простой JSON-парсер на Scala

Всем привет!

Во время нашей работы часто приходится сталкиваться с таким форматом обмена данных как JSON, и на данный момент существует большое количество различных библиотек для JSON сериализации. Конечно, для любителей языка программирования Scala, которые хотят использовать преимущества этого языка, тоже есть такая библиотека – о ней и пойдёт речь в данной статье.

Официальная ссылка на библиотеку Circe:

https://circe.github.io/circe/

Для тех, кто хочет сразу же посмотреть, что получится в ходе статьи, добро пожаловать на GitHub со всем кодом, который рассмотрим далее.

Circe: Libraries

Для знакомства с Circe в рамках данной статьи нам понадобятся следующие библиотеки:

1. Circe-core

2. Сirce-generic

3. Сirce-parser

В данной статье была использована версия Circe — 0.12.3

Circe: Parsing

Стоит начать с простого парсинга. Для этого создадим метод, который будет превращать обыкновенную строку в JSON-объект.

В Circe это реализовано весьма просто:

def parseToJson(data: String): Either[ParsingFailure, Json] = parse(data)

parse(str) – это метод, который уже находится в Circe и при попытке превратить нашу строку в JSON-объект, он возвращает результат в обертке Either, что позволяет получить JSON-объект или ошибку, которая возникла при парсинге.

Давайте убедимся в том, что это работает. Для примера возьмём актера, его пол и список фильмов, в которых он играл:

val simplyStr: String =   """       |{       |    "name": "Leonardo Dicaprio",       |    "sex":  "male",       |    "films": [       |      "Titanic",       |      "The Wolf of Wall Street",       |      "The Revenant"       |    ]       |  }       |""".stripMargin  val parseJsonRes: Either[ParsingFailure, Json] = JsonFormatter.parseToJson(simplyStr)

После запуска приложения видим, что все работает корректно:

Right({   "name" : "Leonardo Dicaprio",   "sex" : "male",   "films" : [     "Titanic",     "The Wolf of Wall Street",     "The Revenant"   ] })

Если же в работе мы встретим строку в виде JSON Array, то нам нужно парсить это немного иначе. Для парсинга таких объектов нам понадобится новый метод, который будет выглядеть следующим образом:

def parseToJsonList(data: String): Either[ParsingFailure, List[Json]] =   parse(data).map(json => json.asArray.toList.flatten)

В данном случае мы используем внутренний метод Circe – asArray, который приводит наш JSON к коллекции, а мы уже конвертируем его в нужный нам List.

Для примера возьмем строку, которая будет содержать список актеров. Выглядеть она будет примерно так:

val listSimplyStr: String =   """     |[     |{     |    "name": "Leonardo Dicaprio",     |    "sex":  "male",     |    "films": [     |      "Titanic",     |      "The Wolf of Wall Street",     |      "The Revenant"     |    ]     |  },     |  {     |    "name": "Chloe Grace Moretz",     |    "sex":  "female",     |    "films": [     |      "The Equalizer",     |      "Carrie",     |      "Movie 43"     |    ]     |  }     |  ]     |""".stripMargin  val parseJsonListRes = JsonFormatter.parseToJsonList(listSimplyStr)

Давайте посмотрим, что показывает нам консоль при запуске приложения:

Right(List({   "name" : "Leonardo Dicaprio",   "sex" : "male",   "films" : [     "Titanic",     "The Wolf of Wall Street",     "The Revenant"   ] }, {   "name" : "Chloe Grace Moretz",   "sex" : "female",   "films" : [     "The Equalizer",     "Carrie",     "Movie 43"   ] }))

Как можно заметить, в консоль вывелось то, что и ожидалось, а именно – List состоящий из двух объектов типа JSON.

На этом с базовым парсингом мы разобрались и теперь можем перейти к более сложным вещам: к таким понятиям, как декодинг и энкодинг в Circe.

Circe: Decoding and Encoding

Circe, как и любая иная библиотека, работающая с JSON-форматом, умеет конвертировать JSON в класс и обратно. Она предлагает такие виды конвертации, как автоматическая, полуавтоматическая и ручная. Об этом мы и поговорим далее.

Для конвертации Circe использует классы Encoder и Decoder – для кодирования и декодирования соответственно.

Encoding

Для демонстрации конвертации класса в строку нам понадобится следующий метод:

def convertToJsonString[T: Encoder](obj: T): String = Encoder[T].apply(obj).noSpaces

Как видно из кода выше, Circe из коробки предлагает нам готовый вариант решения нашей задачи по конвертации класса в JSON. Для того, чтобы превратить наш JSON в строку, достаточно вызвать noSpace, благодаря которому мы преобразуем JSON в обычную строку.

Decoding

Для демонстрации конвертации строки в класс нам понадобится следующий метод:

def convertToObj[T: Decoder](data: String): Either[circe.Error, T] = decode[T](data)

Здесь, мы возьмем готовый вариант библиотеки без каких-либо изменений. Наши функции выглядят довольно просто, но есть одно «но»: для того, чтобы они заработали, нам необходимо создать специальные конверторы.

Примеры классов для обмена информацией

Создадим пару кейс-классов, которые могли бы использоваться для простейшего обмена информацией:

case class PersonInfo(sex: String, age: Int, marital_status: Option[String])  case class Actor(name: String, info: PersonInfo)

Именно на этих классах мы и будем пробовать различные виды конвертации.

Ручная конвертация

Для того, чтобы продемонстрировать работу ручной конвертации, создадим два трейта, один из которых будет отвечать за превращение нашего кейс-класса в строку (ManualEncoders), а другой –за превращение строки в кейс-класс (ManualDecoders). Далее оба этих трейта объединим в один ManualConverter.

Manual Decoder

ManualDecoders будет выглядеть следующим образом:

trait ManualDecoders {    implicit val personInfoDecoder: Decoder[PersonInfo] = (hCursor: HCursor) =>     for {       sex            <- hCursor.get[String]("sex")       age            <- hCursor.get[Int]("age")       marital_status <- hCursor.get[Option[String]]("marital_status")     } yield PersonInfo(sex, age, marital_status)    implicit val actorDecoder: Decoder[Actor] = (hCursor: HCursor) =>     for {       name       <- hCursor.get[String]("name")       personInfo <- hCursor.get[PersonInfo]("info")     } yield Actor(name, personInfo) }

Давайте немного поговорим о том, что же здесь происходит. Мы создаём имплиситы для каждого кейс-класса, которые будут подтягиваться в наш convertToObj, чтобы он понимал – как именно конвертировать эти объекты. Для этого нам необходимо задействовать объект типа Hcurcor.

Если представить процесс его работы, то Hcursor представляет собой некую точку, которая может ходить по-нашему JSON-объекту как по дереву. После того, как она пробежалась по нему, создаются взаимосвязи в виде ключ-значение. Тем самым Hcursor может помочь нам извлечь необходимую информацию. По сути, когда мы говорим о Circe, любой процесс имеет этот курсор, просто ранее он был скрыт под верхнеуровневым API. Но при создании декодера нам потребуется спустится на уровень ниже, где он нам и понадобится.

После создания курсора, используя for-comprehension, мы начнём создавать наш объект. Просим выдать некие значения по определенным ключам, которые были найдены после просмотра дерева Hcursor и превратить полученное значение в необходимый нам тип данных. Получив все значения, создаём из них необходимый нам класс.

Наш ручной Decoder готов и мы можем двигаться дальше.

Manual Encoder

Теперь создадим ручной Encoder. Он будет выглядеть следующим образом:

trait ManualEncoders {    implicit val personInfoEncoder: Encoder[PersonInfo] = info =>     Json.obj(       "sex"            -> info.sex.asJson,       "age"            -> info.age.asJson,       "marital_status" -> info.marital_status.asJson     )    implicit val actorEncoder: Encoder[Actor] = actor =>     Json.obj(       "name" -> actor.name.asJson,       "info" -> actor.info.asJson     ) }

Здесь мы снова создаем имплиситы, которые будут подтягиваться в наш convertToJsonString.

Взяв наш класс PersonInfo и обозначив его info, начнём создавать наш JSON-объект. Этот метод принимает tuples вида (String, Json), таким образом мы создаём ключи в нашем JSON-объекте из строк в левой части, а их значения получаем из полей объектов кейс-классов, приведенных к JSON в правой части.

Наш ручной Encoder также готов.

Manual Converter

Таким образом, все готово для ручного конвертера. Теперь объединим оба наших трейта в готовый конвертер для классов Actor, PersonalInfo и можем использовать его там, где он понадобится:

trait ManualConverter extends ManualEncoders with ManualDecoders

Запустим приложение, чтобы убедится, что все работает:

object CirceApp extends App with ManualConverter {  val actor: Actor =   Actor("Leonardo Dicaprio", PersonInfo("male", 46, None))  // Encoding val actorJson: String = JsonFormatter.convertToJsonString[Actor](actor)  val infoJson: String = JsonFormatter.convertToJsonString[PersonInfo](actor.info)  // Decoding val actorObj: Either[circe.Error, Actor] = JsonFormatter.convertToObj[Actor](actorJson)  val infoObj: Either[circe.Error, PersonInfo] = JsonFormatter.convertToObj[PersonInfo](infoJson)

Проверим Encoding:

Convert Obj to Json String:  {"name":"Leonardo Dicaprio","info":{"sex":"male","age":46,"marital_status":null}}  {"sex":"male","age":46,"marital_status":null}

Проверим Decoding:

Convert String to Obj:  Right(Actor(Leonardo Dicaprio,PersonInfo(male,46,None)))  Right(PersonInfo(male,46,None))

Как видно из результатов, все работает корректно.

На этом с ручной конвертацией разобрались, теперь можем переходить к полуавтоматической.

Полуавтоматическая конвертация

Ручная конвертация требует написания большого количества шаблонного кода и для того, чтобы избежать этого, Сirce предлагает полуавтоматическую конвертацию. Нам снова понадобится три трейта, но выглядеть они будут куда проще.

Semi-automatic Decoder

Полуавтоматический декодер выглядит так:

trait SemiAutomaticDecoder {    implicit val personInfoDecoder: Decoder[PersonInfo] = deriveDecoder[PersonInfo]    implicit val actorDecoder: Decoder[Actor]           = deriveDecoder[Actor]  }

Здесь всего пару коротких имплиситов для классов, которые нам необходимо конвертировать, но присутствует специальный вид декодера, который нам необходимо импортировать:

import io.circe.generic.semiauto.deriveDecoder

Наш полуавтоматический декодер готов.

Semi-automatic Encoder

Давайте взглянем на Encoder:

trait SemiAutomaticEncoder {    implicit val personInfoEncoder: Encoder.AsObject[PersonInfo] = deriveEncoder[PersonInfo]   implicit val actorEncoder: Encoder.AsObject[Actor]           = deriveEncoder[Actor]  }

И его импорты:

import io.circe.generic.semiauto.deriveEncoder

Здесь все то же самое, что и в декодере, только происходит обратный процесс. Наш полуавтоматический энкодер тоже готов.

Semi-automatic Converter

Для полуавтоматического конвертера все готово, остаётся снова объединить оба наших трейта в готовый конвертер:

trait SemiAutomaticConverter extends SemiAutomaticEncoder with SemiAutomaticDecoder

После чего нужно заменить наш ручной конвертер на полуавтоматический:

object CirceApp extends App with SemiAutomaticConverter

Ну, и запустить то же самое приложение, в котором мы использовали ручной конвертер.

Мы получим абсолютно такой же результат:

Convert Obj to Json String:  {"name":"Leonardo Dicaprio","info":{"sex":"male","age":46,"marital_status":null}}  {"sex":"male","age":46,"marital_status":null}   Convert String to Obj:  Right(Actor(Some(Leonardo Dicaprio),Some(PersonInfo(Some(male),Some(46),None))))  Right(PersonInfo(Some(male),Some(46),None))

Semi-automatic Union Converter (Codec)

Также в Circe при создании конвертеров в полуавтоматическом режиме есть возможность не писать отдельно энкодер и декодер: достаточно сделать общий Codec, который представляет собой объединенные вместе энкодер и декодер.

Выглядит он так:

import io.circe.generic.semiauto.deriveCodec  trait SemiAutomaticUnionConverter {    implicit val personInfoEncoder: Codec.AsObject[PersonInfo] = deriveCodec[PersonInfo]    implicit val actorEncoder: Codec.AsObject[Actor] = deriveCodec[Actor]  }

Благодаря чему мы можем не создавать общий трейт для объединения энкодера и декодера, а сразу использовать его, потому что он подходит как для операции превращения классов в JSON, так и обратно.

На этом с полуавтоматической конвертацией мы разобрались и нам остается последний вид конвертации, о котором мы поговорим далее.

Автоматическая конвертация

Предыдущий вид конвертации был достаточно прост, но Circe может упростить этот процесс еще больше.

Для работы автоматической конвертации нам не потребуется создавать каких-либо трейтов с имплиситами, а лишь потребуется одна маленькая деталь. Именно там, где нужно применять метод конвертации, нам нужно импортировать следующее:

import io.circe.generic.auto._

Благодаря этому импорту Circe в автоматическом режиме генерирует все, что необходимо для конвертации.

Уберем все наши ранее используемые трейты и оставим только один импорт автоматического генератора:

import io.circe.generic.auto._  object CirceApp extends App 

Попробуем запустить наше приложение и снова убедимся в том, что все отработало как полагается:

Convert Obj to Json String:  {"name":"Leonardo Dicaprio","info":{"sex":"male","age":46,"marital_status":null}}  {"sex":"male","age":46,"marital_status":null}   Convert String to Obj:  Right(Actor(Some(Leonardo Dicaprio),Some(PersonInfo(Some(male),Some(46),None))))  Right(PersonInfo(Some(male),Some(46),None))

Как можно заметить, все на месте и ничего не отличается от вышеиспользуемых конверторов.

Какую конвертацию выбирать – дело за вами. Все они работают, вопрос лишь в том – как вы планируете использовать конвертор для решения своих задач.