驯服 Mermaid 类图中的花括号：两条通往罗马的绝妙之路

原创于 2025-08-13 17:16:23 发布 · 848 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#类图 #mermaid #花括号

Mermaid 专栏收录该内容

53 篇文章

订阅专栏

驯服 Mermaid 类图中的花括号：两条通往罗马的绝妙之路

你是否也曾在 Mermaid 类图中，为属性添加一个带对象字面量的默认值，就像这样：

+props: object = { label: "label", value: "value" }

然后，满怀期待地看着屏幕，却只收获了一行冰冷的 Parse error？😱

别灰心，你不是一个人在战斗。这个小小的花括号，可以说是 Mermaid 这种领域特定语言（DSL - Domain-Specific Language）中，类图语法里的一个“终极 Boss”。它规则刁钻，行为古怪，常规的转义方法在它面前纷纷败下阵来。

经过反复的试错和探索，我们发现，要解决这个问题，并非只有一条路可走。下面，我将为你揭示两条都已被证实可行的、通往成功的绝妙之路。

第一回合：常规武器库的全军覆没

在揭晓答案之前，让我们先快速回顾一下那些注定会失败的常规方法。这不仅仅是展示错误，更是理解问题特殊性的关键。

1. 反斜杠 `\` 转义：想当然的失败

我们用最经典的 \ 来转义花括号：

classDiagram
    class SuitSelection {
        +props: object = \{ label: "label", value: "value" \}
    }

结果： Parse error！ 报错信息直指 {，并提示 got 'OPEN_IN_STRUCT'。这证明解析器完全无视了反斜杠，依然将 { 视为一个非法的结构开启命令。

2. 双引号 `"` 包裹：出人意料的失败

我们尝试将整个对象包裹成一个字符串，心想这总该行了吧？

classDiagram
    class SuitSelection {
        +props: object = "{ label: 'label', value: 'value' }"
    }

结果： 同样是 Parse error！ 这揭示了 Mermaid 解析器一个惊人的“怪癖”：它会无视属性默认值外层的双引号，直接扫描内部的字符！当它在字符串内部看到 { 时，依然会判定为语法错误。

结论： 常规武器全军覆没。任何试图用标准字符串转义思维来解决问题的路，都是死路。

第二回合：两条秘密通道的发现

当正门被堵死，真正的探索者会去寻找侧门。我们找到了两个！

秘密通道 A：HTML 实体“宽松模式”

第一条路，是利用 HTML 实体编码，但要用一种非常特殊、不带分号的“宽松模式”。

代码示例：

渲染结果： 完美！🎉

工作原理解析：
这招能成功，堪称一个“美丽的意外”。

骗过解析器：Mermaid 的解析器看到 &#123，因为它后面没有分号 ;，所以没有匹配上一个完整的 HTML 实体。它没有选择报错，而是进入了一种“我看不懂，但我选择放行”的容错模式，将这段文本原封不动地交给了下一环节。
依赖渲染器：最终的 SVG (Scalable Vector Graphics, 可缩放矢量图形) 渲染引擎（浏览器）足够智能，它能够正确地将这个不带分号的 &#123 解码为我们想要的 {。

本质：我们利用了解析器的“不严格”和渲染器的“智能”，绕过了问题。它能用，但更像是一个依赖特定环境的“奇招”。

秘密通道 B：Mermaid “私有转义语法”

第二条路，则更加深入，它触及了 Mermaid 内部设计的、虽然未公开但真实存在的“私有协议”。

代码示例：

渲染结果： 同样完美！🎉

工作原理解析：
这不再是巧合，而是精准打击。

解析器直接识别：Mermaid 的解析器被专门编写过，能够识别以 # 开头、以 ; 结尾的数字编码序列。当它看到 #123;，它会立刻理解：“OK，这是一个内部转义指令，代表字符 {”。
确定性转换：整个过程是确定的、无歧义的，不依赖任何外部环境的“猜测”。

本质：这是 Mermaid 官方为解决此类问题设计的“正规军”，只是它忘了把路线图写进公开的文档里。

终极对决：哪条路才是康庄大道？

既然两条路都能走通，我们应该选择哪一条呢？让我们来一场终极对决。

对比项	方案 A (HTML 实体宽松模式)	方案 B (Mermaid 私有语法)
语法格式	`&#` + 数字	`#` + 数字 + `;`
可读性	稍差，容易与标准 HTML 混淆，但其行为又不标准。	更好，`#...;` 形式独特，一旦了解，就知道是 Mermaid 专属。
健壮性	较低 ⚠️。依赖于解析器的容错行为，未来版本更新可能会失效。	极高 ✅。这是内部设计的标准路径，最稳定、最可靠。
推荐度	仅作为备用知识了解。	强烈推荐，这是最佳实践！ ⭐⭐⭐⭐⭐

结论：虽然两条路都能通向罗马，但方案 B (#123;) 才是我们应该选择的、铺着石板的康庄大道！

Mermaid 类图特殊字符终极生存法则

现在，你可以自信地将这份终极法则收入你的兵器库：

渲染花括号 {}：
- 最佳实践：使用 Mermaid 私有语法 #123; 和 #125;。
渲染 & 符号：
- 直接写 & 即可。因为我们不再使用 & 开头的 HTML 实体，所以不会有任何冲突。
渲染双引号 "：
- 为求绝对稳妥，可使用 #34;。

终极示例（渲染 { key & "value" }）：

掌握了这些法则，你就真正驯服了 Mermaid 类图中的这些特殊字符。下次再遇到它们，你将不再是那个手足无措的开发者，而是一个胸有成竹的“屠龙勇士”！

快乐地绘制图表吧！🚀

📊 表格总结

对比项	方案 A (HTML 实体宽松模式)	方案 B (Mermaid 私有语法)
语法格式	`&#` + 数字	`#` + 数字 + `;`
可读性	稍差，容易与标准 HTML 混淆，但其行为又不标准。	更好，`#...;` 形式独特，一旦了解，就知道是 Mermaid 专属。
健壮性	较低 ⚠️。依赖于解析器的容错行为，未来版本更新可能会失效。	极高 ✅。这是内部设计的标准路径，最稳定、最可靠。
推荐度	仅作为备用知识了解。	强烈推荐，这是最佳实践！ ⭐⭐⭐⭐⭐
工作原理	绕过解析器，依赖渲染器解码。	解析器直接识别并转换。