Сегодня мы погружаемся в удивительный мир JSON-схем, и я расскажу вам 6 причин, почему я считаю, что это стоит вашего времени.
Иногда, когда JSON-схема рассматривается в программных проектах, ее воспринимают как препятствие для быстрого продвижения. Я хотел бы возразить против этого, сказав, что да, создание схем для ваших данных может показаться замедляющим фактором в начале. Но как только у вас есть канонический источник правды для каждого ресурса, с которым вы работаете, последующие усилия могут значительно уменьшиться. Главным образом благодаря тому, что вы можете автоматически генерировать многое из своей схемы.
Содержание
Проверка данных
Это очевидно. Как и в случае любой схемы данных, вы можете использовать JSON-схему, чтобы удостовериться, что ваши данные соответствуют определенным структурам, используют правильные типы данных и следуют ограничениям, установленным в схеме.
В экосистеме JavaScript вы можете использовать отличный пакет AJV для проверки любого объекта JavaScript на соответствие JSON-схеме. Это особенно полезно для того, чтобы гарантировать соблюдение API-контрактов при общении с другими службами.
Автоматическая генерация пользовательского интерфейса
Иногда вам может потребоваться собирать данные, но вам нужно создать пользовательский интерфейс для их сбора. Начиная с JSON-схемы, вы можете использовать React JSON Schema Form (Rjsf) для автоматической генерации форм с предварительной клиентской и серверной проверкой по предоставленной схеме.
Rjsf позволяет легко создавать все необходимое для начала сбора данных. Вам нужно предоставить только схему. Он также позволяет настраивать пользовательский интерфейс на более высоком уровне для более сложных случаев.
Посмотрите их приложение-песочницу для примеров создания форм на основе схемы в короткие сроки.
Генерация типов
Допустим, вы создали службу TypeScript, которая принимает некоторые входные данные. Вероятно, вы создадите типы, представляющие эти входные данные.
Имея JSON-схему, вы не только можете проверять входные данные, но и автоматически генерировать типы TypeScript из схемы.
JSON-схема может развиваться по мере изменения структуры данных. Когда вы обновляете JSON-схему, вы можете автоматически генерировать типы TypeScript, чтобы они отражали эти изменения, гарантируя, что ваш код всегда соответствует структурам данных и увеличивая обслуживаемость вашего приложения.
Вы также можете генерировать JSON-схему из ваших типов TypeScript. Это полезно, если у вас есть типы, но нет схемы, или если вы предпочли бы иметь типы как источник истины.
Вот некоторые пакеты, которые помогут вам с этим:
Генерация спецификации OpenAPI
OpenAPI - это спецификация для HTTP API, которая позволяет нам определять, как должны вести себя наши API. Схема для API, так сказать.
Основное различие между JSON-схемой и OpenAPI заключается в том, что JSON-схема определяет данные JSON, тогда как OpenAPI описывает всее API (конечные точки, входные параметры), включая данные.
OpenAPI, как и JSON-схема, может показаться непростым для реализации, если вы его уже не используете. Однако, если вы начнете с JSON-схемы, вы можете использовать эту удобную библиотеку для генерации объекта схемы OpenAPI, который используется для определения типов данных на входе и выходе.
Генерация фиктивных данных
Допустим, вы создали приложение, которое предоставляет доступ к некоторым данным через API, который вызывает другое приложение. Для тестирования интеграции между вашим приложением и внешним миром нам нужно предоставить образец выходных данных из нашего приложения. Часто это может быть образцом JSON, поддерживаемым нами, или, что хуже, образцом JSON, поддерживаемым владельцами другого приложения. Это не идеально, потому что оно зависит от нас (людей) информировать друг друга, когда меняется контракт.
С помощью инструментов, таких как JSON Schema Faker, мы можем генерировать фиктивные данные, которые всегда соответствуют нашей схеме. Это означает, что как только наша схема меняется, меняются и наши фиктивные данные. Это можно использовать с контрактами, зависящими от потребителя, чтобы обеспечить раннее выявление проблемных изменений в наших интеграциях с другими приложениями.
JSON-схемы в вашей среде разработки
При наличии JSON-схемы VSCode может предоставлять автодополнение, подсветку ошибок и проверку для файлов JSON или YAML.
Это дополнительный аргумент, который побудил меня написать этот пост.
Недавно я работал над сложным приложением с низким/нулевым кодом, настроенным с использованием файлов YAML. Люди, которые писали конфигурацию, не были инженерами и полагались на все более сложный набор документации, чтобы правильно настроить систему.
Использование JSON-схем внутри VSCode позволило команде конфигурации использовать возможности автодополнения в IDE, чтобы помочь им совершать меньше ошибок при настройке системы.
Для настройки этого вам нужно указать файлы JSON-схемы и связать их с определенными шаблонами имен файлов.
Откройте вкладку “Settings”, найдите “JSON schemas” и выберите “Edit in settings.json”.
В settings.json вы можете добавить блок yaml.schemas или json.schemas в зависимости от типов файлов, которые вы хотите использовать.
Для YAML:
"yaml.schemas": {
"/absolute/path/to/your/json/schema.json": "somefile.yaml" // a file pattern can be used here
}
Для JSON:
"json.schemas": [
{
"fileMatch": [
"somefile.json" // a file pattern can be used here
],
"url": "file:/absolute/path/to/your/json/schema.json"
}
]
Сохраните файл settings.json и перезагрузите VSCode. После этого, при открытии файла, соответствующего указанному шаблону в настройках, IDE будет использовать схему для проверки содержимого файла. 🎉
Как вы можете видеть, создание и использование схем JSON при работе с данными JSON в ваших приложениях предоставляет множество преимуществ.
Спасибо за чтение!