用Mermaid代码化绘制ER图：解决Visio痛点，让数据库设计文档可维护

如果你和我一样每次要画ER图都先在Visio里拖方块拖到心态爆炸然后在连线对齐上浪费大半个小时那这篇分享应该能帮你省下不少时间。我最近在写数据库设计文档时频繁用到ER图试了一圈工具之后现在的主力方案是Mermaid——一个用纯文本语法画图的工具。把ER图的实体、属性、关系用几行代码写出来常见的Markdown编辑器、GitHub都能直接渲染不用装客户端改起来也特别方便。这篇文章主要面向两类人一类是在做数据库课程设计、需要交ER图作业的同学另一类是后端开发或DBA想把表结构梳理成能写进文档、能参与代码评审的ER图。我会从工具选型的思路讲起再把Mermaid画ER图的核心语法、从MySQL表结构反向生成ER图的工作流、以及我踩过的几个坑逐一展开最后附上一份主流画ER图工具的对比方便你按场景选择。1. 为什么我最终放弃桌面端工具改用代码画ER图1.1 画ER图不只是“做个图”它其实是数据库设计的核心产物很多人在搜索里输入“er图怎么画”“er图例题”多半是数据库系统概论课上的作业题——给一个场景比如电影院售票、学生选课然后画出一张实体-联系图。但在实际项目中ER图的价值远不止交作业。它是数据库设计的蓝图先有实体和关系才有表结构和外键索引。你业务规则没理清楚后面建出来的表大概率会返工。ER图里有三个基本要素我简单过一遍实体Entity可以独立存在的事物比如“用户”“电影”“订单”。对应到数据库里通常是一张表。属性Attribute实体的特征比如用户的姓名、注册时间。关系Relationship实体之间的联系比如“用户下了订单”“订单包含商品”。我见过不少同事直接在工具里对着表结构画图画完才想起来这个关系到底是一对多还是多对多结果又删了重画。其实正确的做法是反过来先想清楚业务规则ER图只是把你脑子里那些“一份订单对应多条订单明细”的结构化表达输出出来。这也是我后来坚定选择代码化工具的根本原因——改文字比改图形快得多能让你把精力放在业务梳理上而不是跟软件界面较劲。1.2 传统桌面工具的三大痛点早些年我画ER图用的就是Visio和Rational Rose后来也用过一段时间MySQL Workbench的内置EER图。说实话功能都够强但用起来总有几个地方让人抓狂。第一个痛点是对齐和连线。实体多了以后框的大小、位置、线的走向全要手工调。两个实体之间如果还有环形的多对多关系那连线基本就是一场灾难经常是拖了半天线还是从别的实体身上穿过。这个问题在团队协作时尤其明显A同事画的图B同事接手后第一件事就是重新排版。第二个痛点是版本管理。Visio文件是二进制的改动之后就很难看出到底改了哪个实体、哪条关系。做代码评审的时候根本没法diff只能导出图片然后用微信发来发去最后可能存了三五个版本谁也说不清哪个是最新的。项目里但凡表结构发生过几次变更这个文档基本就废了。第三个痛点是和数据库脱节。很多项目其实都是先有库表后补文档。用Workbench能反向生成EER图但是生成的图拉到文档里格式往往很乱而且一旦你手工调整过布局下次数据库结构变更后再生成所有手工整理又白做了。1.3 代码化方案彻底解决了这些问题Mermaid这类工具的思路跟传统工具完全不同ER图的定义是一段纯文本你把它当作代码来维护。文本可以进Git每次改动都能留下diff记录评审时一眼就能看出哪个实体加了属性、哪条关系被删了。布局由渲染引擎自动完成你不需要关心框的位置和连线的走向写对了语法图就整齐了。渲染结果直接嵌入Markdown文档Typora、Obsidian、GitHub、GitLab都支持写完文档不需要额外导出图片。这样一来ER图从“一张画完就过时的图”变成了“一份能持续维护的数据库设计文档”。我第一次在GitHub仓库里直接看到渲染好的ER图时那种体验真的回不去了。后面几节我重点讲Mermaid的具体用法和实战工作流。2. Mermaid画ER图的核心语法与快速上手2.1 理解erDiagram语法的最小模型Mermaid画ER图用的是erDiagram关键字一个最小示例长这样这里用text代码块展示方便你复制练习erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ ORDER_ITEM : contains ORDER_ITEM }o--|| PRODUCT : includes这个例子是三行“关系声明”每一行的结构是实体 A 关系符号 实体 B : 关系标签关系符号中间那条线代表连接左右两侧的标记表示“基数”。我用生活中的例子解释一下||表示“恰好一个”o{表示“零个或多个”|{表示“一个或多个”o|表示“零个或一个”。所以CUSTOMER ||--o{ ORDER : places翻译过来就是一个客户可以下零个或多个订单一个订单只属于一个客户。反过来读也一样成立。这是标准的关系基数标记只要你记得按照“左实体——关系——右实体”的顺序去读基本不会搞错。2.2 实体属性、主键、外键的表示方法光有关系还不够ER图还得有实体内部的属性。Mermaid里给实体加属性用花括号直接写在实体名后面erDiagram USER { int user_id PK varchar username UK varchar email datetime created_at } ORDER { int order_id PK int user_id FK datetime ordered_at } USER ||--o{ ORDER : places注意几个细节PK和FK是给主键、外键加的类型标记Mermaid不支持PRIMARY KEY这种完整写法直接写PK就行。varchar、int、datetime这些数据类型写在字段前面或后面都行Mermaid主要用它生成更丰满的展示效果。属性的顺序会按照你写的顺序展示建议把主键放第一行外键紧随其后可读性更好。如果你想给属性加注释用双引号包起来放在字段后面比如varchar username 用户登录名。实际渲染的时候每个实体就是一个带属性列表的卡片跟你在教材里见到的实体图风格很像但是完全不需要手工调整位置。2.3 热搜词里的“电影评分与评价”ER图到底怎么画热搜里有条“画出电影评分与评价的er图”我估计这多半是某本数据库教材或课程作业里的原题。我用它来演示一遍完整的思考过程。场景需求是用户可以对电影评分也可以对电影发表评价也就是评论。关键约束是一个用户对同一部电影只能评分一次。先列实体用户User记录用户信息。电影Movie记录电影信息。评分Rating记录用户对电影的评分属于弱实体依赖于用户和电影才能存在。评价Comment记录用户对电影的文字评价可以有多条。评分和评价其实都是“用户-电影”关系上的属性扩展但它们在数据库里通常要拆成独立的表。于是Mermaid定义就是erDiagram USER { int user_id PK varchar nickname } MOVIE { int movie_id PK varchar title int release_year } RATING { int user_id PK, FK int movie_id PK, FK int score datetime rated_at } COMMENT { int comment_id PK int user_id FK int movie_id FK text content datetime created_at } USER ||--o{ RATING : gives MOVIE ||--o{ RATING : receives USER ||--o{ COMMENT : writes MOVIE ||--o{ COMMENT : has这里有个非常重要的设计决策RATING表用(user_id, movie_id)作为复合主键而不是单独设一个自增id。为什么因为业务规则要求“一个用户对一部电影只能评分一次”复合主键天然保证了这个唯一性。而COMMENT表就不需要这个约束用户可以评论很多次所以单独用一个comment_id做主键就够了。这个例子很典型地说明了ER图中的关系基数是如何直接决定表结构的。画图之前多问一句“这个关系到底允许多少条”比你画完再改要省事得多。3. 从MySQL表结构反向生成ER图的完整工作流3.1 为什么你需要反向生成而不是重新画一遍如果你接手的项目已经有一两年历史数据库里几十张表文档早就过期了那“反向生成”几乎是唯一可行路径。手工照着表结构画一遍不是不能做但效率太低而且你手动画的时候很容易漏掉某个外键关系最终图跟实际库表不一致。需要强调一下反向生成的本质是“把建表语句翻译成ER图”。所以底层依赖是表结构里是否定义了外键约束。如果你的历史表从来都不建外键全靠应用层保证关系那任何工具都只能画出孤立的一张张表关系需要你手工补。3.2 我的推荐路径mysqldump Mermaid脚本化处理先说最简单的日常用法用MySQL Workbench的Reverse Engineer功能连上数据库后选择Database - Reverse Engineer它会自动生成一张EER图里面能看到表、字段、索引和外键连线。这个功能的优点是零成本鼠标点几下就有图适合快速浏览表结构。缺点是导出的图不好直接放进文档或Git仓库而且每次重新生成后布局都会变。如果你想得到一份可以版本管理的ER图文本更推荐脚本化方案。思路是先用mysqldump导出只含建表语句的schemamysqldump -u root -p --no-data --skip-comments your_database schema.sql拿到schema.sql之后下一步就是把建表语句转换成Mermaid的erDiagram文本。这一步可以自己写个小脚本解析CREATE TABLE语句和FOREIGN KEY约束也可以直接用社区现成的工具比如mysql-to-mermaid它能把连接信息作为参数直接输出mermaid源码。我个人习惯是把schema.sql保存下来用脚本批量转因为这样每次数据库变更后重新生成git diff里能清楚看到是哪个表变了对做表结构评审非常有帮助。如果你的表结构设计得比较规范——每张表都有主键、外键都显式声明了——那生成结果基本能直接用。我见过不少团队把这个环节做成一个定时脚本每次上线前自动更新docs/db.md里的ER图这个做法我强烈推荐。3.3 反向生成后的检查与修正工具生成的东西通常不能直接交付至少要做三件事第一检查哪些表没有被关系线连上。如果一张表周围冷冷清清没有任何连线先别急着认为它就是独立的字典表。很可能是外键确实没建需要在Mermaid源码里手工加上对应关系。这类表往往就是业务核心表遗漏关系会造成误导。第二处理多对多的中间表。真实数据库里多对多关系拆出来的中间表比如user_role工具生成出来的结果是三张表USER、ROLE、USER_ROLE外加四条连线。保留这样也是准确的但如果文档读者希望快速理解业务可以把中间表重命名为带语义的名字比如user_role改成USER_ROLE_ASSIGNMENT或者在属性里写注释说明“关联用户和角色”。第三统一术语和注释。很多历史表字段名简洁过头单看字段根本不懂含义。反向生成后花一点时间给每个实体、重点属性补上中文注释。有人觉得这是形式工作但一份没有注释的ER图三个月后连你自己都看不懂更别说新入职的同事。4. 主流ER图画图工具的横向对比与选型建议4.1 我用过的工具体验对比为了让你按场景选得更准我把这几年实际用过、或者身边同事常用的一些ER图工具列了一个对比表。这不是参数罗列而是基于真实使用感受工具使用方式是否支持反向生成适合场景我最在意的痛点Mermaid纯文本代码可用脚本实现Markdown文档、代码评审、博客复杂图布局由引擎决定无法微调draw.io拖拽支持导入SQL轻量级快速画图、跨平台多人协作时文件版本管理比较弱MySQL WorkbenchGUI建模原生支持MySQL项目的EER建模导出图的排版不稳定不适合PRNavicatGUI建模原生支持商业项目、可视化管理收费团队内使用有license问题PlantUML纯文本代码可用脚本实现需要类图/用例图/ER图全套的场景需要Java环境语法稍繁琐Visio拖拽需要插件传统企业文档二进制文件无法diffRational Rose拖拽建模支持老牌教材、课程设计作业安装复杂界面老旧这里多说一句热搜词里有“rational rose画er图”估计是不少学校教材还在用Rational Rose教学。如果你只是为了交作业抓一个会用的工具即可不必纠结。但如果你是工作环境中要给团队交付文档我建议优先考虑代码化方案因为可维护性完全不是一个量级。4.2 不同场景最合适的工具选择根据我自己的经验你可以这样选写博客、写接口文档、放GitHub无脑选Mermaid。GitHub原生渲染读者打开就能看到图不需要下载任何软件。做课程设计、交ER图作业如果老师要求手绘风格或有指定工具就用指定工具没有指定的话draw.io上手最快模板齐全。给存量MySQL数据库做完整的模型管理MySQL Workbench最省事反向生成加结构变更都在一个工具里完成。团队协作频率高、表结构经常变更一定选文本化方案Mermaid或PlantUML都行我个人强烈偏向Mermaid。企业交付物里有大量Visio上级模板那就继续用Visio不过建议导出PDF再存档。4.3 关于“MySQL表导出ER关系图”的补充说明热搜里“mysql的表导出er关系图”是一个高频需求。实际上从MySQL导ER图有三种层次第一层是图形化导出Workbench和Navicat都能直接做到适合人肉看图。第二层是文本化导出通过脚本把表结构转成Mermaid/PlantUML适合进版本库。第三层是元数据级导出把库表信息同步到数据字典平台比如Flyway、Liquibase的schema版本管理ER图只是附带产物。如果你只想快速导一张图发给同事第一层就够。如果你想把ER图变成流程里的一部分那我建议花半小时把第二层的脚本路径搭起来一劳永逸。5. 画ER图过程中的常见坑与实操心得5.1 关系基数是最容易画错的地方画ER图最容易出错的就是基数尤其是多对多关系。我见到的典型错误是用户和电影之间画一条带“多对多”的线就完事了。放到数据库里多对多是必须拆成中间表的因为你无法在用户表加一个字段来存“多部电影”也没法在电影表加一个字段存“多个用户”。ER图上正确的表达应该是拆出一个中间实体比如前面例子里的RATING或收藏表然后分别与用户、电影形成一对多关系。判断基数的时候我的习惯是拿两个实物问自己一个A实例最少关联几个B实例最多关联几个B实例反过来再问一遍。两个方向都问完基数才算准。这里尤其容易漏掉“最少”这个约束很多关系其实是“至少一个”而不是“零个或多个”比如一笔订单至少包含一条订单明细画成o{就把业务规则放宽松了。5.2 命名规范和注释补齐ER图画得好不好很多时候看命名是否统一。我给自己定的几条规则实体名用大写下划线比如USER_ACCOUNT这样在Mermaid里更醒目。字段名统一snake_case避免驼峰和下划线混用。主键统一叫表名_id外键统一叫关联表名_id不要出现有的叫userId、有的叫usr_id的情况。每个实体至少配一句注释说明它承载什么业务含义。注释这事容易被忽略因为Mermaid的实体名本身已经很直观了。但等你的项目表多到一定程度你会发现真正有价值的不光是“有哪些表”而是“为什么会有这张表”。比如一张ORDER_HISTORY表如果不写注释别人可能以为它是订单的备份但实际它可能是审计日志。ER图上的注释能很好地传递这类上下文。5.3 把ER图嵌入文档与PR流程的实际体验最后聊聊我把Mermaid ER图用进团队协作后的变化。我们的数据库设计文档是一份Markdown存放在仓库的docs/目录。以前每次评审表结构都是导图、贴图、发群改完再导一次。现在直接在PR描述里写ER图更新 text erDiagram CUSTOMER ||--o{ ORDER : places评审人打开PR页面就能看到渲染后的图改了什么字段、加了哪条关系git diff里一清二楚。不再存在“两份图片分不清哪个新哪个旧”的问题。 踩过几次坑之后我个人的一个体会是工具选哪个不是重点重点是你愿不愿意把ER图当成一份持续维护的设计文档而不是一次性的交付图。代码化工具之所以让我推荐就是因为它能用管理代码的方式去管理设计图让ER图真正活在项目流程里——而不只是躺在某个人的电脑里等下次数据库变更后又变成一张废图。