Якщо ви вже працювали з JSON, то, ймовірно, зустрічалися з JSON Schema. JSON Schema — це неймовірно корисний інструмент для управління та перевірки структур даних JSON, особливо в сучасних веб-додатках, API та мікросервісах. Можна розглядати його як план, який забезпечує правильну форму даних, що проходять через вашу систему.
У цьому пості ми розглянемо три ключові варіанти використання JSON Schema, які допоможуть вам полегшити життя:
- Перевірка даних у API та додатках
- Тестування контрактів між сервісами
- Генерація динамічних JSON форм
Давайте дослідимо ці варіанти використання і подивимося, як JSON Schema може покращити ваш процес розробки, зробивши його більш гладким, надійним і значно легшим для підтримки.
1. Перевірка даних у API та додатках
Одним із найпоширеніших і потужних застосувань JSON Schema є перевірка даних API — це дані, що надходять та виходять з ваших API. Використовуючи JSON Schema, ви можете бути впевнені, що дані, які ваш API отримує (або надсилає), відповідають необхідній структурі та формату, що дозволяє рано виявляти помилки та уникати непередбачених проблем у майбутньому.
Приклад: Перевірка даних API
Припустимо, у вас є API, яке приймає дані користувача. Ви хочете переконатися, що дані, які надсилаються в API, правильні та повні. Ось як JSON Schema може допомогти:
Крок 1: Визначення JSON Schema
Ось приклад схеми для об'єкта користувача:
{
"type": "object",
"properties": {
"username": { "type": "string", "minLength": 3, "maxLength": 20 },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["username", "email", "age"],
"additionalProperties": false
}
Ця схема забезпечує:
username— рядок довжиною від 3 до 20 символів.email— коректна електронна адреса.age— ціле число, яке не менше за 18.- Не допускаються додаткові поля в даних.
Крок 2: Перевірка даних
Тепер давайте використаємо бібліотеку, як-от Ajv, для перевірки вхідних даних. Ось як це можна зробити в коді:
npm install ajv
const Ajv = require('ajv');
const ajv = new Ajv();
const schema = require('./userSchema.json'); // Завантажуємо схему
const validate = ajv.compile(schema);
// Приклад даних
const payload = {
username: 'john_doe',
email: '[email protected]',
age: 25
};const valid = validate(payload);
if (!valid) {
console.log('Невірні дані:', validate.errors);
} else {
console.log('Дані правильні!');
}
Це гарантує, що будь-які вхідні дані відповідають структурі, яку ми визначили в схемі. Якщо щось не так, ви одразу дізнаєтесь, що потрібно виправити.
Переваги:
- Раннє виявлення помилок: Ловіть помилки ще до того, як вони вплинуть на вашу базу даних або бізнес-логіку.
- Цілісність даних: Забезпечте, щоб дані завжди відповідали очікуваному формату, що дозволить уникнути помилок на подальших етапах.
- Легкість у підтримці: Оновлюючи структуру даних, вам достатньо змінити схему — і все інше автоматично адаптується.
2. Тестування контрактів між сервісами
У мікросервісній архітектурі різні сервіси повинні взаємодіяти один з одним. Але як гарантувати, що дані, які передаються між ними, будуть відповідати вимогам і формату? Тут на допомогу приходить тестування контрактів, і JSON Schema є ідеальним інструментом для визначення та перевірки цих контрактів.
Приклад: Взаємодія між мікросервісами
Припустимо, у вас є два сервіси: Сервіс користувачів і Сервіс замовлень. Сервіс замовлень залежить від даних користувача з Сервісу користувачів.
Визначивши контракт JSON Schema, обидва сервіси можуть домовитись про структуру даних, що передаються між ними.
Крок 1: Визначення контракту (JSON Schema)
Ось проста схема для взаємодії Сервісу користувачів з Сервісом замовлень:
{
"type": "object",
"properties": {
"userId": { "type": "string" },
"username": { "type": "string" },
"email": { "type": "string", "format": "email" }
},
"required": ["userId", "username", "email"],
"additionalProperties": false
}
Ця схема гарантує, що Сервіс користувачів завжди надсилатиме відповідь з полями userId, username та email, і не буде інших дозволених властивостей.
Крок 2: Тестування контракту
Тепер давайте перевіримо, чи насправді Сервіс користувачів надсилає правильні дані. Для цього ми можемо використати Jest та Ajv для перевірки відповіді:
npm install jest ajv
Ось сам тест:
const Ajv = require('ajv');
const ajv = new Ajv();
const userContract = require('./userContract.json'); // Завантажуємо схему контракту
const validate = ajv.compile(userContract);
// Симулюємо відповідь Сервісу користувачів
const userResponse = {
userId: '12345',
username: 'john_doe',
email: '[email protected]'
};test('Тест контракту Сервісу користувачів', () => {
const valid = validate(userResponse);
expect(valid).toBe(true);
if (!valid) {
console.log('Помилки перевірки контракту:', validate.errors);
}
});
Якщо відповідь від Сервісу користувачів не відповідатиме контракту, тест зазнає невдачі, що дасть вам знати про невідповідність, яка може порушити роботу Сервісу замовлень.
Переваги:
- Послідовна комунікація: Гарантуйте, що всі сервіси розуміють і надсилають дані в одному форматі.
- Зменшена тісна залежність: Кожен сервіс перевіряє контракт лише один раз, без необхідності жорсткого зв’язування їхніх структур даних.
- Автоматизоване тестування: Ці тести можуть автоматично запускатися в рамках вашого CI/CD процесу, виявляючи будь-які порушення до того, як вони потраплять в продакшн.
3. Генерація динамічних форм JSON
Якщо ви коли-небудь створювали складні форми, що змінюються залежно від контексту, ви знаєте, як важко їх управляти. А що, якщо ви могли б просто один раз визначити структуру форми і вона автоматично генерувалася б? Це ще одна сфера, де JSON Schema відзначається — динамічна генерація форм.
Приклад: Динамічна генерація форми
Припустимо, ви хочете створити форму реєстрації користувача, але замість того, щоб хардкодити кожне поле, ви можете використати JSON Schema для визначення структури.
Крок 1: Визначення JSON Schema для форми
Ось схема, яка визначає поля для форми реєстрації користувача:
{
"type": "object",
"properties": {
"firstName": { "type": "string", "title": "Ім'я" },
"lastName": { "type": "string", "title": "Прізвище" },
"email": { "type": "string", "title": "Електронна пошта", "format": "email" }
},
"required": ["firstName", "lastName", "email"]
}
Крок 2: Генерація форми в React
Використовуючи бібліотеку react-jsonschema-form, ви можете легко генерувати динамічну форму з JSON Schema:
npm install @rjsf/core
Ось як можна рендерити форму в компоненті React:
import React from 'react';
import Form from '@rjsf/core';
const schema = {
type: "object",
properties: {
firstName: { type: "string", title: "Ім'я" },
lastName: { type: "string", title: "Прізвище" },
email: { type: "string", title: "Електронна пошта", format: "email" }
},
required: ["firstName", "lastName", "email"]
};const DynamicForm = () => {
const onSubmit = ({ formData }) => {
console.log("Форма надіслана з даними:", formData);
}; return (
<Form schema={schema} onSubmit={onSubmit} />
);
};export default DynamicForm;
Це автоматично згенерує форму з полями для firstName, lastName та email на основі JSON Schema.
Більше не потрібно вручну писати кожне поле форми!
Переваги:
- Динамічні форми: Автоматично генеруйте форми на основі визначень JSON Schema.
- Послідовність: Тримайте поля форми в синхронізації зі структурою даних на сервері.
- Гнучкість: Якщо схема змінюється (наприклад, додаються або видаляються нові поля), форма автоматично оновиться — без необхідності вручну втручатись.
Висновок
JSON Schema — це не просто інструмент для валідації, це справжня революція у створенні масштабованих, підтримуваних та надійних систем. Чи то валідація API-пейлоудів, тестування контрактів між мікросервісами, чи генерування динамічних форм, JSON Schema спрощує ваш процес розробки та гарантує послідовність на всіх етапах.
Завдяки використанню JSON Schema ви зможете зменшити кількість помилок, покращити цілісність даних та зробити ваші робочі процеси ефективнішими.
Перекладено з: Exploring JSON Schema: Validation, Contract Testing, and Dynamic Forms