Моделювання структури таблиць БД реєстру в XML-редакторі коду

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальні положення

Адміністративний портал пропонує вбудований XML-редактор, який спеціалізується на роботі зі структурою таблиць у файлі data-model/createTables.xml і спрощує роботу з моделлю даних у регламенті реєстру. Всього існують два підходи до створення та редагування таблиць:

  • Робота безпосередньо у файлах регламенту Gerrit. У цьому випадку може бути декілька різних файлів для роботи з різними таблицями.

    Детальніше про роботу з таблицями у моделі даних див. — Керування таблицями.

  • Робота через XML-редактор в адміністративному порталі. Зміни, внесені тут, після їх застосування до майстер гілки репозиторію registry-regulations, потрапляють лише до одного файлу — data-model/createTables.xml.

    У такому випадку необхідно дотримуватися таких рекомендацій:

    • Усі операції, пов’язані зі створенням або зміною структури таблиць бази даних, слід зберігати у файлі data-model/createTables.xml. Це допоможе забезпечити правильну організацію структури даних та зручність роботи з ними.

    • Файл data-model/createTables.xml має бути явно включений до переліку файлів для розгортання у конфігурації data-model/main-liquibase.xml. Це гарантує належне врахування змін у таблицях бази даних під час розгортання системи.

    Дотримуючись цих рекомендацій, ви зможете забезпечити ефективну роботу зі структурою таблиць та забезпечити коректність розгортання бази даних у вашому реєстрі.

Ви самі обираєте, який підхід використовувати для створення та редагування таблиць. Якщо ви обираєте роботу з адміністративного порталу через вбудований XML-редактор, то для полегшення роботи зі структурою таблиць у файлі createTables.xml було імплементовано рішення Monaco Editor, візуалізоване темою Visual Studio Dark. Це дозволяє швидко та зручно вносити зміни через єдиний інтерфейс і зменшує кількість помилок, забезпечуючи більш продуктивний процес роботи з моделлю даних.

Однією з переваг цього редактора є синтаксичний аналіз коду — можливість отримувати сповіщення про синтаксичні помилки, якщо такі виникли. Крім того, редактор надає підказки та дозволяє використовувати функцію автозаповнення, що спрощує процес додавання нової таблиці до моделі даних.

2. Сценарії використання

  • Зручне редагування структури даних у моделі регламенту реєстру за допомогою простого вікна редагування.

  • Автоматичне збереження внесених змін до версії-кандидата регламенту, що дозволяє ефективно вести процес редагування.

  • Відображення повідомлень про помилки у вікні редагування структури таблиць моделі даних регламенту реєстру, що допомагає швидко виявляти та виправляти помилки.

  • Надання автопідказок та автодоповнень при редагуванні liquibase changelog xml, що спрощує процес редагування та дозволяє уникнути помилок.

  • Перевірка liquibase-конфігурації згідно з liquibase та DDM xsd, що допомагає налаштувати конфігурацію коректно та уникнути проблем.

3. Функціональні можливості

3.1. Загальний процес використання

Використовуйте візуальний редактор коду при створенні та редагуванні таблиць моделі даних реєстру за допомогою XML-тегів.

Редагування складових регламенту реєстру можливе лише в рамках версій-кандидатів на внесення змін. Для майстер-версії доступна лише опція перегляду.

Детальніше про особливості роботи з версіями регламенту дивіться на сторінці Управління версіями регламенту.

  1. У Кабінеті адміністратора регламентів відкрийте розділ Таблиці.

    Портал адміністратора ви можете знайти за посиланням:
    https://admin-tools-<назва-реєстру>.apps.envone.dev.registry.eua.gov.ua/.

    xml editor 1

  2. В рамках версії-кандидата відкрийте вкладку Файл опису структури та розгорніть візуальний редактор у повноекранному режимі, натиснувши Розгорнути.

  3. Внесіть відповідні зміни до моделі даних та натисніть Зберегти зміни.

    Детальніше про роботу з моделлю даних реєстру ви можете дізнатися на сторінці Створення фізичної моделі даних.

    xml editor 2

    Ви отримаєте відповідне повідомлення-підказку про те, що зміни збережено.

    xml editor 3

    Скасуйте зміни, натиснувши Відмінити зміни. При натисканні на цю кнопку, ви отримаєте наступне попереджувальне повідомлення із варіантами продовження:

    Ви впевнені, що хочете скасувати зміни?

    xml editor 5

    Якщо ви змінили файл, але не зберегли зміни, і хочете вийти із вікна редагування, то отримаєте наступне повідомлення:

    Файл опису структури було змінено. Якщо покинути сторінку зараз, то незбережені зміни будуть скасовані.

    xml editor 4
    Кнопка Зберегти зміни заблокована, якщо файл опису структури містить помилки, знайдені під час аналізу коду та liquibase-конфігурації згідно з liquibase та DDM xsd (детальніше — див. у розділі Синтаксичний аналіз коду, підказки та автодоповнення).

  4. Перейдіть до розділу Огляд версії та перевірте, що зміни у файлі додалися до переліку змін вашої версії-кандидата з відповідним статусом.

    Якщо у файлі data-model/createTables.xml було внесено зміни через адміністративний портал або безпосередньо через додавання патчсет-у в Gerrit у відповідний MR до версії-кандидата, то на сторінці Огляд версії в розділі Внесені зміни відображатиметься секція Структура таблиць БД.

    xml editor 9

  5. Застосуйте зміни до майстер-версії регламенту.

    Детальніше дивіться на сторінці Перегляд та управління налаштуваннями версії-кандидата.
Виникнення помилок під час обробки файлу з описом структури моделі даних

  • При відкритті вкладки Файл опису структури в адміністративному порталі, у разі відсутності файлу data-model/createTables.xml у репозиторії з регламентом, може виникнути 404 помилка.

    xml editor 7

  • У випадку проблем із обробкою файлу data-model/createTables.xml, може виникнути 500 помилка.

    xml editor 8

3.2. Синтаксичний аналіз коду, підказки та автодоповнення

Вбудований синтаксичний аналізатор коду в редакторі Monaco пропонує переваги, які є специфічними для роботи з XML-розміткою:

  1. Підсвічування синтаксису XML: Редактор Monaco підсвічує відповідні елементи XML-файлу, такі як теги, атрибути та текстовий контент. Це полегшує читання та редагування XML-файлів.

  2. Автодоповнення XML-тегів: Редактор Monaco надає автодоповнення закривальних тегів, базуючись на відкритих тегах, а також автодоповнення для тегів <changeSet> та їхнього вмісту. Крім того, він пропонує автодоповнення для типових і нетипових (розширених) тегів та атрибутів Liquibase, що сприяє правильній структурі XML-файлів та знижує ризик виникнення помилок.

    Детальніше про доступні теги для побудови моделі даних див. на сторінках Перелік стандартних тегів Liquibase та Розширення Liquibase для моделювання даних відповідно.

  3. Валідація XML: Синтаксичний аналізатор перевіряє коректність XML-структури в реальному часі, виявляючи неправильні або відсутні теги та атрибути, що дозволяє швидко виправити помилки.

    xml editor 6

Функції синтаксичного аналізатора коду ґрунтуються на правилах, встановлених у XSD для редагування XML Liquibase документів. Відповідні XSD зберігаються у сховищі артефактів Nexus Платформи.

Для використання автопідказок, автодоповнення та аналізу коду згідно з Liquibase XSD та DDM Liquibase Extension під час редагування файлу структури моделі даних, замініть http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.5.xsd та https://nexus-public-mdtu-ddm-edp-cicd.apps.cicd2.mdtu-ddm.projects.epam.com/repository/extensions/com/epam/digital/data/platform/liquibase-ext-schema/latest/liquibase-ext-schema-latest.xsd на актуальні схеми, розміщені у Nexus.

Зверніться до адміністратора платформи для отримання посилань на схеми.

4. Інтеграція структури таблиць БД з різних файлів регламенту для відображення в адміністративному порталі

Цей розділ допоможе вам інтегрувати структуру таблиць бази даних (БД) із різних файлів регламенту для відображення у Кабінеті адміністратора регламентів. Мета полягає у тому, щоб зібрати всі структури таблиць БД в одному файлі — createTables.xml.

  1. Аналіз файлів регламенту.

    Перегляньте файли теки data-model, такі як createTables.xml, tablesCommon.xml, tablesKatottg.xml тощо, які містять набори змін (changeSets) із таблицями та їх атрибутами.

  2. Перенесення структур таблиць до файлу createTables.xml.

    • Знайдіть усі changeSets, які стосуються структури таблиць БД, у різних файлах регламенту.

    • Перенесіть ці changeSets до файлу createTables.xml у хронологічному порядку.

  3. Визначення дати створення changeSet.

    Щоб знайти дату створення changeSet, скористайтеся функцією Annotate with Git Blame в Intellij IDEA (або іншому середовищі розробки):

    • Натисніть правою кнопкою миші на лівому стовпці з номерами рядків у файлі.

    • Оберіть опцію Annotate with Git Blame.

      xml editor 10

    • Після цього лівий стовпчик розшириться, і поряд з номером рядка будуть відображені дата останнього оновлення та автор цього рядка.

      xml editor 11

  4. Перевірка результатів у Кабінеті адміністратора регламентів.

    Після завершення попередніх кроків, відкрийте адміністративний портал та перейдіть до розділу Таблиці > Файл опису структури. Тепер ви повинні побачити всю структуру таблиць БД, зібрану з різних файлів регламенту та відображену в одному файлі createTables.xml.

Зверніть увагу, що інтеграція структури таблиць БД в одному файлі — це лише рекомендація для поліпшення відображення структури даних у Кабінеті адміністратора. Ви завжди можете продовжити розробку структури даних безпосередньо в адміністративному порталі, враховуючи ваші власні вимоги та обмеження.