Опубликовано вUncategorized

От диаграмм к живой документации: Руководство для начинающих по DevOps-каналу Visual Paradigm

Введение: Конец устаревшей документации

Если вы когда-либо работали над программным проектом, вы знаете страдания от «долга документации». Вы тратите часы на рисование красивых диаграмм архитектуры в Visio или Lucidchart, только чтобы увидеть, как они мгновенно устаревают, как только команда разработки меняет схему базы данных или добавляет новый микросервис. Документация превращается в нудную работу, и разработчики перестают ей доверять.

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

From Diagrams to Living Documentation: Visual Paradigm’s DevOps Pipeline

В этом руководстве вы пройдете путь созданияDevOps-канала и документации Visual Paradigm (VP). Мы преобразуем статичные визуальные модели в автоматизированную, живую базу знаний. К концу этого руководства вы поймете, как подключить настольные инструменты проектирования, ИИ-ассистентов и системы CI/CD, чтобы создать бесшовный жизненный цикл «Живой документации».

Рекомендуемые инструменты и предварительные требования

Чтобы следовать по этому каналу, вам понадобится доступ к экосистеме Visual Paradigm и стандартным инструментам DevOps:

  1. Visual Paradigm Desktop или Online: Для создания богатых диаграмм UML, SysML и BPMN.

  2. Чат-бот VP / ИИ-ассистент: Для генерации начальных диаграмм с помощью естественных языковых запросов.

  3. Git: Для контроля версий ваших текстовых моделей и кода.

  4. Платформа CI/CD: GitHub Actions, GitLab CI или Jenkins (в этом руководстве мы будем использовать GitHub Actions).

  5. OpenDocs / PlantUML: Для преобразования текстовых моделей в визуальные результаты.

Этап 1: Уровень проектирования (захват архитектуры)

Канал начинается с момента, когда вы фиксируете требования и проектируете архитектуру вашей системы. Visual Paradigm предлагает три основных способа создания ваших моделей:

  • VP Desktop: Мощный инструмент с полным функционалом для сложной корпоративной архитектуры, UML и BPMN.

  • VP Online: Облачная, совместно используемая платформа, идеально подходящая для быстрой работы с векторной графикой и гибкого планирования.

  • Чат-бот VP / ИИ: Конверсационный интерфейс, который генерирует диаграммы непосредственно из текстовых описаний или пользовательских историй.

Реалистичный пример: проектирование процесса оформления заказа в электронной коммерции

Представьте, что вам поручено разработать архитектуру оформления заказа для новой платформы электронной коммерции. Вместо ручного перетаскивания фигур вы можете использовать VP Chatbot с следующим запросом:

«Создайте диаграмму компонентов для системы оформления заказов электронной коммерции. Она должна включать веб-интерфейс, сервис заказов, шлюз оплаты и базу данных инвентаря.»

ИИ мгновенно генерирует структурную диаграмму. Под капотом эта визуальная модель может быть представлена с помощью стандартного текстового синтаксиса, такого как PlantUML, который нативно поддерживается Visual Paradigm для своих текстовых моделей.

Вот код PlantUML, представляющий нашу дизайнерскую модель, созданную ИИ:

Plantuml


Редактировать Plantuml в VPasCode
Plantuml Edit Plantuml in VPasCode 
@startuml Архитектура оформления заказов электронной коммерции
!theme plain
skinparam componentStyle rectangle

package "Слой пользовательского интерфейса" {
  [Веб-приложение] как Web
  [Мобильное приложение] как Mobile
}

package "Бэкенд-микросервисы" {
  [Сервис заказов] как Order
  [Шлюз оплаты] как Payment
  [Сервис инвентаря] как Inventory
}

database "PostgreSQLn(БД инвентаря)" как DB

' Связи
Web --> Order : REST API
Mobile --> Order : REST API
Order --> Payment : Обработка транзакции
Order --> Inventory : Проверка/резервирование товара
Inventory --> DB : Чтение/запись

@enduml
Edit Plantuml in VPasCode



Редактировать Plantuml в VPasCode

Этап 2: Уровень абстракции (VPasCode)

Визуальные модели отлично подходят для людей, но машины нуждаются в тексте. Именно здесь VPasCode (Visual Paradigm как код) закрывает этот разрыв.

VPasCode позволяет рассматривать ваши диаграммы точно так же, как программный код.

  • Текстовое моделирование: Вы определяете диаграммы с помощью читаемого человеком текста (например, код PlantUML выше).

  • Контроль версий: Вы сохраняете эти определения диаграмм как .puml или .vpuc файлы непосредственно в вашем репозитории Git вместе с исходным кодом приложения.

  • Автоматизация с помощью SDK/CLI: Вы можете использовать API Visual Paradigm для программного запроса или изменения визуальных элементов.

Реалистичный пример: коммит в Git

Вместо сохранения вашей диаграммы как изолированного .png файл, вы сохраняете код PlantUML в файле с именем checkout-architecture.puml внутри папки вашего проекта /docs/architecture/ папки.

git add docs/architecture/checkout-architecture.puml
git commit -m "docs: добавить начальную диаграмму архитектуры checkout"
git push origin main

Теперь ваша диаграмма контролируется версиями. Если разработчик изменит Order Service, они обновят текстовый файл в том же запросе на изменение.

Этап 3: Уровень автоматизации (OpenDocs и CI/CD)

Вот где происходит волшебство. Мы больше не вручную экспортируем диаграммы в PDF или Word. Мы автоматизируем процесс с помощью OpenDocs и CI/CD-канала.

  • OpenDocs: Фреймворк генерации открытых стандартов документов, который читает данные вашей модели (файлы PlantUML/VPasCode) и сопоставляет их с текстовыми шаблонами.

  • Интеграция канала: Мы используем инструменты CI/CD (например, GitHub Actions), чтобы отслеживать изменения в репозитории.

  • Автоматические триггеры: Каждый раз, когда код или модели изменяются, канал автоматически пересобирает документацию.

Реалистичный пример: рабочий процесс GitHub Actions

Вот реалистичный .github/workflows/build-docs.yml файл, который запускается каждый раз, когда обновляются файлы архитектуры. Он использует PlantUML для отрисовки диаграмм и упаковывает их в статический веб-сайт HTML.

name: Сборка живой документации

# Запуск рабочего процесса только при изменении файлов в папке docs/architecture
on:
  push:
    paths:
      - 'docs/architecture/**'
  workflow_dispatch: # Позволяет запускать вручную

jobs:
  generate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Проверка репозитория
        uses: actions/checkout@v3

      - name: Настройка Java (необходимо для PlantUML/VP CLI)
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Генерация диаграмм с помощью OpenDocs/PlantUML
        run: |
          # Скачать jar-файл PlantUML
          wget https://github.com/plantuml/plantuml/releases/download/v1.2023.10/plantuml-1.2023.10.jar -O plantuml.jar
          # Отобразить все файлы .puml в папке архитектуры в формате SVG/PNG
          java -jar plantuml.jar -tsvg docs/architecture/*.puml

      - name: Компиляция HTML-документации живой документации
        run: |
          # Предполагается, что используется пользовательский скрипт OpenDocs или команда CLI VP для обертывания изображений в HTML-шаблоны
          mkdir -p public/docs
          cp -r docs/architecture/*.svg public/docs/
          # Создание index.html с метаданными и встроенными диаграммами
          echo "<html><body><h1>Живая документация по архитектуре</h1>" > public/docs/index.html
          echo "<img src='checkout-architecture.svg' />" >> public/docs/index.html
          echo "</body></html>" >> public/docs/index.html

      - name: Развертывание на GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Этап 4: Уровень вывода (Живая документация)

Финальный результат этого канала — ваша Живая документация. Поскольку она автоматически генерируется из источника истины (ваш код и текстовые модели), она никогда не устаревает.

  • Единый источник истины: Код, визуальные модели и текстовые пояснения остаются идеально синхронизированными.

  • Гибкость форматов: Поток может генерировать адаптивные веб-сайты в формате HTML (размещаемые на GitHub Pages или внутренних вики), PDF-файлы для соответствия требованиям или напрямую отправлять в Confluence.

  • Динамические метаданные: Расширенные настройки могут встраивать активные метрики системы, словари данных и отслеживание требований Jira непосредственно в сгенерированный текст, ориентированный на пользователя.

Ваша команда теперь имеет красивый и актуальный URL (например, docs.yourcompany.com) который всегда отражает точное текущее состояние программного обеспечения.

Пошаговый рабочий процесс внедрения

Кратко говоря, вот ежедневный рабочий процесс, который будет следовать ваша команда для поддержания этой экосистемы:

  1. Черновик: Создайте диаграмму класса UML, компонента или процесса BPMN в VP Desktop/Online, или запросите у чат-бота VP создание диаграммы на основе пользовательской истории.

  2. Экспорт: Сохраните или закоммитьте файл проекта, используя форматы текста VPasCode/PlantUML внутри репозитория Git вашего проекта.

  3. Сборка: Загрузите изменения в Git. Это действие автоматически запускает ваш пайплайн CI/CD (например, GitHub Actions).

  4. Генерация: Пайплайн запускает OpenDocs/PlantUML для извлечения новых изображений диаграмм, компиляции метаданных и создания выходных HTML/PDF-файлов.

  5. Публикация: Инструмент размещает только что обновлённый живой документ на внутреннем портале команды, вики или публичном сайте документации.

Заключение: Принятие концепции живой документации

Переход на визуальную парадигму DevOps-пайплайна требует смены мышления. Документация больше не является после мысли или отдельной задачей, поручаемой младшему разработчику в конце спринта. Вместо этого она становится автоматическим побочным продуктом самого процесса разработки.

Используя Слой проектирования (VP Desktop и ИИ), Слой абстракции (VPasCode), Слой автоматизации (CI/CD и OpenDocs), и Слой вывода (Живая документация), вы навсегда избавитесь от долгов документации. Ваши диаграммы наконец-то будут развиваться с той же скоростью, что и ваш код, обеспечивая вашу команду надежным, единым источником истины, который способствует более качественным решениям и быстрому вводу в работу.

Начните с малого: выберите один основной микросервис, опишите его архитектуру на PlantUML, закоммитьте в Git и настройте базовую GitHub Action для его отображения. Как только вы увидите, как ваш первый «Живой документ» автоматически обновляется, вы больше никогда не захотите возвращаться к ручному созданию диаграмм.

Справка

  1. Кейс: Ускорение документации архитектуры программного обеспечения с помощью VPasCode — революция в виде диаграмм как кода: Кейс о том, как VPasCode преодолевает разрыв между кодом и визуализацией с помощью готовых к использованию в ИИ диаграмм как кода и автоматизированной инженерии компоновки.
  2. Полное руководство по VPasCode от Visual Paradigm: Подробный обзор основной философии VPasCode, пользовательского интерфейса, поддержки нескольких движков и рабочих процессов совместной работы.
  3. От кода к ясности: Руководство для начинающих по бесшовному созданию диаграмм с помощью VPasCode и OpenDocs: Руководство по использованию VPasCode с OpenDocs для документации с ИИ-поддержкой, включая практические примеры PlantUML и интеграцию в пайплайн.
  4. Овладение VPasCode: Полное руководство по диаграммам как коду с ИИ-поддержкой и поддержкой нескольких движков: Расширенное руководство, охватывающее уникальные преимущества VPasCode, архитектуру, нативно ориентированную на ИИ, и поддержку нескольких движков.
  5. Революция в обслуживании диаграмм: Как автисправление на основе ИИ в VPasCode устраняет раздражение из-за синтаксических ошибок: Подробный обзор функции автисправления на основе ИИ в VPasCode для автоматического обнаружения и исправления синтаксических ошибок.
  6. Как чат-бот Visual Paradigm на основе ИИ и VPasCode работают как интегрированная экосистема для создания диаграмм: Объясняет интегрированный двухэтапный рабочий процесс, объединяющий чат-бота на основе ИИ для быстрого создания и VPasCode для точной доработки диаграмм.
  7. Ясность за счет дизайна: Упрощение документации инфраструктуры с помощью VPasCode и языка Graphviz DOT: Кейс по использованию VPasCode и языка Graphviz DOT для модернизации документации инфраструктуры как кода.
  8. VPasCode: Единая платформа для диаграмм как кода: Официальная страница функций, описывающая поддерживаемые типы диаграмм, поддержку нескольких движков, предварительный просмотр в реальном времени и возможности экспорта.