dataspace_demo_shop
Демонстрационное 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
v
- Создаем нового клиента для системы авторизации на сайте (под клиентом понимается именно компонент клиент - сервер, а не клиент интернет-магазина)
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/
Спасибо!
Описание
Демонстрационное web-приложение сервиса Platform V DataSpace (базовый функционал)
Языки
TypeScript
- JavaScript
- HTML