Mermaid on Liangweidong's blog

Mermaid 与 PlantUML 类图：从 Markdown 画 UML

Fri, 15 May 2015 00:00:00 +0800

为什么用 Markdown 画 UML

UML 工具（Enterprise Architect、StarUML、Visio）的痛点：

商业授权贵
团队协作要共享文件
改一处要打开 GUI 拖拽

文本描述 UML 的方案：

Mermaid：2014 年起，GitHub 原生支持，类图/时序图/流程图 10+ 种
PlantUML：2009 年起，Java 实现，UML 2.5 全覆盖，扩展性最强

Mermaid

类图基础

classDiagram
 Animal <|-- Person
 Person <|.. Man

类图语法

classDiagram
 class Animal {
 +String name
 +int age
 +eat() void
 -breathe() void
 }
 class Person {
 +String id
 +think() void
 }
 class Man {
 +work() void
 }
 Animal <|-- Person // 继承（实心空心三角箭头）
 Person <|.. Man // 实现（虚线空心三角箭头）

关系符号

符号	含义
`<\|--`	继承（extends）
`<\|\..`	实现（implements）
`*--`	组合（Composition）
`o--`	聚合（Aggregation）
`-->`	关联（Association）
`..>`	依赖（Dependency）
`--`	实线链接
`..`	虚线链接

时序图

sequenceDiagram
 participant U as User
 participant A as App
 participant S as Server
 U->>A: 点击登录
 A->>S: POST /login {user, pass}
 S-->>A: 200 {token}
 A-->>U: 跳转到首页

流程图

flowchart TD
 A[开始] --> B{是否登录}
 B -- 是 --> C[首页]
 B -- 否 --> D[登录页]
 D --> E[提交登录]
 E --> F{验证成功}
 F -- 是 --> C
 F -- 否 --> G[错误提示]
 G --> D

状态图

stateDiagram-v2
 [*] --> 待支付
 待支付 --> 已支付: 付款
 已支付 --> 已发货: 发货
 已发货 --> 已签收: 签收
 已签收 --> [*]
 待支付 --> 已取消: 取消
 已取消 --> [*]

ER 图

erDiagram
 USER ||--o{ ORDER : places
 USER {
 int id PK
 string name
 string email
 }
 ORDER {
 int id PK
 int user_id FK
 date created_at
 }

GitHub 原生支持

1
2
3
4
5


# README.md
\`\`\`mermaid
classDiagram
 Animal <|-- Person
\`\`\`

GitHub 会自动渲染成 SVG。

IDEA 集成

IDEA Ultimate 内置 Mermaid 预览：

.md 文件里的 mermaid 代码块
或装 Mermaid 插件

VSCode 集成

装 Markdown Preview Mermaid Support 插件
Ctrl + Shift + V 预览

PlantUML

PlantUML 比 Mermaid 功能强，覆盖 UML 2.5 全套，扩展性更好。

安装

1
2
3
4
5
6
7
8


# Java JRE 8+
java -jar plantuml.jar file.puml

# VSCode 插件
# PlantUML (by jebbs)

# IDEA 插件
# PlantUML integration

类图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@startuml
class Animal {
 +name: String
 +age: int
 +eat(): void
 -breathe(): void
}

class Person {
 +id: String
 +think(): void
}

class Man {
 +work(): void
}

Animal <|-- Person
Person <|.. Man
@enduml

关系

1
2
3
4
5
6
7
8


@startuml
A <|-- B ' 继承
C <|.. D ' 实现
E *-- F ' 组合
G o-- H ' 聚合
I --> J ' 关联
K ..> L ' 依赖
@enduml

时序图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@startuml
actor User
participant "App" as A
participant "Server" as S

User -> A: 点击登录
A -> S: POST /login
S --> A: 200 {token}
A --> User: 跳转到首页
@enduml

流程图（活动图）

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


@startuml
(*) --> "开始"
if "已登录" then
 -->[是] "首页"
 --> (*)
else
 -->[否] "登录页"
 --> "提交登录"
 if "验证成功" then
 -->[是] "首页"
 else
 -->[否] "错误提示"
 endif
endif
@enduml

状态图

1
2
3
4
5
6
7
8


@startuml
[*] --> 待支付
待支付 --> 已支付: 付款
已支付 --> 已发货: 发货
已发货 --> 已签收: 签收
已签收 --> [*]
待支付 --> 已取消: 取消
@enduml

组件图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@startuml
package "Frontend" {
 [Web App]
 [Mobile App]
}

package "Backend" {
 [API Gateway]
 [Auth Service]
 [Order Service]
}

[Web App] --> [API Gateway]
[Mobile App] --> [API Gateway]
[API Gateway] --> [Auth Service]
[API Gateway] --> [Order Service]
@enduml

部署图

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


@startuml
node "Web Server" {
 [Nginx]
 [App]
}

node "Database" {
 [MySQL]
 [Redis]
}

[Nginx] --> [App]
[App] --> [MySQL]
[App] --> [Redis]
@enduml

主题与样式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@startuml
!theme plain
skinparam classAttributeIconSize 0
skinparam classFontSize 14
skinparam classBackgroundColor #F0F0F0

class Foo {
 +method()
}
@enduml

PlantUML Server

如果不想装 Java，可以用自己的 PlantUML Server：

1
2
3
4
5


# 官方
docker run -d -p 8080:8080 plantuml/plantuml-server

# 用法
curl "http://localhost:8080/svg/~1uml@somefile"

或者用公共 PlantUML 服务：https://www.plantuml.com/plantuml/uml/

Mermaid vs PlantUML 对比

维度	Mermaid	PlantUML
渲染	JS（前端）	Java
GitHub 原生	✅	❌（需插件）
类型覆盖	10+	UML 2.5 全
扩展性	一般	强（皮肤、宏）
主题	少	多
性能	较慢（前端渲染）	快（Java 服务端）
上手	简单	较难
输出	SVG	SVG/PNG/PDF

选 Mermaid 的场景：团队用 GitHub Wiki / README、简单图为主、JS 渲染方便 选 PlantUML 的场景：需要严格 UML、复杂时序图、企业级文档

工程化

文档生成器

docsify + Mermaid 插件
GitBook + Mermaid 插件
VuePress + Mermaid 插件
Docusaurus + Mermaid 插件（v3 内置）

CI/CD 集成

GitHub Action 自动校验 Mermaid 语法：

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


# .github/workflows/mermaid-check.yml
name: Mermaid Check
on: [pull_request]
jobs:
 check:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: neenjaw/extract-mermaid-blocks-action@v1
 with:
 output-folder: 'mermaid-blocks'
 - uses: nicolegordon/mermaid-validate-action@v1
 with:
 input: 'mermaid-blocks'

IDE 实时预览

VSCode + Markdown Preview Enhanced：实时预览 Mermaid
IDEA + PlantUML Integration：右键 PlantUML 文件 → Show Preview
Obsidian：原生支持 Mermaid

下一步

想把类图转成代码，看 JetBrains MPS、UML Designer
想要画系统架构图，看 2017-08-15《iOS 应用开发与证书管理》中架构图部分
想要画 UI 原型，看 2014-05-15《Axure 产品原型设计》

参考资料

Mermaid 官方：https://mermaid.js.org/
Mermaid Live Editor：https://mermaid.live/
PlantUML 官方：https://plantuml.com/
PlantUML 中文文档：https://plantuml.com/zh/
PlantUML Server：https://github.com/plantuml/plantuml-server

2024+ 视角（从 Mermaid/PlantUML 到 AI 画图 + 架构即代码）

2015 年写 Mermaid/PlantUML 时，文本画图还是"新事物"；到 2024-2026 年，这两套已经全面成为行业标准，并出现明显分层：

GitHub 原生支持的扩散：
- Mermaid 仍是 GitHub/GitLab 默认渲染引擎
- GitLab 15+ 也支持 PlantUML 渲染
- Notion、飞书、语雀等均原生支持 Mermaid
Mermaid v10/v11 增强：
- 新增 C4 插件（Context/Container/Component）—— 配合 Structurizr 简化架构图
- Git graph 已成为最常被复制的图类型
- Architecture diagram（v10.6+）支持服务、数据库、队列等图标
PlantUML 的 C4-PlantUML 扩展：
- 第三方 C4-PlantUML 让 PlantUML 也能画 C4
- Mermaid 渲染 C4 性能 vs PlantUML 渲染 C4 性能：复杂 C4 图 Mermaid 仍偏慢
AI 画图崛起：
- Mermaid Chart + AI（自动从文字生成图）
- Eraser.io / Whimsical AI（手绘草图转 UML）
- GitHub Copilot Workspace 支持从 issue 描述自动生成架构图
Structurizr DSL 全面胜出"画架构图"场景：
- C4 模型 + Structurizr DSL（Java 生态）+ Structurizr Lite（本地预览）已是画系统架构的事实标准
- 替代品：Mermaid + C4 插件（轻量）、draw.io / diagrams.net（GUI 派）
文档工具集成：
- Docusaurus（v3+）内置 Mermaid
- Hugo + Mermaid 短代码
- VitePress / Astro 都默认支持 Mermaid
新工具涌现：
- Excalidraw（手绘风格，团队协作）
- tldraw（白板式画架构图）
- IcePanel（C4 互动式）
- Ilograph（多视角架构图）
PlantUML 的"危机"：
- 公共 PlantUML Server 经常因负载限速
- 私有 PlantUML Server + Asciidoctor Diagram 仍是企业内部方案
- 一些企业转向 D2（Terrastruct 出品，文本画图新秀，go 生态）

选型更新（2024 视角）：

场景	推荐工具
README/Wiki 简单图	Mermaid（GitHub 原生）
严格 UML（时序/状态/类）	PlantUML
系统架构 C4	Structurizr DSL（首选） / Mermaid C4 插件
手绘风格团队讨论	Excalidraw
互动式架构	IcePanel / Ilograph
AI 辅助	Mermaid Chart AI / Eraser AI
复杂企业文档	PlantUML Server + Asciidoctor

2015 年这篇的"Mermaid/PlantUML 对比"框架至今成立——GitHub 原生选 Mermaid，企业级严格 UML 选 PlantUML。变化的是 C4 模型成为架构图事实标准、AI 辅助画图崛起、私有 PlantUML Server 成为企业首选。

Windows 终端与 Navicat 工具链：cmd / Git Bash / Markdown / Navicat

Sun, 15 Sep 2013 00:00:00 +0800

一、为什么 Windows 仍需要"终端三件套"

2013 年的 Windows 8 时代，PowerShell 3.0 已经成熟，但日常开发还是 cmd + Git Bash + PowerShell 三选一。本文整理 cmd / Git Bash / PowerShell 的常用配置，外加 Markdown 编辑、Mermaid 图表、Navicat 数据库工具这三条"终端之外的工具链"。

阅读建议：本文不重复 “PowerShell 基础命令” 类的入门内容，重点在配置 + 排错。

二、cmd：被低估的"老古董"

2.1 时间显示到秒

cmd 默认 time /t 只显示 HH:MM，要看到秒：

1
2
3
4
5
6


:: 系统变量法
echo %time%

:: 强制格式 HH:MM:SS
for /f "tokens=2 delims=." %%a in ('echo %time%') do set ms=%%a
echo %time:~0,8%.%ms%

更简单的办法：用 prompt：

1

prompt $T $P$G

效果：12:34:56.78 C:\>

2.2 常用快捷键

快捷键	作用
`F7`	显示命令历史
`F8`	搜索历史
`Tab`	路径自动补全（Win 7+）
`Ctrl+C`	中断当前命令
`Ctrl+Insert` / `Shift+Insert`	复制 / 粘贴（Win 10+）

2.3 中文编码

cmd 默认 GBK。chcp 65001 切到 UTF-8，但部分老 exe 还会乱码——这是 cmd 一直存在的老问题。2013 时代推荐用 cmder / ConEmu 替代 cmd（Unicode + 多 Tab）。

2.4 提升到管理员

1
2
3
4
5
6
7
8
9


:: 单次管理员
runas /user:administrator cmd

:: 写脚本时
net session >nul 2>&1 || (
 echo 需要管理员权限！
 powershell start-process cmd -ArgumentList "/c %~f0" -Verb runas
 exit /b
)

三、Git Bash：Windows 上最像 Linux 的终端

3.1 安装

安装 Git for Windows（https://git-scm.com/download/win）时默认带 Git Bash。关键选项：

Use Git from the Windows Command Prompt：勾选（让 cmd 也能用 git）
Checkout Windows-style, commit Unix-style line endings：推荐（文件保留 CRLF，提交时自动转 LF）
Use Windows' default console window：默认即可，追求美化用 Windows Terminal / cmder

3.2 中文乱码

Git Bash 早期（<= 2.10）ls 中文文件名乱码。两种解决：

1
2
3
4
5
6
7
8
9


# 方案 1：让 Git 输出 UTF-8
git config --global core.quotepath false
git config --global gui.encoding utf-8
git config --global i18n.commit.encoding utf-8
git config --global i18n.logoutputencoding utf-8

# 方案 2：终端本身设 UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

git config --global core.quotepath false 这一条最关键——ls 看到的中文文件名会正常显示。

3.3 常用别名（`~/.bashrc`）

1
2
3
4
5
6
7
8


alias ll='ls -la'
alias gst='git status'
alias gco='git checkout'
alias gbr='git branch'
alias glog='git log --oneline --graph --decorate --all -20'
alias gp='git push'
alias gpl='git pull'
alias vim='winpty mvim' # Windows 下 vim 经常需要 winpty

3.4 winpty 与交互式程序

Git Bash 调用 Windows 原生 python.exe、mysql.exe 等交互式程序会丢失方向键/历史。解决：

1
2
3


winpty python # 包装一层
# 或写别名
alias python='winpty python'

2025 时代：微软推出 Windows Terminal + WSL 才是真"现代终端"——但 2013 时代 Git Bash 已经是最佳选择。

四、Markdown 工具链

4.1 Markdown 语法速查

Markdown 在 2013 年已经开始从极客玩具走向主流。三个层次的语法：

基础（CommonMark）：标题、列表、引用、链接、图片、代码块
GFM（GitHub Flavored）：表格、删除线、任务列表、``` 代码围栏
扩展：数学公式（ $...$ ）、Mermaid 图表、PlantUML、目录（TOC）

4.2 数学公式

VSCode / Typora / Obsidian 都支持 KaTeX 风格的数学公式：

1
2
3
4
5
6


行内公式：爱因斯坦 $E=mc^2$

行间公式：
$$
\int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

常用符号速查：

符号	代码	描述
$\sum$	$\sum$	求和
$\prod$	$\prod$	N 元乘积
$\int$	$\int$	积分
$\partial$	$\partial$	偏导
$\nabla$	$\nabla$	梯度
$\alpha$	$\alpha$	希腊字母 alpha
$\leq$ / $\geq$	$\leq$ / $\geq$	小于等于 / 大于等于
$\in$	$\in$	属于
$\emptyset$	$\emptyset$	空集
$\forall$	$\forall$	任意
$\exists$	$\exists$	存在

4.3 Mermaid 图表

Mermaid 2014 年由 Knut Sveidqvist 开源，用纯文本写流程图、时序图、类图、状态图、ER 图。在 GitHub README / VSCode / Typora 里都原生支持。

流程图：

graph TD
 A[用户] --> B{已登录?}
 B -- 是 --> C[展示首页]
 B -- 否 --> D[跳转登录]
 D --> E[输入密码]
 E --> F{验证通过?}
 F -- 是 --> C
 F -- 否 --> G[提示错误]

饼图：

pie
 title 浏览器份额
 "Chrome": 65
 "Safari": 19
 "Firefox": 7
 "Edge": 5
 "其他": 4

4.4 类图（UML）

classDiagram
 class Animal {
 +int age
 +String gender
 +isMammal()
 +mate()
 }
 class Duck {
 +String beakColor
 +swim()
 +quack()
 }
 class Fish {
 -int sizeInFeet
 -canEat()
 }
 Animal <|-- Duck
 Animal <|-- Fish

6 种关系：

关系	标记	含义
泛化	`<\|--`	子类继承父类
实现	`<\|..`	实现接口
组合	`*--`	强拥有（生命周期一致）
聚合	`o--`	弱拥有（可独立）
关联	`-->`	知道对方
依赖	`..>`	使用关系

4.5 PlantUML

PlantUML 2009 年开源，写 UML 还能保留 .puml 文本文件——比 Visio 强在"可版本控制"。需要 Graphviz 支持：

1

plantuml 源文件目录：建议 D:\soft\Graphviz

VSCode 装 PlantUML 插件 + jebbs/plantuml 即可一键预览。

五、Navicat：多数据库管理瑞士军刀

5.1 定位

Navicat Premium 是 PremiumSoft 公司开发的多数据库 GUI 工具，一个客户端同时支持：

MySQL、MariaDB
PostgreSQL、SQL Server、Oracle
SQLite、MongoDB
Redis（早期版本，2020+ 才完善）

5.2 连接配置

新建连接，关键选项：

Host：MySQL 默认 3306，PostgreSQL 默认 5432
SSH 通道：先 SSH 到堡垒机再连数据库（生产环境必备）
SSL：MySQL 5.7+ 强制要求
Advanced → Connection timeout：默认 30s，建议 60s
Advanced → Keepalive interval：120s（防止隧道中断）

5.3 常用功能

数据传输：跨库同步（MySQL → PostgreSQL 异构）
数据同步：表级双向同步
结构同步：表结构差异对比 → 自动生成 ALTER
查询构建器：可视化 SELECT，自动生成 SQL
数据建模：画 ER 图（替代 PowerDesigner 的核心功能）
计划任务：定时备份、转储

5.4 备份与还原

自动运行 → 新建批处理作业：

数据库右键 → 转储 SQL 文件
调度 → 每日 02:00
Windows 任务计划程序配合调用

5.5 与 PowerDesigner 协作

PowerDesigner 做概念模型 (CDM) → 物理模型 (PDM) → 建库 SQL
Navicat 做日常管理 + 数据同步 + 报表

详见 [2014-10-15 设计建模工具：Axure / PowerDesigner / VSCode]

六、PowerDesigner 16.x 速查

6.1 安装

PowerDesigner 16.5/16.6 是 SAP 时代的最后一版。安装路径默认 C:\Program Files\Sybase\PowerDesigner 16。注意：16.7 是民间称呼，实际是 16.6 升级包。

6.2 名称转注释

PD 默认表名/字段名是**逻辑名（Name）+ 物理名（Code）**双轨。批量把 Name 复制到 Comment：

1

Tools → Execute Commands → Edit/Run Scripts

1
2
3
4
5
6
7


' 把所有实体的 Name 复制到 Comment
For Each obj In ActiveModel.Entities
 obj.Comment = obj.Name
 For Each col In obj.Columns
 col.Comment = col.Name
 Next
Next

6.3 全局通用字段

每个表都加 create_by / create_time / update_by / update_time / sys_org_code 字段。用 PD 的 Global Field 模板：

Tools → Model Options → Naming Convention → Default Field，新增：

字段	类型	注释
`create_by`	varchar(50)	创建人
`create_time`	datetime	创建时间
`update_by`	varchar(50)	更新人
`update_time`	datetime	更新时间
`sys_org_code`	varchar(64)	机构代码

6.4 MySQL 8.0 关键字

MySQL 8.0 大量新关键字（EMPTY、OFF、ZONE、PATH、OFFSET 等）——字段名撞关键字会报错。常用对策：

字段加反引号 `field`
改字段名（推荐）
PD 导出时勾选 Quote identifiers

完整关键字表见 MySQL 8.0 官方文档 https://dev.mysql.com/doc/refman/8.0/en/keywords.html。

七、常见问题

7.1 Git Bash 启动慢

~/.bashrc 加载太多东西会卡。用 time bash -c "echo hello" 测试，把慢的命令移到 if [ -n "$PS1" ] 之后。

7.2 cmd 中 UTF-8 编码显示错乱

chcp 65001 后部分 exe 仍乱码——是字体问题。cmd 标题右键 → 属性 → 字体 → Consolas 或 Lucida Console。

7.3 Navicat 连不上 MySQL 8.0

MySQL 8.0 默认 caching_sha2_password 鉴权插件，Navicat 11 之前不支持。两种解决：

1
2


-- 改成 mysql_native_password
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY 'password';

或升级 Navicat 12+。

7.4 Mermaid 中文乱码

某些 Mermaid 版本类名有中文会报错，用引号包起来：

classDiagram
 class "用户" {
 +String 姓名
 +登录()
 }

八、下一步

想看 IDE 编码主战场：[2014-04-15 IntelliJ IDEA 全攻略]
想看数据库建模：[2014-10-15 设计建模工具：Axure / PowerDesigner / VSCode]
想看 Git 工作流：[2014-11-15 Git 与版本控制]

本文写于 2013 年，回看当时：cmd 至今没被 Windows Terminal 完全替代，大量运维老脚本还在用 bat 写；Navicat 至今仍是国产 DBA 的"事实第一选择"——这套工具的生命力超乎想象。