Инструменты системного аналитика: чем рисовать схемы и вести контракты

Я долго рисовал диаграммы мышкой в красивых редакторах. Пока однажды разработчик не поменял один сервис, а схема в Confluence осталась старой — и новый человек в команде неделю проектировал интеграцию по картинке, которая уже врала. С тех пор моя графика живёт как код: я пишу её текстом, она лежит рядом с проектом, и любое изменение видно в истории как обычный коммит. Это не вопрос вкуса — это вопрос того, чтобы схема не врала.

Дальше — набор по задачам. Не «топ инструментов», а карта «какая задача — чем закрывается». Многое из этого — то, чем я пользуюсь каждый день.

Диаграммы как код

Главная идея, которую стоит усвоить раньше любого конкретного инструмента: схему можно писать текстом, а не рисовать. Вы описываете диаграмму на простом языке, а движок рендерит картинку. Звучит как лишний шаг — а на деле это меняет всё.

PlantUML — рабочая лошадка для этого. UML, C4, sequence — всё описывается текстом. Вся моя графика-как-код живёт здесь: sequence-диаграммы, компонентные, C4. Текст диаграммы лежит в репозитории, его ревьюят в пул-реквесте, как обычный код, и он не разъезжается с реальностью, потому что меняется вместе с ней. Mermaid — та же идея, встроенная прямо в Markdown и многие вики, удобна для быстрых схем по месту.

Чтобы это перестало быть абстракцией — вот как «код схемы» выглядит на самом деле. Sequence-диаграмма в PlantUML: между @startuml и @enduml вы перечисляете участников и стрелки между ними. Сплошная стрелка -> — это вызов, пунктирная --> — ответ.

@startuml
actor Клиент
Клиент -> API : POST /orders
API -> DB : INSERT order
DB --> API : id = 123
API --> Клиент : 201 Created
@enduml

Та же диаграмма на mermaid — синтаксис чуть другой (->> вызов, -->> ответ), но идея ровно та же, и блок вставляется прямо в Markdown:

sequenceDiagram
  participant Клиент
  participant API
  participant DB
  Клиент->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: id = 123
  API-->>Клиент: 201 Created

Схема данных (ER) в dbdiagram.io описывается на языке DBML: таблица, столбцы с типами, ключи и связи. Знак > в [ref: > users.id] читается как «много заказов ссылаются на одного пользователя» — связь many-to-one.

Table orders {
  id          integer    [pk]
  user_id     integer    [ref: > users.id]
  status      varchar
  created_at  timestamp
}

Все три фрагмента — обычный текст. Он лежит в репозитории, диффится построчно и ревьюится в пул-реквесте, а движок (сервер PlantUML, mermaid-плагин, dbdiagram) превращает его в картинку. Меняете строку — меняется схема, и в истории git видно, кто и зачем.

PlantUML vs mermaid vs Excalidraw vs Draw.io

Четыре инструмента, которые на практике приходится выбирать чаще всего. Критерий выбора — не «красивее», а «как схема будет жить»: лежит ли она в git, можно ли её продиффить, рисуется ли она в CI вместе со сборкой, удобно ли её ревьюить.

Критерий	PlantUML	mermaid	Excalidraw	Draw.io
Хранение в git	текст (.puml)	текст (в Markdown)	JSON, но правят мышкой	XML, но правят мышкой
Осмысленный дифф	да, построчный	да, построчный	нет (дифф JSON нечитаем)	нет (дифф XML нечитаем)
Рендер в CI	да (jar / docker-сервер)	да (mermaid-cli)	нет, рисуется руками	частично (drawio CLI), редко
Ревью в пул-реквесте	правишь текст, видно изменение	правишь текст, видно изменение	только сравнить картинки	только сравнить картинки
Где сильнее всего	UML, C4, sequence «по-взрослому»	быстрые схемы прямо в вики/README	наброски на созвоне	произвольная схема мышкой

Грубое правило: долгоживущая и точная схема (контракт интеграции, архитектура сервиса) — PlantUML или mermaid; одноразовый набросок — Excalidraw; что-то нестандартное, под что нет языка, — Draw.io мышкой. mermaid выигрывает там, где схема должна быть прямо в README или вики без отдельного рендер-сервера; PlantUML — там, где нужны полноценный UML и C4.

Быстрые наброски

Обратная сторона: не всё надо превращать в код. Когда вы на созвоне за пять минут объясняете идею или набрасываете черновик, который завтра выкинете, — текстовый движок только мешает. Тут нужен лист и маркер.

Excalidraw — для этого идеален. Это единственный диаграммер, в котором не тянет полировать: нарочито «карандашный» стиль сразу говорит «это черновик, не финальный документ», и никто не воспринимает набросок как контракт. Правило простое: одноразовое и для разговора — рисуйте от руки в Excalidraw; долгоживущее и точное — пишите кодом.

BPMN

BPMN — особый случай: у него строгая нотация со своими правилами, и удобнее рисовать в редакторе, который эти правила знает и подсказывает. Storm BPMN — рабочий инструмент под нотацию, не игрушка, рекомендую именно его для BPMN. bpmn.io (движок, на котором построен моделлер Camunda) — открытый редактор BPMN, удобен, если процесс потом пойдёт в исполнение в Camunda. Подробнее про саму нотацию — в записи какую нотацию когда использовать, а как читать BPMN по символам — в записи BPMN на практике.

API-контракты

Контракт API — это тоже код, и ведётся он текстом. OpenAPI (бывший Swagger) — стандарт описания REST-API в YAML: эндпоинты, параметры, схемы запросов и ответов, коды ошибок. Редактируют в Swagger Editor (показывает ошибки и рисует интерактивную документацию) или Stoplight (визуальный редактор поверх того же OpenAPI). Для событийных, асинхронных интеграций — очереди, топики Kafka — есть родственный стандарт AsyncAPI. Контракт в YAML диффится и ревьюится так же, как диаграмма-как-код. Что вообще должно быть в контракте — в записи REST API для аналитика.

Вот как выглядит фрагмент контракта — операция создания заказа с телом запроса и схемой ответа:

paths:
  /orders:
    post:
      summary: Создать заказ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId, items]
              properties:
                userId: { type: integer }
                items:  { type: array, items: { type: integer } }
      responses:
        "201":
          description: Заказ создан
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

Контракт как источник правды (contract-first)

Ценность OpenAPI не в красивой документации, а в том, что из контракта вырастает всё остальное. Это подход contract-first (spec-driven): сначала договариваются о контракте, потом по нему параллельно работают обе стороны интеграции. Из одного YAML-файла получают сразу несколько вещей:

• Моки. Prism (от Stoplight) поднимает фейковый сервер прямо по контракту: фронт и смежная команда начинают звать API ещё до того, как бэкенд написан. Контракт согласовали — интеграцию уже можно собирать.
• Клиенты и серверные заготовки (SDK). openapi-generator генерирует клиентский код на нужном языке и каркас сервера прямо из контракта — никто не переписывает модели руками и не расходится с правдой.
• Валидацию. API-gateway или middleware проверяет каждый запрос и ответ на соответствие схеме: пришло поле не того типа — отлуп до того, как кривые данные дойдут до логики. Контракт перестаёт быть бумажкой и начинает работать в рантайме.

База знаний и журнал решений

Схемы и контракты — это «что». Но не менее важно «почему»: почему выбрали такую интеграцию, почему отказались от очереди, какие были альтернативы. Это журнал решений, и его стоит вести отдельно. Confluence — корпоративный стандарт, общая вики команды. Obsidian — для личных заметок и журнала решений: журнал решений и мои личные заметки живут именно здесь, локально и в Markdown. Связку обычно делят так: личное и черновики — в Obsidian, согласованное и общекомандное — в Confluence.

Задачи и схемы данных

Задачи и бэклог ведут в трекере: Jira (индустриальный стандарт) или YouTrack. Для аналитика трекер — это не просто список дел, а место, где требование связано с задачей разработки, тестом и релизом. Схемы данных (ER-диаграммы) удобно рисовать в dbdiagram.io — там та же идея «как код»: пишете описание таблиц текстом, получаете ER-диаграмму. Draw.io — универсальный бесплатный редактор «нарисовать что угодно», когда под задачу нет специализированного инструмента.

Задача → инструмент

Задача	Инструмент
UML, C4, sequence (долгоживущие, точные)	PlantUML, mermaid
Быстрый набросок на созвоне	Excalidraw
BPMN-процесс	Storm BPMN, bpmn.io / Camunda
REST API-контракт	OpenAPI в Swagger Editor / Stoplight
Асинхронная интеграция (очереди, события)	AsyncAPI
База знаний, журнал решений	Confluence (общее), Obsidian (личное)
Задачи и бэклог	Jira, YouTrack
ER-диаграммы, схемы данных	dbdiagram.io, Draw.io

Честная цена «диаграмм как код»

«Как код» — не бесплатно, и продавать его как серебряную пулю нечестно. За что вы платите:

• Нужен рендер-пайплайн. Текст сам по себе картинку не покажет: где-то должен крутиться движок (сервер PlantUML, mermaid-плагин в вики, рендер в CI). Если его не настроить, в пул-реквесте лежит непонятный исходник, который никто не открывает глазами. Это разовая настройка, но её надо сделать.
• Кривая входа. Синтаксис надо выучить, и первые схемы пишутся медленнее, чем рисуются мышкой. Окупается это только на схемах, которые живут долго и меняются не раз.
• Сложную раскладку мышкой делать проще. Когда важно точное расположение блоков (большая схема для презентации, нестандартная компоновка), движок авторазметки начинает мешать, и в Draw.io вы сделаете это быстрее и аккуратнее.

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

Частые вопросы

Какие инструменты нужны системному аналитику?

Минимальный набор по задачам: PlantUML или mermaid для диаграмм-как-код (UML, C4, sequence), Excalidraw для быстрых набросков, отдельный редактор для BPMN (Storm BPMN, bpmn.io), OpenAPI/Swagger для API-контрактов, Confluence или Obsidian для базы знаний и журнала решений, Jira или YouTrack для задач. Не нужно учить всё сразу — берите инструмент под конкретную задачу.

Чем рисовать UML и BPMN?

UML, sequence и C4 удобнее всего писать кодом в PlantUML или mermaid — такие схемы диффятся, ревьюятся и не разъезжаются с проектом. BPMN со своей строгой нотацией лучше рисовать в специализированном редакторе: Storm BPMN или bpmn.io (движок моделлера Camunda). Для одноразового наброска на созвоне подойдёт Excalidraw.

В чём вести API-контракты?

REST-контракты ведут в стандарте OpenAPI (бывший Swagger) — это YAML с эндпоинтами, параметрами, схемами и кодами ошибок; редактируют в Swagger Editor или Stoplight. Для асинхронных интеграций (очереди, Kafka) есть родственный стандарт AsyncAPI. Контракт в YAML лежит в git, диффится и ревьюится наравне с кодом.