简介数据字典工具是一款面向数据库管理员与开发人员的自动化文档生成软件。它能够自动扫描数据库中的表、视图、存储过程等对象提取字段名、数据类型、默认值、可空约束及开发注释并按用户要求生成结构清晰的数据库字典文档帮助团队快速理解数据库架构减少手工编写维护文档的工作量。压缩包内共包含十六个文件大小约二点五八兆字节核心是一个可直接运行的可执行文件附带动态链接库、Word与HTML文档模板、文本说明以及用于界面演示的示例图片结构完整下载后即可试用。目前已有五百二十八人学习使用既适合刚接触数据库设计的初学者也适合需要为现有系统快速补全数据字典的中小型项目团队。通过该工具用户不仅能自动生成包含字段注释和关系的文档还能根据提供的模板自定义输出样式直接用于项目交付、评审或团队协作提升数据库管理与交接效率。 接手过一个跑了五六年的老系统数据库里两百多张表前任离职交接时只留下一句“都在库里自己看”。我连着一个星期每天对着 Navicat 翻字段见着status就猜是 0 还是 1见着remark就祈祷注释别是空的。一个月后我终于忍不了了必须把“数据字典工具”这件事系统性解决掉不然以后每个接手的兄弟都得再遭一遍罪。这篇文章不是给你推荐某一个软件完事而是把我从“查系统表拼文档”到“流水线自动生成字典”的全过程、工具选型思路、以及踩过的坑都整理出来。适合刚接手老项目的一线开发、团队里负责数据库规范的人还有那些嘴上说“要有文档”、实际上连注释都不写的项目管理者看。1. 先搞清楚数据字典到底在解决什么痛点1.1 没有字典的团队有多痛很多人以为数据字典就是个“数据库表结构说明书”这理解没错但太浅了。真正的痛点不在于“没有文档”而在于信息在传递过程中层层失真业务方说“我们要看用户状态”开发知道user.status字段 0 是正常、1 是禁用、2 是注销但报表组的人不知道新来的同事不知道三个月后的你自己也不知道。我见过最魔幻的一次DBA 给线上表加了个is_deleted字段默认 0。结果运营那边导数据看到 0 就以为是“已删除”把正常用户全过滤掉了。事后复盘谁都没错错的是这个字段的含义只存在于开发脑子里而数据字典是空的。这种成本远比“写注释多花五分钟”要高得多。1.2 数据字典的三种常见形态按我接触过的项目数据字典有这三种落地形态数据库注释型直接在COMMENT里写字段说明。这是最基础、最不会丢的形态任何可视化工具都能看到。缺点是表达力有限枚举值含义、关联关系写不详细。独立文档型用 Word、Markdown、Confluence 或专门的工具生成独立的表结构文档。信息丰富、可分享但极容易过期——改表的人大概率不会同步去改文档。在线协作平台型像 dbdocs、Bytebase 这类把字典当成一个可以多人编辑、版本管理的“产品”来做字典和表结构之间可以对比 Diff。这三者不是互斥的靠谱的做法是“注释兜底 文档对外 平台协作”后面我会展开讲怎么搭。1.3 一份好字典应该长什么样根据我的经验一份能真正顶用的数据字典至少要包含四层信息表级信息表名、业务含义、负责人、所属模块。字段级信息字段名、类型、长度、是否可空、默认值、字段注释。枚举值说明status的 0/1/2 分别代表什么这是最容易被忽略、又最致命的部分。关联关系这张表和哪些表有外键/逻辑关联order.user_id对应user.id业务分析时才能顺着脉络走。只做到第 1、2 层那叫“会导出数据库注释”做到 3、4 层才叫真正的“数据字典”。2. 主流数据字典工具选型别只盯着“能导出”工具这东西没有最好的只有跟团队现状最匹配的。我把市面上常见的路子分成四类每个都有自己的适用场景。2.1 数据库自带能力系统表与注释所有主流数据库都提供了对元数据的访问接口。MySQL 有information_schemaPostgreSQL 有pg_catalogOracle 有ALL_TAB_COLUMNS连 SQLite 都有PRAGMA table_info()。这类“工具”的优点是零依赖、永远跟数据库同步缺点是只能拿到结构信息拿不到业务信息。说白了你得先有个好的注释习惯否则查出来一堆英文裸字段。2.2 桌面客户端一键导出快但只解决一半问题Navicat、DataGrip、DBeaver 这些客户端基本都带“导出数据库结构”的功能。Navicat 里选中库右键“转储 SQL 文件”或者用“模型”功能就能看到 ER 图和字段列表DataGrip 甚至能把表结构导出成 Markdown 格式。这类方案适合临时救急客户现场要交付文档、领导突然要一份表清单五分钟导出来能交差。但它最大的问题是下一次表结构变了这份文档就废了。它没有“重新生成”的自动化闭环所以我不建议把它当长期方案只能当“快速出活”的手段。2.3 开源工具 screwJava 生态的文档生成利器如果你团队的技术栈是 Java那 screwgithub 上搜 smallbun/screw值得认真对待。它是一个专门生成数据库文档的开源工具支持 HTML、Word、Markdown 三种格式。我为什么喜欢它因为它解决了一个特别恶心的点它读取的是数据库里的 COMMENT只要平时写注释它就能生成一份结构完整的文档不需要额外维护一份“文档里的表结构”。用法也很简单Spring Boot 项目里引入依赖配一下数据源一个命令跑完dependency groupIdcn.smallbun.screw/groupId artifactIdscrew-core/artifactId version1.0.7/version /dependency然后写个测试类或者用它的 Maven 插件指定输出路径和格式直接生成。它会把表注释、字段注释、索引、主键全部带出来长得很接近那种“商业级交付文档”的质感。2.4 在线协作平台适合多人维护的团队如果团队超过十个人、业务线多、字典需要业务方也参与维护那就要考虑在线协作工具了。dbdocs 这类产品可以把数据库连接以后自动拉取 Schema 生成在线文档也可以在界面上手动补充描述还支持版本历史。国内团队如果在意数据安全可以用 Bytebase 或自建的类似系统。这类平台的核心价值在于字典不再是某个人的文本文件而是一个“活”的、有权限管理的资产。代价是需要服务器、需要维护、需要有人推进落地对两三个人的小团队来说可能过重。2.5 我的选型建议团队场景推荐方案理由临时交付/个人使用Navicat/DataGrip 导出五分钟拿到现成文档中小型 Java 项目screw 嵌入 Maven 插件低成本、可自动化多语言/微服务团队Python 脚本连系统表发布到内部 Wiki语言无关、可自定义大规模业务协作dbdocs/Bytebase 类在线平台权限管理、版本控制、多方维护3. 用 SQL 从数据库系统表生成 Markdown 字典零依赖方案如果你不想引入任何第三方工具也不想被某一种语言绑死那我强烈建议你学会一种“万能手艺”直接查系统表自己把结果拼成 Markdown。这个方案能在任何环境、任何语言下落地。3.1 MySQL核心查询长这样以 MySQL 为例表级信息在information_schema.TABLES字段信息在information_schema.COLUMNS-- 表级信息 SELECT TABLE_NAME AS 表名, TABLE_COMMENT AS 表注释 FROM information_schema.TABLES WHERE TABLE_SCHEMA your_database_name; -- 字段级信息 SELECT TABLE_NAME AS 表名, COLUMN_NAME AS 字段名, COLUMN_TYPE AS 字段类型, IS_NULLABLE AS 是否为空, COLUMN_DEFAULT AS 默认值, COLUMN_COMMENT AS 字段注释 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your_database_name;这个查询结果拿到之后用任何脚本语言都能转成 Markdown 表格。关键在于思路先按表名分组每张表生成一个### 表名注释的二级块再把该表的字段矩阵输出成表格。3.2 写个小脚本自动搞定我用 Python 写过一版核心逻辑大概长这样你可以直接参考import pymysql import markdown def generate_dict(db_config, output_file): conn pymysql.connect(**db_config) cursor conn.cursor() # 查表 cursor.execute( SELECT TABLE_NAME, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA %s ORDER BY TABLE_NAME , (db_config[database],)) tables cursor.fetchall() with open(output_file, w, encodingutf-8) as f: for table_name, table_comment in tables: f.write(f### {table_name}{table_comment}\n\n) f.write(| 字段名 | 类型 | 可空 | 默认值 | 注释 |\n) f.write(| --- | --- | --- | --- | --- |\n) cursor.execute( SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA %s AND TABLE_NAME %s ORDER BY ORDINAL_POSITION , (db_config[database], table_name)) for row in cursor.fetchall(): f.write(f| {row[0]} | {row[1]} | {row[2]} | {row[3]} | {row[4]} |\n) f.write(\n) cursor.close() conn.close()这样生成出来的 Markdown 可以直接丢到 Git 仓库里跟着代码一起走版本。我甚至见过有人直接把它挂在 Confluence 的宏里定时拉取展示效果不比商业工具差。3.3 PostgreSQL 的差异点Postgres 用户要注意information_schema虽然也有但注释信息存储在obj_description()和col_description()函数里不是直接的COMMENT字段SELECT c.relname AS table_name, a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS data_type, col_description(a.attrelid, a.attnum) AS comment FROM pg_class c JOIN pg_namespace n ON n.oid c.relnamespace JOIN pg_attribute a ON a.attrelid c.oid WHERE c.relkind r AND n.nspname public AND a.attnum 0 AND NOT a.attisdropped ORDER BY c.relname, a.attnum;核心逻辑不变查元数据 - 拼 Markdown - 进版本库。这套“手艺”才是真正的通用方案。4. 构建自动化同步链路让字典不再过期4.1 字典过期的真正原因工具选得再好、SQL 写得再漂亮如果字典是手动生成的三个月后必然过期。这是人性问题开发改表结构的时候绝不会想着“去更新一下字典文档”。所以唯一的出路是把字典生成嵌到自动化流水线里让它每次构建都重新生成像编译代码一样“不新鲜就报错”。4.2 方案 AMaven 插件Java 项目的首选用 screw 的 Maven 插件可以做到mvn clean package的时候自动重新生成数据库文档。配置核心就三块数据源连接信息、输出目录、文档格式。plugin groupIdcn.smallbun.screw/groupId artifactIdscrew-maven-plugin/artifactId version1.0.7/version configuration driverClassNamecom.mysql.cj.jdbc.Driver/driverClassName urljdbc:mysql://localhost:3306/your_db/url usernameroot/username passwordyour_password/password fileTypeHTML/fileType fileOutputDir${project.build.directory}/docs/fileOutputDir /configuration executions execution phaseverify/phase goals goalrun/goal /goals /execution /executions /plugin然后构建产物target/docs下的 HTML 就是最新版字典可以直接挂在构建服务器的 Artifact 里也可以发到内部的文档站。这样做的好处是每次发版字典一定和代码是同一个时点的快照。4.3 方案 BGitLab CI / GitHub Actions 定时刷新非 Java 项目或不想在构建里加重量级依赖就用定时任务。把上一节的 Python 脚本提交到仓库然后在 CI 配置里加一个定时 job比如每天夜里跑一次# .gitlab-ci.yml 片段 generate-dict: stage: deploy script: - pip install pymysql markdown - python scripts/gen_dict.py --config configs/db.json --output public/dict.md - # 这里调用内部文件服务 API 把 dict.md 传到在线文档平台 only: - schedules跑出来的结果直接发布到内部站点所有人打开链接看到的就是“昨天夜里自动更新”的最新字典。我实际用下来觉得这种“哑巴式”的执行特别稳定不依赖任何人的自觉性。4.4 流程上的“强制手段”自动化只能兜底真正要根治老化问题还得在开发规范上做文章。我们团队当时定了一条硬性规矩所有新增字段或新表必须带 COMMENT否则 Code Review 不通过。规矩很土但效果极好。另外强烈建议把“维护数据字典”写进新员工的入职文档里新人看到的第一份项目资料就是自动生成的字典链接而不是让他在代码里逐行猜。当字典成为所有人默认的知识入口时它自然会被用心维护。5. 这几个坑我替你们踩过了5.1 枚举字段不写取值含义字典等于半成品我见过最多的“假字典”是COLUMN_COMMENT里写着“状态”然后没了。你查完系统表导出的文档根本不知道 1 是启用还是禁用。解决思路有两种。如果字段用的是 MySQL 的ENUM类型注释里可以直接列出来更多场景是TINYINT加业务码这时要约定一种注释格式比如status tinyint(1) NOT NULL DEFAULT 0 COMMENT 用户状态0-正常1-禁用2-注销如果嫌注释太长可以建一张独立的“枚举字典表”专门记录业务枚举值和含义。这属于架构层面的事了但字典工具设计时一定要给枚举含义留位置——screw 输出的文档里其实就是数据库注释原文所以规则要前置约定好。5.2 MySQL 8 注释长度和字符集问题MySQL 8.0 之前字段注释最大只能存 255 个字符8.0 以后放宽到 1024但依然有上限。如果团队在表结构里写特别长的说明比如把整个业务规则写进去截断得很“优雅”你甚至不会发现。另外生成文档时如果连接串没指定characterEncodingutf8或者数据库排序规则不是 utf8mb4中文注释和 emoji 极容易乱码。我的经验是连接串统一写成jdbc:mysql://localhost:3306/db?useUnicodetruecharacterEncodingutf8mb4useSSLfalse别小看这个我见过一份 Word 版数据字典里二十张表的注释全是问号白做了。5.3 自动化后没人看也白搭字典生成得再漂亮如果没人访问、没人引用就是个死文档。后来我把字典链接挂在了项目 README 首页和 CI 流水线的 MR 描述模板里每次提 Merge RequestMR 描述自动带上“本次变更涉及的表xxx最新字典见xxx”。数据字典这才真正“活”起来。5.4 别在字典里写太细节的业务逻辑最后说个方向上的事。数据字典适合承载“字段是什么”不适合承载“字段怎么算”。比如total_amount是“订单总额”这个可以写在注释里但“订单总额 商品金额 运费 - 优惠券分摊”这种计算逻辑写进字典维护起来非常痛苦。那是接口文档和需求文档该管的事。工具能解决的是“一致性”问题解决不了“逻辑分层”问题这个边界要想清楚。本文还有配套的精品资源点击获取
简介数据字典工具是一款面向数据库管理员与开发人员的自动化文档生成软件。它能够自动扫描数据库中的表、视图、存储过程等对象提取字段名、数据类型、默认值、可空约束及开发注释并按用户要求生成结构清晰的数据库字典文档帮助团队快速理解数据库架构减少手工编写维护文档的工作量。压缩包内共包含十六个文件大小约二点五八兆字节核心是一个可直接运行的可执行文件附带动态链接库、Word与HTML文档模板、文本说明以及用于界面演示的示例图片结构完整下载后即可试用。目前已有五百二十八人学习使用既适合刚接触数据库设计的初学者也适合需要为现有系统快速补全数据字典的中小型项目团队。通过该工具用户不仅能自动生成包含字段注释和关系的文档还能根据提供的模板自定义输出样式直接用于项目交付、评审或团队协作提升数据库管理与交接效率。 接手过一个跑了五六年的老系统数据库里两百多张表前任离职交接时只留下一句“都在库里自己看”。我连着一个星期每天对着 Navicat 翻字段见着status就猜是 0 还是 1见着remark就祈祷注释别是空的。一个月后我终于忍不了了必须把“数据字典工具”这件事系统性解决掉不然以后每个接手的兄弟都得再遭一遍罪。这篇文章不是给你推荐某一个软件完事而是把我从“查系统表拼文档”到“流水线自动生成字典”的全过程、工具选型思路、以及踩过的坑都整理出来。适合刚接手老项目的一线开发、团队里负责数据库规范的人还有那些嘴上说“要有文档”、实际上连注释都不写的项目管理者看。1. 先搞清楚数据字典到底在解决什么痛点1.1 没有字典的团队有多痛很多人以为数据字典就是个“数据库表结构说明书”这理解没错但太浅了。真正的痛点不在于“没有文档”而在于信息在传递过程中层层失真业务方说“我们要看用户状态”开发知道user.status字段 0 是正常、1 是禁用、2 是注销但报表组的人不知道新来的同事不知道三个月后的你自己也不知道。我见过最魔幻的一次DBA 给线上表加了个is_deleted字段默认 0。结果运营那边导数据看到 0 就以为是“已删除”把正常用户全过滤掉了。事后复盘谁都没错错的是这个字段的含义只存在于开发脑子里而数据字典是空的。这种成本远比“写注释多花五分钟”要高得多。1.2 数据字典的三种常见形态按我接触过的项目数据字典有这三种落地形态数据库注释型直接在COMMENT里写字段说明。这是最基础、最不会丢的形态任何可视化工具都能看到。缺点是表达力有限枚举值含义、关联关系写不详细。独立文档型用 Word、Markdown、Confluence 或专门的工具生成独立的表结构文档。信息丰富、可分享但极容易过期——改表的人大概率不会同步去改文档。在线协作平台型像 dbdocs、Bytebase 这类把字典当成一个可以多人编辑、版本管理的“产品”来做字典和表结构之间可以对比 Diff。这三者不是互斥的靠谱的做法是“注释兜底 文档对外 平台协作”后面我会展开讲怎么搭。1.3 一份好字典应该长什么样根据我的经验一份能真正顶用的数据字典至少要包含四层信息表级信息表名、业务含义、负责人、所属模块。字段级信息字段名、类型、长度、是否可空、默认值、字段注释。枚举值说明status的 0/1/2 分别代表什么这是最容易被忽略、又最致命的部分。关联关系这张表和哪些表有外键/逻辑关联order.user_id对应user.id业务分析时才能顺着脉络走。只做到第 1、2 层那叫“会导出数据库注释”做到 3、4 层才叫真正的“数据字典”。2. 主流数据字典工具选型别只盯着“能导出”工具这东西没有最好的只有跟团队现状最匹配的。我把市面上常见的路子分成四类每个都有自己的适用场景。2.1 数据库自带能力系统表与注释所有主流数据库都提供了对元数据的访问接口。MySQL 有information_schemaPostgreSQL 有pg_catalogOracle 有ALL_TAB_COLUMNS连 SQLite 都有PRAGMA table_info()。这类“工具”的优点是零依赖、永远跟数据库同步缺点是只能拿到结构信息拿不到业务信息。说白了你得先有个好的注释习惯否则查出来一堆英文裸字段。2.2 桌面客户端一键导出快但只解决一半问题Navicat、DataGrip、DBeaver 这些客户端基本都带“导出数据库结构”的功能。Navicat 里选中库右键“转储 SQL 文件”或者用“模型”功能就能看到 ER 图和字段列表DataGrip 甚至能把表结构导出成 Markdown 格式。这类方案适合临时救急客户现场要交付文档、领导突然要一份表清单五分钟导出来能交差。但它最大的问题是下一次表结构变了这份文档就废了。它没有“重新生成”的自动化闭环所以我不建议把它当长期方案只能当“快速出活”的手段。2.3 开源工具 screwJava 生态的文档生成利器如果你团队的技术栈是 Java那 screwgithub 上搜 smallbun/screw值得认真对待。它是一个专门生成数据库文档的开源工具支持 HTML、Word、Markdown 三种格式。我为什么喜欢它因为它解决了一个特别恶心的点它读取的是数据库里的 COMMENT只要平时写注释它就能生成一份结构完整的文档不需要额外维护一份“文档里的表结构”。用法也很简单Spring Boot 项目里引入依赖配一下数据源一个命令跑完dependency groupIdcn.smallbun.screw/groupId artifactIdscrew-core/artifactId version1.0.7/version /dependency然后写个测试类或者用它的 Maven 插件指定输出路径和格式直接生成。它会把表注释、字段注释、索引、主键全部带出来长得很接近那种“商业级交付文档”的质感。2.4 在线协作平台适合多人维护的团队如果团队超过十个人、业务线多、字典需要业务方也参与维护那就要考虑在线协作工具了。dbdocs 这类产品可以把数据库连接以后自动拉取 Schema 生成在线文档也可以在界面上手动补充描述还支持版本历史。国内团队如果在意数据安全可以用 Bytebase 或自建的类似系统。这类平台的核心价值在于字典不再是某个人的文本文件而是一个“活”的、有权限管理的资产。代价是需要服务器、需要维护、需要有人推进落地对两三个人的小团队来说可能过重。2.5 我的选型建议团队场景推荐方案理由临时交付/个人使用Navicat/DataGrip 导出五分钟拿到现成文档中小型 Java 项目screw 嵌入 Maven 插件低成本、可自动化多语言/微服务团队Python 脚本连系统表发布到内部 Wiki语言无关、可自定义大规模业务协作dbdocs/Bytebase 类在线平台权限管理、版本控制、多方维护3. 用 SQL 从数据库系统表生成 Markdown 字典零依赖方案如果你不想引入任何第三方工具也不想被某一种语言绑死那我强烈建议你学会一种“万能手艺”直接查系统表自己把结果拼成 Markdown。这个方案能在任何环境、任何语言下落地。3.1 MySQL核心查询长这样以 MySQL 为例表级信息在information_schema.TABLES字段信息在information_schema.COLUMNS-- 表级信息 SELECT TABLE_NAME AS 表名, TABLE_COMMENT AS 表注释 FROM information_schema.TABLES WHERE TABLE_SCHEMA your_database_name; -- 字段级信息 SELECT TABLE_NAME AS 表名, COLUMN_NAME AS 字段名, COLUMN_TYPE AS 字段类型, IS_NULLABLE AS 是否为空, COLUMN_DEFAULT AS 默认值, COLUMN_COMMENT AS 字段注释 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your_database_name;这个查询结果拿到之后用任何脚本语言都能转成 Markdown 表格。关键在于思路先按表名分组每张表生成一个### 表名注释的二级块再把该表的字段矩阵输出成表格。3.2 写个小脚本自动搞定我用 Python 写过一版核心逻辑大概长这样你可以直接参考import pymysql import markdown def generate_dict(db_config, output_file): conn pymysql.connect(**db_config) cursor conn.cursor() # 查表 cursor.execute( SELECT TABLE_NAME, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA %s ORDER BY TABLE_NAME , (db_config[database],)) tables cursor.fetchall() with open(output_file, w, encodingutf-8) as f: for table_name, table_comment in tables: f.write(f### {table_name}{table_comment}\n\n) f.write(| 字段名 | 类型 | 可空 | 默认值 | 注释 |\n) f.write(| --- | --- | --- | --- | --- |\n) cursor.execute( SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA %s AND TABLE_NAME %s ORDER BY ORDINAL_POSITION , (db_config[database], table_name)) for row in cursor.fetchall(): f.write(f| {row[0]} | {row[1]} | {row[2]} | {row[3]} | {row[4]} |\n) f.write(\n) cursor.close() conn.close()这样生成出来的 Markdown 可以直接丢到 Git 仓库里跟着代码一起走版本。我甚至见过有人直接把它挂在 Confluence 的宏里定时拉取展示效果不比商业工具差。3.3 PostgreSQL 的差异点Postgres 用户要注意information_schema虽然也有但注释信息存储在obj_description()和col_description()函数里不是直接的COMMENT字段SELECT c.relname AS table_name, a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS data_type, col_description(a.attrelid, a.attnum) AS comment FROM pg_class c JOIN pg_namespace n ON n.oid c.relnamespace JOIN pg_attribute a ON a.attrelid c.oid WHERE c.relkind r AND n.nspname public AND a.attnum 0 AND NOT a.attisdropped ORDER BY c.relname, a.attnum;核心逻辑不变查元数据 - 拼 Markdown - 进版本库。这套“手艺”才是真正的通用方案。4. 构建自动化同步链路让字典不再过期4.1 字典过期的真正原因工具选得再好、SQL 写得再漂亮如果字典是手动生成的三个月后必然过期。这是人性问题开发改表结构的时候绝不会想着“去更新一下字典文档”。所以唯一的出路是把字典生成嵌到自动化流水线里让它每次构建都重新生成像编译代码一样“不新鲜就报错”。4.2 方案 AMaven 插件Java 项目的首选用 screw 的 Maven 插件可以做到mvn clean package的时候自动重新生成数据库文档。配置核心就三块数据源连接信息、输出目录、文档格式。plugin groupIdcn.smallbun.screw/groupId artifactIdscrew-maven-plugin/artifactId version1.0.7/version configuration driverClassNamecom.mysql.cj.jdbc.Driver/driverClassName urljdbc:mysql://localhost:3306/your_db/url usernameroot/username passwordyour_password/password fileTypeHTML/fileType fileOutputDir${project.build.directory}/docs/fileOutputDir /configuration executions execution phaseverify/phase goals goalrun/goal /goals /execution /executions /plugin然后构建产物target/docs下的 HTML 就是最新版字典可以直接挂在构建服务器的 Artifact 里也可以发到内部的文档站。这样做的好处是每次发版字典一定和代码是同一个时点的快照。4.3 方案 BGitLab CI / GitHub Actions 定时刷新非 Java 项目或不想在构建里加重量级依赖就用定时任务。把上一节的 Python 脚本提交到仓库然后在 CI 配置里加一个定时 job比如每天夜里跑一次# .gitlab-ci.yml 片段 generate-dict: stage: deploy script: - pip install pymysql markdown - python scripts/gen_dict.py --config configs/db.json --output public/dict.md - # 这里调用内部文件服务 API 把 dict.md 传到在线文档平台 only: - schedules跑出来的结果直接发布到内部站点所有人打开链接看到的就是“昨天夜里自动更新”的最新字典。我实际用下来觉得这种“哑巴式”的执行特别稳定不依赖任何人的自觉性。4.4 流程上的“强制手段”自动化只能兜底真正要根治老化问题还得在开发规范上做文章。我们团队当时定了一条硬性规矩所有新增字段或新表必须带 COMMENT否则 Code Review 不通过。规矩很土但效果极好。另外强烈建议把“维护数据字典”写进新员工的入职文档里新人看到的第一份项目资料就是自动生成的字典链接而不是让他在代码里逐行猜。当字典成为所有人默认的知识入口时它自然会被用心维护。5. 这几个坑我替你们踩过了5.1 枚举字段不写取值含义字典等于半成品我见过最多的“假字典”是COLUMN_COMMENT里写着“状态”然后没了。你查完系统表导出的文档根本不知道 1 是启用还是禁用。解决思路有两种。如果字段用的是 MySQL 的ENUM类型注释里可以直接列出来更多场景是TINYINT加业务码这时要约定一种注释格式比如status tinyint(1) NOT NULL DEFAULT 0 COMMENT 用户状态0-正常1-禁用2-注销如果嫌注释太长可以建一张独立的“枚举字典表”专门记录业务枚举值和含义。这属于架构层面的事了但字典工具设计时一定要给枚举含义留位置——screw 输出的文档里其实就是数据库注释原文所以规则要前置约定好。5.2 MySQL 8 注释长度和字符集问题MySQL 8.0 之前字段注释最大只能存 255 个字符8.0 以后放宽到 1024但依然有上限。如果团队在表结构里写特别长的说明比如把整个业务规则写进去截断得很“优雅”你甚至不会发现。另外生成文档时如果连接串没指定characterEncodingutf8或者数据库排序规则不是 utf8mb4中文注释和 emoji 极容易乱码。我的经验是连接串统一写成jdbc:mysql://localhost:3306/db?useUnicodetruecharacterEncodingutf8mb4useSSLfalse别小看这个我见过一份 Word 版数据字典里二十张表的注释全是问号白做了。5.3 自动化后没人看也白搭字典生成得再漂亮如果没人访问、没人引用就是个死文档。后来我把字典链接挂在了项目 README 首页和 CI 流水线的 MR 描述模板里每次提 Merge RequestMR 描述自动带上“本次变更涉及的表xxx最新字典见xxx”。数据字典这才真正“活”起来。5.4 别在字典里写太细节的业务逻辑最后说个方向上的事。数据字典适合承载“字段是什么”不适合承载“字段怎么算”。比如total_amount是“订单总额”这个可以写在注释里但“订单总额 商品金额 运费 - 优惠券分摊”这种计算逻辑写进字典维护起来非常痛苦。那是接口文档和需求文档该管的事。工具能解决的是“一致性”问题解决不了“逻辑分层”问题这个边界要想清楚。本文还有配套的精品资源点击获取
