利用Mermaid在Markdown中快速构建数据库ER图

1. 为什么我放弃了Visio，选择在Markdown里画ER图

不知道你有没有过这样的经历：项目评审会上，你花了半天时间用Visio或者某个在线绘图工具画好的数据库ER图，在演示时因为格式错位、字体不兼容，或者干脆因为对方电脑没装对应软件而变得一团糟。又或者，你更新了数据库表结构，却忘了同步更新那份“孤零零”的Word文档里的ER图，导致后来接手的同事对着过时的文档一头雾水，踩了坑还得找你“算账”。

我以前就经常被这些问题困扰。作为一个常年和数据库、API文档打交道的人，我深知清晰、准确、可维护的文档有多重要。ER图（实体关系图）是数据库设计的蓝图，它用图形化的方式展示了数据表（实体）以及它们之间的关系（关系），是开发、测试、产品经理之间沟通的“通用语言”。但传统的绘图工具，总是让我觉得和代码、文档是“两张皮”，维护成本太高。

直到我开始在Markdown文档里写技术方案，并发现了Mermaid这个宝藏。Mermaid是一个基于JavaScript的图表绘制工具，它允许你用纯文本的方式描述图表，然后自动渲染成图形。最关键的是，它被GitHub、GitLab、Notion、Typora等一大堆主流Markdown编辑器和平台原生支持。这意味着，你写的这份包含ER图的Markdown文档，无论是在本地用VS Code打开，还是提交到Git仓库在线浏览，或者分享到团队知识库，图表都能原样、正确地显示出来，彻底告别了格式兼容性的噩梦。

用Mermaid在Markdown里画ER图，本质上就是把数据库设计“代码化”了。你的图表定义就是一段文本，可以和你的数据库迁移脚本、模型定义代码放在同一个Git仓库里，一起进行版本管理。改了一个字段？直接修改对应的Mermaid文本描述，提交代码，图表就自动更新了。这种“文档即代码”的思路，让文档真正活了起来，成为了开发流程中自然的一部分，而不是事后补的、容易过时的负担。

2. 5分钟上手：Mermaid ER图的核心语法拆解

别被“语法”这个词吓到，Mermaid画ER图的语法非常直观，几乎就是在用英语句子描述你脑海中的图。我们从一个最简单的例子开始，假设我们要为一个博客系统设计数据库，有用户和文章两个实体。

erDiagram
    USER ||--o{ POST : "writes"
    USER {
        int id PK
        string username
        string email
    }
    POST {
        int id PK
        string title
        text content
        int author_id FK
    }

上面这段代码，在支持Mermaid的环境下渲染出来，就是一个标准的ER图。我们来逐行拆解它的意思：

1. erDiagram：这是Mermaid ER图的声明，告诉渲染器：“嘿，我后面要开始描述一个实体关系图了”。这一行必须放在最开头。
2. 定义关系：USER ||--o{ POST : "writes"。这是整张图的灵魂，它定义了两个实体之间的关系。
   • USER 和 POST 就是两个实体的名字。