Json схема: навіщо і кому вона потрібна

Привіт, мандрівнику. Сьогодні я хочу розповісти тобі про невелику магію. Ти, мабуть, уже чув про json. Це така універсальна мова: її розуміє машина і легко читає людина. Ось типовий приклад json повідомлення:

{
   "помещение":{
      "название":"избушка",
      "разумна":true
   },
   "основание":{
      "тип":"курьи ноги",
      "количество":2
   },
   "проживающие":[
      {
         "ім'я":"Баба Яга",
         "профиль":"ведьма"
      }
   ],
   "местоположение":{
      "адреса":"граница леса"
   }
}

Адже зручно так спілкуватися, правда? Якщо ти не знав, що таке json, тепер знаєш. Як це використовувати в коді java? Json став універсальним форматом. Розшифровується він як JavaScript Object Notation, але вже давно вийшов за межі JavaScript і використовується майже скрізь. У java є кілька бібліотек, які спрощують роботу з json. Ось найвідоміші:

gson
Jackson

Я використовуватиму другу. Там їх 2 версії codehaus і fasterxml , відмінностей у них не помічав, тому тут можете використовувати будь-яку. Ось такий шматок коду:

ObjectMapper mapper = new ObjectMapper();
return mapper.readValue("сюда json", "сюда класс");

допоможе перевести json на об'єкт. І ми наближаємося до найголовнішого. Написання класу для цього json. Можна це робити руками, створити структуру приблизно таку:

-----------------------------------com.fairytale.Base.java-----------------------------------

package com.fairytale;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
"type",
"quantity"
})
public class Base {

@JsonProperty("type")
public String type = "";
@JsonProperty("quantity")
public int quantity = 0;

}
-----------------------------------com.fairytale.Hut.java-----------------------------------

package com.fairytale;

import java.util.ArrayList;
import java.util.List;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
"room",
"base",
"residents",
"location"
})
public class Hut {

@JsonProperty("room")
public Room room;
@JsonProperty("base")
public Base base;
@JsonProperty("residents")
public List<Resident> residents = new ArrayList<Resident>();
@JsonProperty("location")
public Location location;

}
-----------------------------------com.fairytale.Location.java-----------------------------------

package com.fairytale;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
"address"
})
public class Location {

@JsonProperty("address")
public String address = "";

}
-----------------------------------com.fairytale.Resident.java-----------------------------------

package com.fairytale;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
"name",
"profile"
})
public class Resident {

@JsonProperty("name")
public String name = "";
@JsonProperty("profile")
public String profile = "";

}
-----------------------------------com.fairytale.Room.java-----------------------------------

package com.fairytale;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;

@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
"name",
"reasonable"
})
public class Room {

@JsonProperty("name")
public String name = "";
@JsonProperty("reasonable")
public boolean reasonable = false;

}

Я спеціально опустив гетери, сетери, конструктори та інші атрибути pojo, інакше ти втомився б промотувати =) А тепер подивись сюди:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/root.json",
  "type": "object",
  "title": "The Root Schema",
  "required": [
    "room",
    "base",
    "residents",
    "location"
  ],
  "properties": {
    "room": {
      "$id": "#/properties/room",
      "type": "object",
      "title": "The Room Schema",
      "required": [
        "name",
        "reasonable"
      ],
      "properties": {
        "name": {
          "$id": "#/properties/room/properties/name",
          "type": "string",
          "title": "The Name Schema",
          "default": "",
          "examples": [
            "избушка"
          ],
          "pattern": "^(.*)$"
        },
        "reasonable": {
          "$id": "#/properties/room/properties/reasonable",
          "type": "boolean",
          "title": "The Reasonable Schema",
          "default": false,
          "examples": [
            true
          ]
        }
      },
	"additionalProperties": false
    },
    "base": {
      "$id": "#/properties/base",
      "type": "object",
      "title": "The Base Schema",
      "required": [
        "type",
        "quantity"
      ],
      "properties": {
        "type": {
          "$id": "#/properties/base/properties/type",
          "type": "string",
          "title": "The Type Schema",
          "default": "",
          "examples": [
            "курьи ноги"
          ],
          "pattern": "^(.*)$"
        },
        "quantity": {
          "$id": "#/properties/base/properties/quantity",
          "type": "integer",
          "title": "The Quantity Schema",
          "default": 0,
          "examples": [
            2
          ]
        }
      },
	"additionalProperties": false
    },
    "residents": {
      "$id": "#/properties/residents",
      "type": "array",
      "title": "The Residents Schema",
      "items": {
        "$id": "#/properties/residents/items",
        "type": "object",
        "title": "The Items Schema",
        "required": [
          "name",
          "profile"
        ],
        "properties": {
          "name": {
            "$id": "#/properties/residents/items/properties/name",
            "type": "string",
            "title": "The Name Schema",
            "default": "",
            "examples": [
              "Баба Яга"
            ],
            "pattern": "^(.*)$"
          },
          "profile": {
            "$id": "#/properties/residents/items/properties/profile",
            "type": "string",
            "title": "The Profile Schema",
            "default": "",
            "examples": [
              "ведьма"
            ],
            "pattern": "^(.*)$"
          }
        },
	    "additionalProperties": false
      }
    },
    "location": {
      "$id": "#/properties/location",
      "type": "object",
      "title": "The Location Schema",
      "required": [
        "address"
      ],
      "properties": {
        "address": {
          "$id": "#/properties/location/properties/address",
          "type": "string",
          "title": "The Address Schema",
          "default": "",
          "examples": [
            "граница леса"
          ],
          "pattern": "^(.*)$",
		  "additionalProperties": false
        }
      },
	"additionalProperties": false
    }
  },
	"additionalProperties": false
}

Це json схема структури вище. Тепер настав час пояснити, навіщо вона тобі. Вона позбавить необхідності писати класи і підтримувати їх. Є такий хороший проект jsonschema2pojo . Він пропонує плагіни для збирачів проекту (мавен, грейдл), які напишуть ці класи для тебе під час збирання. Наведу приклад із мого проекту:

<plugin>
    <groupId>org.jsonschema2pojo</groupId>
    <artifactId>jsonschema2pojo-maven-plugin</artifactId>
    <version>0.4.37</version>

    <executions>
        <execution>
            <id>jsonschema2opjo</id>
            <configuration>
                <sourceDirectory>${project.basedir}/src/main/resources/json-schema/</sourceDirectory>
                <targetPackage>tester.model</targetPackage>
                <outputDirectory>${project.basedir}/target/generated-sources/jsonschema/</outputDirectory>
                <useCommonsLang3>true</useCommonsLang3>
                <includeConstructors>true</includeConstructors>
                <generateBuilders>true</generateBuilders>
                <includeToString>true</includeToString>
                <usePrimitives>true</usePrimitives>
            </configuration>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>generate-sources</phase>
        </execution>
    </executions>
</plugin>

Це його налаштування. Найцікавіше тут:

<useCommonsLang3>true</useCommonsLang3>
<includeConstructors>true</includeConstructors>
<generateBuilders>true</generateBuilders>
<includeToString>true</includeToString>
<usePrimitives>true</usePrimitives>

Це вказівка, як писати клас: useCommonsLang3 – використовувати бібліотеку CommonsLang3 includeConstructors – напише конструктор generateBuilders – вбудує патерн білдер includeToString – додасть toString usePrimitives – вказівку використовувати примітиви Чим це краще за самописний код?

Ви можете кастомізувати класи одним рядком. Наприклад, треба додати суфікс Pojo до кожного класу. Достатньо додати <classNameSuffix>Pojo</classNameSuffix> збирати проект і готово. Інакше довелося міняти імена кожному клас руками.

Цих параметрів дуже багато, про всіх варто почитати у доках
Якщо твій проект має споживача, набагато простіше буде віддати йому json схеми, а не java класи. Як я вже казав, схеми універсальні і споживач просто згенерує pojo своєю мовою.
Вони набагато менші. Приклад зверху містить багато не завжди потрібної інформації, скажімо, патерни та приклади. Але якщо повернути їх у java код, він також сильно зросте. І не забудь про шаблонний код, який у схемах вказується парою налаштувань у плагіні, а в коді його треба писати самому. Так, я знаю про ломбок, тут альтернатива.
Ніякої логіки у pojo. Коли ваші класи самописні, хтось може спокуситись і додати зручний йому метод. У схемі json метод додати не можна, як і в згенерований клас.

Напевно, на цьому все.

Висновок:

Я намагався донести, що json схема дуже хороший формат взаємодії між проектами. Якось я з ним зустрівся на одному проекті, і він запал мені в серці. Я використовую їх майже всюди. Так, це не завжди зручно, адже, щоб подивитися вихідники, треба збирати проект. Але це pojo, отже, логіки там бути не може, зі схемами і не буде. PS.. я іноді поясню погано, так що ось відео з гарною доповіддю: Кирило Меркушев — Кодогенерація як спосіб вирішення проблем автоматизатора.

Коментарі

ЩОБ ПОДИВИТИСЯ ВСІ КОМЕНТАРІ АБО ЗАЛИШИТИ КОМЕНТАР,
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ