为MySQL项目生成Doxygen文档，核心思路是让Doxygen识别SQL文件并把表、视图、存储过程、函数当作“模块”解析。Doxygen原生不支持SQL语言，但提供了FILTER_PATTERNS机制，可以用外部脚本把SQL注释翻译成Doxygen能懂的近似C++伪代码，从而提取结构信息。
一、为什么用Doxygen管理MySQL文档
在多人协作的数据库开发中，表字段含义、存储过程参数往往只存在于个别成员的脑子里。当业务变更导致脚本修改，文档不同步就会引发误用。Doxygen的优势在于“注释即文档”，只要开发者按规范写注释，执行一条命令就能产出带检索和继承关系的网页。
相比在Confluence或Wiki上手写说明，Doxygen方案把文档生命周期绑定到代码仓库。每次合并SQL脚本，CI可自动重新生成文档并发布，避免人为遗漏。对于拥有上百个存储过程的老系统，这种自动化尤其有价值。
二、编写兼容Doxygen的MySQL注释
Doxygen依靠特殊注释块（如/** ... */）提取信息。在SQL文件里，我们可以在CREATE语句前添加这类注释，并用@table、@param等命令描述结构。下面示例展示了一张用户表的注释写法。
/** * @table users 用户基础信息表 * @details 存储系统注册用户的核心字段，状态字段控制登录权限 */ CREATE TABLE users ( id INT PRIMARY KEY COMMENT '用户唯一编号', name VARCHAR(50) NOT NULL COMMENT '登录名', status TINYINT DEFAULT 1 COMMENT '1正常 0禁用' );
对于存储过程，要用@proc标识，并在体内用@param描述入参。注意MySQL的COMMENT关键字和Doxygen注释互不冲突，前者写进数据字典，后者用于生成静态站。如下过程演示了如何注释一个简单查询。
/** * @proc get_user_status 获取用户状态 * @param uid 用户ID */ CREATE PROCEDURE get_user_status(IN uid INT) BEGIN SELECT status FROM users WHERE id = uid; END;
三、配置Doxygen识别SQL文件
默认Doxygen会忽略.sql文件，需要在配置文件Doxyfile里设置EXTENSION_MAPPING将sql映射为cpp类型，再借助FILTER_PATTERNS调用过滤脚本。这样Doxygen会先让脚本处理文件，再把结果当C++解析。
EXTENSION_MAPPING = sql=cpp FILTER_PATTERNS = *.sql=sql2dox.py INPUT = ./sql_scripts RECURSIVE = YES GENERATE_HTML = YES
过滤脚本sql2dox.py的作用是把MySQL注释原样保留，同时将CREATE TABLE等语句转成类声明，让Doxygen建立实体关联。一个简单的Python实现如下，它仅做行过滤与关键字替换，实际项目可扩展为完整解析器。
import sys
# 读取sql文件并输出doxygen可识别文本
for line in sys.stdin:
line = line.replace('CREATE TABLE', 'class')
line = line.replace('CREATE PROCEDURE', 'void')
sys.stdout.write(line)
四、生成与查看文档
完成配置后，在终端运行doxygen Doxyfile，工具会在OUTPUT_DIRECTORY指定的路径生成html目录。打开index.html即可看到按表、过程分组的导航，点击表名能展开字段注释与关联关系图。
如果文档中出现乱码，通常是编码问题，需在Doxyfile设置UTF-8：DOXYFILE_ENCODING = UTF-8，并且SQL文件保存为无BOM的UTF-8。此外，给重要脚本打@todo标签，还能在文档里汇总待办，方便技术负责人跟踪。
五、实践中的注意事项
第一，过滤脚本越简单越稳。复杂正则可能误伤SQL语法，导致Doxygen报错退出。建议先小范围跑通再推广到全库。第二，MySQL的触发器与事件调度器注释支持较弱，可单独写markdown页面用@include引入。
第三，将文档生成加入Git钩子或流水线，能保证团队随时访问最新版。当表结构重构时，旧文档自动失效并被覆盖，从机制上解决了“说一套做一套”的隐患。长期坚持，数据库知识资产便自然沉淀下来。