Mermaid.js 需求图语法与可追溯性指南

需求图是一种专门的工程可视化工具，由系统架构师、产品经理和软件工程师用于绘制技术规范、系统约束和验证测试。基于SysML（系统建模语言）标准，原生requirementDiagram引擎允许您使用基于文本的声明，将抽象的设计需求直接链接到物理系统组件和测试用例。

理解需求图元素

需求图主要由两种不同的结构化构建模块组成：需求块（用于指定规则）以及元素块（用于建模代码、硬件或测试脚本）。然后在这些块之间绘制关系，以创建清晰的可追溯性矩阵。

基本语法结构

每个图表都以requirementDiagram声明头开始。随后通过嵌套属性、元素块和方向性关系线来定义需求块。

Mermaid

在VPasCode中编辑Mermaid

Mermaid Edit Mermaid in VPasCode

requirementDiagram
  requirement test_req {
    id: 1
    text: "系统必须安全地处理支付。"
    risk: high
    verifymethod: test
  }

Edit Mermaid in VPasCode

在VPasCode中编辑Mermaid

完整的需求类型分类体系

并非所有工程需求都具有同等重要性。该引擎提供了六个不同的块关键字，用于从视觉和语义上对您的规范进行分类。每种类型都会改变渲染后图表框内显示的标题标签：

requirement：标准或通用的系统规范。
functionalRequirement：指定系统必须执行的动作或行为能力。
interfaceRequirement：定义组件之间的连接点、数据交换或通信协议。
performanceRequirement：设定可测量的执行指标，例如速度、可扩展性、吞吐量或容量。
physicalRequirement：规定材料约束、尺寸、重量或硬件限制。
设计约束: 限制软件选择、架构风格、框架或合规标准。

Mermaid

在 VPasCode 中编辑 Mermaid

Mermaid Edit Mermaid in VPasCode

需求图
  设计约束 legacy_constraint {
    id: "CON-04"
    text: "后端必须保持与 PHP 8.2 流水线的向后兼容性。"
    risk: low
    verifymethod: inspection
  }

Edit Mermaid in VPasCode

在 VPasCode 中编辑 Mermaid

语法参考：需求元素与修饰符

下表分解了需求解释器原生识别的主要语义关键字、必需属性和分类结构。

语法组件	类型需求	描述与支持的系统属性
声明	关键字标识符	初始化 SysML 需求工作区画布。必须使用确切的 `requirementDiagram` 块标题。
唯一 ID 属性	`id:` 字符串 / 整数	一个必需的嵌套参数，用于在您的跟踪框架内提供跟踪索引或唯一的字母数字引用代码。允许混合空格。
文本属性	`text:` 引号字符串	一个必需的描述性字符串，详细说明项目的实际规范或行为约束。始终用双引号包裹。
风险属性	`risk:` 严重性标志	一个可选的标记，用于跟踪架构风险的严重程度。接受低级别标记：`low`, `中等`，或`高`.
验证属性	`验证方法：` 方法标签	一个可选参数，用于声明规则将如何被证明。接受标准工程值：`分析`, `演示`, `检查`，或`测试`.
系统元素	`元素`模块	使用以下语法声明一个物理组件、软件组件或测试脚本：`element 元素名称 { type: "组件类型" }`.

高级关系与可追溯性链接

需求图的主要功能在于将需求与实际系统连接起来。链接使用专用的、带类型的箭头连接器绘制（例如，- 满足 ->）以明确表达结构意图。

支持的关系操作符

关系语法标记	战略工程意义	方向性流动规则
`源 - 包含 -> 目标`	将一个广泛的父级需求分解为更小的、嵌套的子需求。	从父级需求块指向子需求块。
`元素 - 满足 -> 需求`	证明一个具体的软件或硬件组件成功满足了一条规则。	从 `元素`块指向目标 `需求`块。
`元素 - 验证 -> 需求`	表明特定的测试脚本或测试用例正在检查一条规则的准确性。	从测试 `元素`块指向目标 `需求`块。
`源 - 复制 -> 目标`	表示一个与另一处存在的主需求完全对应的重复需求。	从重复副本指向主原始块。
`源 - 跟踪 -> 目标`	在两个独立的需求之间建立广泛的依赖关系或历史关联。	从依赖需求指向主要目标块。
`源 - 派生 -> 目标`	表明一个需求是直接由另一个需求计算或生成的。	从派生的子块指向源父块。
`源 - 优化 -> 目标`	为高度复杂、高层次的技术规范增加额外的细节或清晰度。	从优化后的规范指向基准目标块。

用户自定义元素与扩展属性

除了标准要求之外，element关键字允许您将特定的应用程序脚本、硬件项目或第三方包映射到您的追踪路径中。每个 element 块可以通过在其大括号内使用type:模式来存储自定义的键值元数据属性。

Mermaid

在 VPasCode 中编辑 Mermaid

Mermaid Edit Mermaid in VPasCode

requirementDiagram
  element payment_gateway_api {
    type: "Stripe 微服务模块"
  }
  
  element compliance_audit_log {
    type: "不可变数据库表"
  }

Edit Mermaid in VPasCode

在 VPasCode 中编辑 Mermaid

现实世界蓝图：复杂的电子商务安全基础设施

这个全面的蓝图追踪了一个完整的生产合规生态系统。它通过contains展示了分解过程，映射性能约束，并通过satisfies连接软件模块，并使用verifies循环来映射集成测试用例。

Mermaid

在 VPasCode 中编辑 Mermaid

Mermaid Edit Mermaid in VPasCode

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 Token (JWT)。"
    risk: high
    verifymethod: test
  }

  %% 系统元素层
  element auth_service_code {
    type: "Go 后端微服务"
  }

  element load_tester_script {
    type: "K6 性能脚本"
  }

  element jwt_validator_test {
    type: "Jest 集成单元套件"
  }

  %% 架构关系路径
  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

Edit Mermaid in VPasCode

在 VPasCode 中编辑 Mermaid

常见语法陷阱与系统约束

在编译精确的工程地图时，请牢记这些验证参数，以防止解析错误：

字符串必须使用双引号：文本块和类型（例如，text: "描述", type: "组件"）必须用双引号包裹。使用单引号或不加引号的字符串将导致编译器崩溃。
严格的属性语法： 大括号内的属性必须使用冒号直接跟随值（例如，id: 1）。忘记冒号或在同一行上书写而没有适当的缩进空格会导致错误。
有限的值选择： risk 和 verifymethod 参数仅接受明确的系统标记（例如，low, medium, high 表示风险；analysis, demonstration, inspection, test 表示 verifymethod）。输入自定义值如risk: extreme 将导致布局构建器崩溃。
箭头间距完整性： 方向性线条必须在操作符周围使用空格分隔输入（例如，A - satisfies -> B）。将字符串压缩为A-satisfies->B 将丢弃系统处理异常。