数学公式排版：PlantUML 与 Mermaid 混排公式

简介

架构图里出现公式并不罕见：求根公式、折扣公式、SLA 的百分比、队列的期望等待时间。传统做法是把公式写成纯文本（x = (-b +- sqrt(b^2-4ac)) / (2a)），可读性直接归零；另一个极端是把公式截图贴进图里，改一个数字就要重画。

两个引擎都原生支持 LaTeX 风格公式。PlantUML 走 MathJax 路线：用 <math>...</math> 标签嵌进类图注释，或用 @startmath / @startlatex 单独画一张公式图；Mermaid 走 KaTeX 路线：在节点标签里写 $$...$$，渲染时自动排版成分式、根号和上下标。本文用同一个二次方程求根公式画出两版，说明各自能写什么、以及最容易踩的坑。

PlantUML 版

PlantUML 的 <math> 标签可以放进任何能写文字的地方，最常用的是 note。写一个带求根公式的类图：

1
2
3
4
5
6
7
8
9
10
11
12

@startuml
class Quadratic {
  {field} double a
  {field} double b
  {field} double c
  {method} double root1()
  {method} double root2()
}
note right of Quadratic
  <math>x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}</math>
end note
@enduml

渲染后公式不是文字，而是一张内嵌的矢量图：分式的横线、根号的钩子、± 符号都是真正的路径。

要点：

• 必须用 <math> 标签，且内容是 LaTeX：写 $x^2$ 或裸文本都只会被当成普通字符串原样显示——$ 不会触发任何排版。

• 反斜杠要成对：LaTeX 命令如 \frac、\sqrt、\pm 都以反斜杠开头。

• 花括号是分组，不是字面量：b^2 - 4ac 里的 ^ 只作用于紧跟其后的一个字符；要给整个表达式上标，写 b^{2 - 4ac}。

• 单独的公式图：把 @startuml 换成 @startmath（或 @startlatex）起头、结尾，公式独占一张图，适合公式本身就是要讲的内容时：

  1 2 3

  @startmath sum_(i=1)^n i = n(n+1)/2 @endmath

  注意：@startmath 与 @startuml 不能混在同一个文件里互相嵌套，一个文件只渲染其中一种块。

• @startmath 与 @startlatex 的差别：@startmath 走 AsciiMath 风格，sqrt(4)、text(hello)、root(2) 这类函数式写法能被解析；@startlatex 只认 LaTeX 语法（\sqrt{4}、\frac{a}{b}）。两者的 \frac{a}{b}、\sqrt{4} 都能用，所以默认用 @startlatex 更保险。

Mermaid 版

Mermaid 节点标签里的公式用 KaTeX 渲染，规则和 Markdown 里写数学公式一致：单美元符号 $...$ 用于行内公式，双美元符号 $$...$$ 用于独立公式。在 Mermaid 中要用 $$，因为节点标签本身已经处在引号里。

1
2
3
4
5

flowchart LR
  Q["Quadratic: ax^2 + bx + c = 0"] --> R["$$\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$"]
  R --> X1["$$x_1 = \frac{-b + \sqrt{D}}{2a}$$"]
  R --> X2["$$x_2 = \frac{-b - \sqrt{D}}{2a}$$"]
  R -.-> S["$$D = b^2 - 4ac$$"]

要点：

• 用 $$ 而不是 $：实测单 $...$ 在节点标签里不会触发 KaTeX，公式会以字面量 $\frac{...}$ 显示；$$...$$ 才会真正排版。
• 标签必须加引号：R["$$...$$"] 里含空格、反斜杠和花括号，不加引号会被 Mermaid 的语法解析器截断或报错。
• 反斜杠在 Mermaid 里不用转义：\frac 直接写。但要注意 Markdown 渲染器处理代码块时不会改写反斜杠，所以博客正文里也是原样保留。
• KaTeX 能力边界：KaTeX 支持分式、根号、上下标、矩阵、对齐等常用结构，但不支持 \begin{equation} 这类需要完整 LaTeX 编译环境的宏包，也不支持 TikZ 绘图。
• 节点尺寸会随公式变化：KaTeX 渲染进 foreignObject 后，节点宽度按公式实际宽度计算，含长分式的标签会把相邻节点推得更远——这是正常的排版行为，不是渲染失败。

对比

选择建议：需要把公式当主角——单独一张公式图、或公式里用到 AsciiMath 风格的函数式写法——用 PlantUML 的 @startlatex / @startmath。需要公式只是图上的一个注解、并且要和流程箭头混排，用 Mermaid 的 $$...$$ 更省事，因为 Mermaid 本身就是围绕流程关系设计的。

小结

公式排版的关键不是”能不能写”，而是”写在哪、用哪种方言”。PlantUML 把公式当一等公民：<math> 标签能嵌进任何文字位置，@startmath / @startlatex 还能单独成图。Mermaid 把公式当标签内容：$$...$$ 在节点里排版，但受限于 KaTeX 子集与标签语法。两者共同的红线只有一条——别忘了标签或公式环境本身：PlantUML 忘了写 <math>，Mermaid 忘了写 $$，结果都只是屏幕上一串没人看得懂的字符。