Синтаксис диаграммы требований Mermaid.js и руководство по отслеживанию

Диаграмма требований — это специализированный инструмент визуализации инженерных разработок, используемый системными архитекторами, менеджерами продуктов и программистами для составления технических спецификаций, ограничений системы и тестов проверки. Созданная на основе стандарта SysML (язык системного моделирования), встроеннаяrequirementDiagramсистема позволяет напрямую связывать абстрактные требования к проектированию с физическими компонентами системы и тестовыми случаями с помощью текстовых объявлений.

Понимание элементов диаграммы требований

Диаграмма требований в основном состоит из двух различных структурных элементов:Блоки требований (которые определяют правила) иБлоки элементов (которые моделируют код, аппаратное обеспечение или тестовые скрипты). Затем между этими блоками проводятся связи, чтобы создать четкую матрицу отслеживаемости.

Базовая структура синтаксиса

Каждая диаграмма начинается с заголовкаrequirementDiagramобъявления. Затем следует определение блоков требований с вложенными свойствами, блоков элементов и направляющих линий отношений.

requirementDiagram
  requirement test_req {
    id: 1
    text: "Система должна обрабатывать платежи безопасно."
    risk: high
    verifymethod: test
  }

Полная классификация типов требований

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

• requirement: Стандартная или общая спецификация системы.
• functionalRequirement: Определяет действие или поведенческую способность, которую система должна выполнять.
• interfaceRequirement: Определяет точки подключения, обмены данными или протоколы связи между компонентами.
• performanceRequirement: Задает измеримые метрики выполнения, такие как скорость, масштабируемость, пропускная способность или емкость.
• physicalRequirement: Определяет ограничения по материалу, размерам, весу или аппаратным ограничениям.
• констрейнт проектирования: Ограничивает выбор программного обеспечения, архитектурных стилей, фреймворков или стандартов соответствия.

requirementDiagram
  designConstraint legacy_constraint {
    id: "CON-04"
    text: "Бэкенд должен поддерживать обратную совместимость с пайплайнами PHP 8.2."
    risk: low
    verifymethod: inspection
  }

Справочник синтаксиса: элементы требований и модификаторы

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

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

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

Поддерживаемые операторы отношений

Пользовательские элементы и расширенные атрибуты

Помимо стандартных требований, ключевое слово element позволяет отображать конкретные скрипты приложения, аппаратные компоненты или сторонние пакеты в ваших путях отслеживания. Каждый блок элемента может хранить пользовательские свойства метаданных ключ-значение, используя схему type: внутри фигурных скобок.

requirementDiagram
  element payment_gateway_api {
    type: "Stripe Microservice Module"
  }
  
  element compliance_audit_log {
    type: "Immutable Database Table"
  }

Реальный чертеж: Сложная инфраструктура безопасности электронной коммерции

Этот всесторонний чертеж отслеживает полную экосистему производственной соответствия. Он демонстрирует декомпозицию через contains, отображает ограничения производительности, подключает программные модули через satisfies, и отображает случаи интеграционного тестирования с помощью verifies циклов.

requirementDiagram
  
  %% Уровень иерархии требований
  requirement security_master_req {
    id: "SEC-001"
    text: "Платформа приложения должна строго соответствовать стандарту PCI-DSS."
    risk: high
    verifymethod: test
  }

  performanceRequirement checkout_speed_req {
    id: "PERF-22"
    text: "Ручные операции аутентификации с использованием криптографии MFA должны компилироваться за время менее 200 мс."
    risk: medium
    verifymethod: analysis
  }

  interfaceRequirement secure_token_req {
    id: "INT-09"
    text: "Передача данных API должна использовать зашифрованные JSON Web Tokens (JWT)."
    risk: high
    verifymethod: test
  }

  %% Уровень элементов системы
  element auth_service_code {
    type: "Go Backend Microservice"
  }

  element load_tester_script {
    type: "K6 Performance Script"
  }

  element jwt_validator_test {
    type: "Jest Integration Unit Suite"
  }

  %% Архитектурные пути взаимосвязей
  security_master_req - contains -> checkout_speed_req
  security_master_req - contains -> secure_token_req
  
  auth_service_code - satisfies -> secure_token_req
  load_tester_script - verifies -> checkout_speed_req
  jwt_validator_test - verifies -> secure_token_req

Распространённые ошибки синтаксиса и системные ограничения

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

• Обязательные двойные кавычки для строк: Блоки текста и типы (например, text: "Description", type: "Component") *должны* быть заключены в двойные кавычки. Использование одинарных кавычек или оставление строк без кавычек приведёт к сбою компилятора.
• Строгий синтаксис атрибутов: Атрибуты внутри фигурных скобок должны использовать двоеточия, за которыми непосредственно следуют значения (например, id: 1). Пропуск двоеточия или запись их в одной строке без правильного отступа может вызвать ошибки.
• Ограниченный выбор значений: The risk и verifymethod параметры принимают только явные системные токены (например, low, medium, high для risk; analysis, demonstration, inspection, test для verifymethod). Ввод пользовательских значений, таких как risk: extreme нарушит работу конструктора макетов.
• Целостность интервала стрелок: Направленные линии должны вводиться с пробелами вокруг операторов (например, A - satisfies -> B). Сжатие строки в A-satisfies->B будет игнорировать исключения обработки системы.