Демонстрационное web-приложение сервиса Platform V DataSpace

Приветсвие

Добро пожаловать в руководство по установке и настройке демонстрационного проекта Platform V DataSpace!
В рамках данного материала будут подробно описаны все основные шаги, необходимые для развертывания учебного проекта в локальном окружении разработчика, установке всех необходимых зависимостей и инструментов. Также будет дана краткая характеристика применяемых подходов и технологий. Мы будем благодарны за любую конструктивную обратную связь, а также готовы ответить на все вопросы по внедрению и практической разработке с применением Platform V DataSpace.

Понятие BaaS

Backend as a Service (backend как услуга) — модель, которая предоставляет полноценную среду разработки ПО в облаке провайдера. Она автоматизирует внутреннюю разработку, берет на себя работу с серверами и позволяет заказчику сосредоточиться на разработке интерфейса. Готовые инфраструктурные решения значительно упрощают работу разработчиков

Общая информация о системе Platform V DataSpace

Platform V DataSpace является облачным решением для хранения и управления данными, реализующее концепции DааS (data-as-a-service) и BааS (backend-as-a-service), с продвинутым мониторингом и гибкими возможностями поиска и получения данных

Platform V DataSpace входит в состав обширного набора продвинутых инструментов разработки и поддержки IT-инфраструктуры от Сбера

Ключевые преимущества Platform V DataSpace

Экономия
Снижение расходов на создание backend-инфраструктуры
Мультиязычность
Поддержка Java, JavaScript, Python, Go
Совместимость с GraphQL API
Полноценная работа с популярным протоколом
Удобный интерфейс
Визуальный редактор моделей, понятный всей команде
Безопасность
Основан на реальных внедрениях в enterprise-сегменте, позволяет реализовать импортозамещение

Предметно-ориентированное проектирование
(domain-driven design, DDD)

DDD — это подход, который нацелен на изучение предметной области предприятия в целом или каких-то отдельных бизнес-процессов. Это отличный подход для проектов, в которых сложность (запутанность) бизнес-логики достаточно велика. Его применение призвано снизить эту сложность, насколько возможно.

Вне подхода DDD, когда программист пишет код, больше внимания он уделяет технологиям и инфраструктуре, например, как отправить сообщение, как его получить, закодировать, сохранить в базу данных, в какую именно базу данных.

Подход DDD говорит о том, что всё это, конечно, важно, но вторично. Бизнес главнее и должен стоять на первом месте. И чтобы вся эта штука заработала вместе, DDD учит нас (разработчиков) разговаривать с бизнесом на одном языке. Не на языке программирования, а на языке бизнеса. Это называется в DDD Единый язык (Ubiquitous language).

Главные книги по DDD: красная, синяя и зелёная

DDD — довольно старый подход. Его использование выглядит разумным и вполне оправданным, но почему-то он всё ещё мало распространён, про него мало говорят на конференциях. Да что не так с этим DDD?

Есть предположение, что основная проблема в дефиците учебных материалов. Вся теория описана в нескольких книжках: красной, синей и зелёной. Говорят, что есть «ещё одна красная книжка», но её пока мало кто видел :)

Если вы решили начать изучать литературу по DDD, то лучше всего начать с «зелёной» книги. В ней Вон Вернон пробегается по верхушкам подхода и на простых примерах показывает его преимущества. Говорят, что перевод получился сомнительным, так что лучше читать в оригинале.

Необходимое программное обеспечение

Git https://git-scm.com/
Система контроля версий
Node.js v16.14.2 https://nodejs.org/en
Применяется для сборки и запуска React-приложения
OpenJDK v18.0.2+9 https://jdk.java.net/archive/
Необходимый компонент для запуска и работы Keycloak
Visual Studio Code https://code.visualstudio.com/
Любая IDE
Keycloak v17.0.1 https://github.com/keycloak/keycloak/releases/download/17.0.1/keycloak-legacy-17.0.1.zip
Система идентификации и авторизации (Identity Identification Manager)

В данном учебном примере клиентское приложение развертывается в операционной системе Mac OS.
Для Windows и Linux общий порядок шагов будет аналогичным, но с учетом с особенностей данных ОС.

Описание проекта, ключевые файлы

Приложение создано с применением JS-библиотеки React, для сборки используется Webpack и Babel
Кроме этого для создания GraphQL API применяется Apollo GraphQL

Apollo GraphQL – это облачная платформа для создания GraphQL API, используется для создания высокопроизводительных и масштабируемых API для мобильной и веб-разработки, а также IoT-устройств.

Ключевые файлы проекта:

model.xml - модель предметной области для DataSpace
schema.graphql - GraphQL-схема API DataSpace
.env - конфигурационный файл подключения frontend-приложения к серверу через язык запросов GraphQL
FirstLoad.graphql - запрос для первоначальной загрузки данных о товарах
permissions.json - JSON файл для загрузки в DataSpace информации об разрешенных для frontend запросов к серверу
graphql/requests.graphql - GraphQL-запросы, осуществляющие основные функции приложения
documentation - справочная информация о применяемых запросах и разрешениях
src/components - React-компоненты приложения

Пошаговый процесс развертывания

Подготовка файлов проекта

Создание директории для проекта

mkdir app
Переходим в созданную директорию и клонируем файлы из github автора проекта,
главного руководителя IT-направления в СберТех - Виктора Бирюкова:

cd app

git clone -b step2 https://github.com/VictorBiryukov/online-shop.git
в директории app будет создана вложенная директория online-shop, в которой находится все необходимые для развертывания приложения файлы

Установка и настройка системы авторизации и идентификации Keycloak

Скачиваем систему авторизации и идентификации доступа KeyCloak
https://github.com/keycloak/keycloak/releases/download/17.0.1/keycloak-legacy-17.0.1.zip
Распаковываем скачанный zip-архив Keycloak-legacy-17.0.1.zip и перемещаем директорию keycloak-17.0.1 в директорию проекта (app)
Открываем Терминал и переходим в директорию keycloak-17.0.1/bin
Запускаем KeyCloak командой
./standalone.sh

Важно! Перед запуском KeyCloak в системе должен быть установлен JDK!
KeyCloak выводит в консоль информацию о запуске

Открываем Панель управления KeyCloak в браузере по адресу http://localhost:8080/auth/
Указываем логин и пароль для создания администратора, для тестовых целей подойдет несложный, например admin 12345, нажимаем кнопку Create, далее логинимся в соответствии с созданным профилем

Административная консоль Keycloak

Создание пользователей и настройка прав доступа в системе Keycloak

Создаем новое рабочую область (realm) с названием orders

Создаем нового клиента для системы авторизации на сайте (под клиентом понимается именно компонент клиент - сервер, а не клиент интернет-магазина)
Client ID: orders
Root URL: http://localhost:3000

Создаем роли для пользователей системы:

customer (покупатель)
manager (менеджер интернет-магазина)
supervisor (старший менеджер интернет-магазина)
vendor (поставщик, продавец)

Создаем четырех пользователей системы, создаем для каждого пароли и устанавливаем их постоянными (система не будет предлагать сменить их после первого входа)

customer_user
customer@mail.ru
12345

manager_user
manager@mail.ru
12345

supervisor_user
supervisor@mail.ru
12345

vendor_user
vendor@mail.ru
12345

Для пользователя vendor_user также создаем аттрибут vendor_id со значением "SberDevices". Это необходимо для демонстрации возможности системы по обеспечению прав доступа и передачи разным пользователям только той информации, к которой у них есть доступ

Добавляем пользователям соответствующее роли

Добавляем передачу параметра vendor_id в составе JWS-токена (необходимо для обеспечения корректного разграничения прав доступа)

Clients orders Mappers Create Protocol Mappers

Clients - orders - Mappers - Create - vendor_id (тип User Attribute, User Attribute и Token Claim Name - vendor_id, Claim JSON Type - String)

Создание модели предметной области в визуальном редакторе Platform V DataSpace.
Открываем Smart Market studio (Авторизация по Sber ID или почте) https://developers.sber.ru/dev
Создаем новый проект Platform V DataSpace, имя Shop

После создание проекта попадаем в визуальный конструктор моделей предметной области DataSpace

Импортируем в проект готовую модель предметной области (файл model.xml проекта)

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

После загрузки в редактор модель должна быть выпущена, т.е. на стороне сервера созданы и запущенны все необходимые компоненты и сервисы, обеспечивающие функционирование модели и обмен данными. По завершении выпуска модели необходимо указать ее версию для редактирования - 0.0.2 (исходная версия модели - 0.0.1)

Настройка локального приложения для работы с DataSpace посредством GraphQL

GraphQL — это язык запросов и серверная среда для API с открытым исходным кодом. Он появился в Facebook в 2012 году и был разработан для упрощения управления конечными точками для API на основе REST

Копируем значение Ссылка на endPoint jwt graphql и вставляем его в файл .env проекта в качестве значения параметра DS_ENDPOINT (например DS_ENDPOINT=https://smapi.pv-api.sbc.space/jwt/ds-7376253516743639041/graphql)

Для корректной совместной работы системы авторизации KeyCloak и DataSpace необходимо настроить ключи JSON Web Key Sets. Для этого создаем в корне приложения файл
certs.json
Получаем открытую часть ключа KeyCloak, перейдя по ссылке http://localhost:8080/auth/realms/orders/protocol/openid-connect/certs

Копируем полученный ключ в файл certs.json, для удобства чтения JSON можно отформатировать средствами VS Code или сторонних расширений

Загружаем полученный ключ в DataSpace в разделе Разрешения -> Загрузить JSON Web Key Sets

Загружаем разрешения на запросы от frontend-части приложения к DataSpace из файла permissions.json из файлов проекта

Поскольку в нашем интернет-магазине еще нет никаких данных нам необходимо загрузить их в DataSpace, выполнив GraphQL запросы из файла FirstLoad.graphql в конструкторе GraphQL запросов. Копируем запросы из файла, вставляем в левой части конструктора и нажимаем кнопку в центре, данные загружаются в DataSpace. Теперь в нашем интернет-магазине появились товары!

Сборка и запуск React-приложения.
Последовательно выполняем в терминале следующие команды:

Установка необходимых модулей Node.js с помощью менеджера пакетов npm

npm install

Сборка React-приложения
npm run codegen

Запуск приложения
npm start
Открываем приложение в браузере:
http://localhost:3000/
Авторизуемся например под пользователем customer_user (12345)
Мы попадаем на главную страницу интернет магазина, где можем просматривать товары, помещать их в корзину (кнопки справа)

Важно, что разделы сайта All orders и Orders details for vendor в соответствии с заданной схемой разрешений пользователю customer_user недоступны

При этом если мы авторизуемся на сайт под пользователем vendor_user, для которого был создан аттрибут vendor_id = SberDevices мы сможем просмотреть информацию раздела Orders details for vendor, доступа будет разрешен

Более детально механизм работы JWT-токенов можно увидеть, открыв инструмент мониторинга сети браузера и выбрать какой-то GraphQL-запрос

Скопировав значение ключа и зайдя на сайт https://jwt.io/ можно его декодировать, среди параметров мы увидим vendor_id, передача именно этого параметра в составе JWT-токена и позволяет Keycloak распознать пользователя и предоставить ему доступ к разрешенным разделам сайта

Поздравляем! Вы справились!
Добро пожаловать в демонстрационное приложение Platform V DataSpace!

Корректно завершить работу web-приложения, а также KeyCloak возможно комбинацией - Ctrl + С в терминале с запушенными сервисами

Средства мониторинга

Platform V DataSpace обладает развитыми средствами анализа производительности и мониторинга. Можно анализировать скорость работы запросов GraphQL, загруженность CPU, сети, дискового пространства и много е другое.
Доступ к средствам мониторинга можно получить в Smart Market Studio, вкладка Детали:

Полезные ссылки

Портал Сбера для разработчиков
https://developers.sber.ru/dev

Platform V
https://platformv.sbertech.ru/

Platform V DataSpace
https://platformv.sbertech.ru/products/instrumenty-razrabotchika/dataspace

Документация Platform V DataSpace
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/

JWT & JWKS

Open ID Connect
https://openid.net/developers/how-connect-works/

JWKS
https://auth0.com/docs/secure/tokens/json-web-tokens

JSON Web Tokens
https://jwt.io/

Язык запросов GraphQL

Официальный сайт GraphQL
https://graphql.org/

Кодогенерация с помощью GraphQL
https://the-guild.dev/graphql/codegen#!

GraphQL в DataSpace
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/documents/dataspace-core-graphql-protocol/index.html

Работа со строковыми выражениями в DataSpace
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/documents/string-expressions/index.html

Инструменты для разработчиков от Сбера

GIGACHAT - диалоговая AI-модель, которая отвечает на вопросы, сочиняет тексты, пишет код и рисует картинки. Говорит на русском и понимает английский.
https://developers.sber.ru/gigachat/

GIGACODE - это AI-ассистент разработчика, который позволяет ускорить процесс написания кода, предлагая наиболее вероятные и релевантные подсказки
https://gigacode.ru/

GITVERSE - российская платформа для работы с исходным кодом
https://gitverse.ru/

Завершение

В результате последовательного и внимательного выполнения всех шагов данного руководства вы получите полноценное fullstack web приложение, демонстрирующее базовые возможности сервиса Platform V DataSpace. Команда Сбера активно ведет разработку новых функций и возможностей, постоянно выходят обновления, новые версии платформы, инструментов для разработчиков.

Всю актуальную информацию, новости, а также ответы на вопросы вы можете оперативно получать через наши каналы в социальных сетях, вступайте и подписывайтесь:

TG канал Sber Developer News
https://t.me/SberDeveloperNews

TG группа пользователей developers.sber.ru и продуктов SberDevices
https://t.me/smartmarket_community

Habr
https://habr.com/ru/companies/sberbank/profile/

dataspace_demo_shop