C++ Mermaid实战：从Doxygen注释到类图自动生成（组合、聚合、关联详解）-CSDN博客

1. 为什么我们需要自动生成类图？

如果你写过C++项目，尤其是那种规模稍微大一点的，比如超过十个类，几十个文件，你肯定有过这样的经历：新同事入职，或者自己隔了几个月再回来看代码，面对一堆头文件和源文件，脑子里一片空白。ClassA 里有个 ClassB 的指针，ClassC 又继承了 ClassA，ClassD 和 ClassE 之间好像还有某种管理关系……这些关系光靠看代码，得在编辑器里来回跳转，像走迷宫一样，效率极低，还容易出错。

这时候，一张清晰的类图（Class Diagram）简直就是救命稻草。它能直观地展示出类与类之间的继承、组合、聚合、关联等关系，让你一眼看清整个系统的骨架。但问题来了，画图太麻烦了！用 Visio、Draw.io 这些工具手动画，代码一改，图就得跟着改，维护成本高得吓人，最后往往图跟不上代码，成了“历史文物”。

所以，我们追求的是 “文档即代码，图表自动化”。最好的状态是，我们只需要在写代码的时候，按照一定的规范添加注释，然后运行一个命令，最新的、准确的类图就自动生成了。这不仅能保证文档的实时性，还能把我们从重复的绘图劳动中解放出来。

要实现这个目标，两个工具是关键：Doxygen 和 Mermaid。Doxygen 是老牌的代码文档生成器，能从你的源代码注释中提取信息，生成HTML、PDF等格式的文档。而 Mermaid 是一个用文本描述来生成图表的强大工具，语法简单直观。把它们俩结合起来，就能实现我们“注释生成图表”的梦想。这篇文章，我就来手把手带你走通这条路，重点攻克C++里最让人头疼的几种关系——组合、聚合、关联——在代码和图表中如何准确表达。

2. 环境搭建：让工具链就位

工欲善其事，必先利其器。我们先得把需要的工具装好。整个过程其实不复杂，跟着步骤来就行。

2.1 安装 Doxygen 与 Graphviz

Doxygen 是核心，它负责解析你的代码。Graphviz 是一个开源的图形可视化软件包，Doxygen 可以用它来生成包含关系图的文档。

在 Ubuntu/Debian 系统上： 打开终端，一行命令搞定：

sudo apt-get update
sudo apt-get install doxygen graphviz

在 macOS 上： 如果你用 Homebrew，那就更简单了：

brew install doxygen graphviz

在 Windows 上： 建议直接去 Doxygen 官网下载安装程序，图形化界面安装很方便。记得在安装向导里，勾选上“安装 Graphviz”的选项，或者自己额外下载 Graphviz 安装，并把它的 bin 目录添加到系统的 PATH 环境变量里。

安装完成后，在终端里输入 doxygen --version 和 dot -V（Graphviz 的命令行工具），如果都能显示出版本号，说明安装成功。

2.2 配置 Doxygen 支持 Mermaid

默认情况下，Doxygen 使用 Graphviz 的 dot 工具来画图。但我们要用更灵活的 Mermaid。新版本的 Doxygen（1.9.x 及以上）已经内置了 Mermaid 支持，只需要在配置文件中打开它。

首先，为你的项目生成一个默认的 Doxygen 配置文件：

doxygen -g Doxyfile

这会生成一个名为 Doxyfile 的配置文件。用你喜欢的文本编辑器（比如 VSCode、Vim）打开它。

找到以下几行配置，并进行修改：

# 启用类图生成
HAVE_DOT = YES
CLASS_DIAGRAM = YES

# 关键！将生成图表的工具从 dot 切换到 mermaid
DOT_IMAGE_FORMAT = svg
USE_MDFILE_AS_MAINPAGE = NO

# 搜索并确保以下关于 Mermaid 的选项是打开的
# 通常它们默认就是 YES，但检查一下没错
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES

# 对于较新版本的 Doxygen，直接设置使用 Mermaid
DIAFILE_DIRS =
MSCFILE_DIRS =
DOTFILE_DIRS =

# 重要：指定使用 Mermaid.js
USE_MDFILE_AS_MAINPAGE = NO

实际上，对于 Mermaid 支持，最关键的往往是一个叫 DOT_IMAGE_FORMAT 的选项。但更直接的方法是，确保你的 Doxygen 版本足够新，然后在配置文件中寻找 Mermaid 相关的选项。如果找不到，别担心，我们主要靠注释语法来驱动。

一个更稳妥的办法是，在 Doxygen 的配置向导（doxywizard）里，可以看到所有图形相关的选项，并勾选“使用 Mermaid”之类的选项。不过，我习惯直接改配置文件，心里有底。

2.3 准备你的 C++ 项目

为了演示，我们创建一个简单的示例项目。假设我们在做一个“动物园管理系统”的模拟。项目结构如下：

zoo_project/
├── include/
│   ├── Animal.h
│   ├── Mammal.h
│   ├── Bird.h
│   ├── Enclosure.h
│   └── Zoo.h
├── src/
│   └── (相应的 .cpp 文件)
└── Doxyfile

接下来，我们就往这些头文件里填充代码和关键的 Doxygen 注释。