简介：数据字典工具面向数据库开发、运维与设计人员，用于自动化生成数据库结构文档，解决手动整理表结构、字段说明与注释耗时且易出错的问题。工具可扫描表、视图、存储过程等对象，提取字段类型、长度、默认值及注释信息，并支持关系图展示与HTML、Word等格式导出，适合中小型项目快速产出规范文档。压缩包共16个文件，约2.58MB，以exe主程序、dll运行库、xml配置与docx说明文档为主，辅以html、css、js等模板资源及少量图片素材，整体轻量、解压即用。目前已有531人学习下载。借助该工具，读者可省去逐表手工编写文档的环节，获得结构清晰、注释完整的数据库说明材料，并可通过模板调整输出样式，便于团队共享与后期维护查阅。

1. 数据字典工具：从建表脚本到可交付文档的那一步

接手一个跑了三年的业务库，最怕的不是 SQL 慢，而是没人说得清order_ext里那二十几个字段到底哪个还在用。数据字典工具解决的正是这个断层：把库里的表、字段、类型、注释、索引、外键这些元数据抽出来，整理成一份人能读、机器也能继续处理的文档。它适合三类人——要交付数据库设计文档的开发者、接手遗留系统的维护者、以及需要把表结构同步给前端和测试的团队。这类工具的核心价值不在“生成”，而在“可重复生成”：改完表结构重跑一遍，文档跟着变，而不是靠人肉维护一份永远过期的 Word。下面按我实际拆解和复用的顺序，把选型、抽取、导出、踩坑一条线讲透。

2. 元数据从哪来：三种抽取路径的取舍

数据字典工具的第一道分水岭是元数据来源。选错了路径，后面全是补丁。常见做法有三条：直连数据库读系统表、解析 DDL 建表脚本、走 ORM 模型反射。三条路各有边界，我一般按“库是否可连”和“注释是否完整”两个维度来定。

2.1 直连数据库读 information_schema

这是最稳的一条路，前提是能拿到只读账号。MySQL 系的information_schema.COLUMNS、TABLES、STATISTICS三张表基本能覆盖字段名、类型、是否可空、默认值、注释、索引。PostgreSQL 则走pg_catalog下的pg_class、pg_attribute、pg_description。关键点是：注释字段是数据字典的灵魂，没有注释的字典等于一张字段名清单。

-- MySQL：一次性拉出某库所有表的字段元数据 SELECT t.TABLE_NAME AS 表名, t.TABLE_COMMENT AS 表注释, c.COLUMN_NAME AS 字段名, c.COLUMN_TYPE AS 字段类型, c.IS_NULLABLE AS 是否可空, c.COLUMN_DEFAULT AS 默认值, c.COLUMN_COMMENT AS 字段注释, c.ORDINAL_POSITION AS 序号 FROM information_schema.TABLES t JOIN information_schema.COLUMNS c ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME WHERE t.TABLE_SCHEMA = 'your_db' -- 换成目标库名 AND t.TABLE_TYPE = 'BASE TABLE' -- 排除视图，视图单独处理 ORDER BY t.TABLE_NAME, c.ORDINAL_POSITION;

这段 SQL 的逻辑是先用TABLES拿表级注释，再JOIN COLUMNS拿字段级信息，TABLE_TYPE过滤掉视图避免混入。参数上唯一要改的是your_db；如果库里有分表（比如order_202401这种），建议加AND t.TABLE_NAME NOT REGEXP '_[0-9]{6}$'把按月分表排除，否则字典会被几百张同构表撑爆。索引信息要另查STATISTICS，按INDEX_NAME聚合，别和字段查询混在一条 SQL 里，否则行数会翻倍。

2.2 解析 DDL 脚本：没有库连接时的退路

有些场景拿不到库连接——交付物只有一份schema.sql，或者库在客户内网。这时只能解析 DDL。正则解析CREATE TABLE是可行的，但要有心理准备：注释语法、反引号、COMMENT ON COLUMN（PG 风格）都得单独处理。我一般用 Python 的sqlparse先做语句切分，再对每条CREATE TABLE做字段行提取。

import re import sqlparse def parse_ddl(ddl_text): result = {} # 按分号切分，只保留 CREATE TABLE 语句 for stmt in sqlparse.split(ddl_text): stmt = stmt.strip() if not stmt.upper().startswith("CREATE TABLE"): continue # 抓表名与表注释 m = re.search(r"CREATE TABLE\s+`?(\w+)`?", stmt, re.I) if not m: continue table = m.group(1) fields = [] # 逐行匹配字段定义：字段名 类型 ... COMMENT 'xxx' for line in stmt.splitlines(): fm = re.match( r"\s*`?(\w+)`?\s+([\w()]+).*?COMMENT\s+'([^']*)'", line, re.I ) if fm: fields.append({ "name": fm.group(1), "type": fm.group(2), "comment": fm.group(3), }) result[table] = fields return result

逻辑说明：sqlparse.split负责把多语句文件切开，避免跨表误匹配；字段正则里COMMENT\s+'([^']*)'是硬约束，没有注释的字段会被漏掉——这是刻意的，因为无注释字段进字典意义不大，但要在日志里打出来提醒补注释。参数上[\w()]+覆盖varchar(64)、decimal(10,2)这类带括号类型，遇到enum('a','b')这种带引号的类型会截断，需要把类型正则放宽成[^,\s]+。这条路的天花板是：DDL 里没写注释，解析出来就是空的，工具救不了。

2.3 ORM 反射：模型即字典的适用边界

如果项目本身用 ORM（SQLAlchemy、Django ORM、MyBatis-Plus 之类），模型定义里往往已经带了字段说明。走反射的好处是不用连库也能拿到结构，坏处是模型和真实库可能已经漂移——有人手动改过库没同步模型，字典就会骗人。我的判断标准很简单：模型是唯一事实来源的项目才走反射，否则老老实实连库。Django 可以用apps.get_models()遍历_meta.fields，SQLAlchemy 用inspect(engine).get_columns()，拿到的comment属性直接映射到字典字段。

三条路径的取舍可以压成一张表：

3. 把元数据变成文档：导出格式与字段映射

抽到元数据只是半成品，真正交付的是文档。这一步的核心是字段映射：库里的COLUMN_NAME要变成人读的“字段名”，COLUMN_COMMENT变成“说明”，还要补上“业务含义”“枚举值”这类库里没有的列。工具的价值在于把“能自动填的自动填，填不了的留空等人补”，而不是硬凑一份全自动文档。

3.1 Markdown 与 Excel 双格式导出

Markdown 适合进 Git 仓库随代码走，Excel 适合给不碰代码的同事。两种格式共用同一份中间数据结构，导出层只做渲染。下面是一个最小可用的 Markdown 渲染函数：

def render_markdown(dict_data, db_name): lines = [f"# {db_name} 数据字典\n"] for table, info in dict_data.items(): lines.append(f"## {table} {info.get('comment', '')}\n") lines.append("| 字段名 | 类型 | 可空 | 默认值 | 说明 |") lines.append("|--------|------|------|--------|------|") for f in info["fields"]: lines.append( f"| {f['name']} | {f['type']} | {f['nullable']} " f"| {f['default'] or ''} | {f['comment']} |" ) lines.append("") return "\n".join(lines)

逻辑上就是遍历表、遍历字段拼表格行。参数说明：info.get('comment', '')用默认空串兜底，避免表注释缺失时渲染出None；f['default'] or ''处理默认值为NULL的情况，否则表格里会出现字面量None。Excel 导出用openpyxl，一个 sheet 一张表或一张大表都行，我倾向一张大表加“表名”列，方便筛选。注意 Excel 单元格有 32767 字符上限，字段说明特别长的（比如存了 JSON 示例）要截断或另起 sheet。

3.2 字段映射表：库里没有的那几列怎么补

自动抽取只能填“字段名/类型/可空/默认值/注释”五列，但一份能交付的字典通常还要“业务含义”“枚举值”“是否敏感”“负责人”。这几列库里没有，硬编码进工具又太死。我的做法是维护一张外部映射表（CSV 或 YAML），以表名.字段名为键，导出时做左连接合并。

# field_meta.yaml —— 人工补充的字段语义 order.ext_status: business: 订单扩展状态 enum: "0=待审,1=通过,2=驳回" sensitive: false user.id_card: business: 身份证号 enum: "" sensitive: true

合并逻辑放在渲染前：读 YAML 成字典，遍历元数据时用f"{table}.{field}"去查，命中就覆盖或追加列。这样工具本身保持通用，业务语义留在配置里，换项目只换 YAML。参数上要注意键的大小写——MySQL 在 Linux 下表名默认区分大小写，映射表的键要和information_schema返回的完全一致，否则静默不命中，这是很隐蔽的坑。

3.3 增量对比：让字典能看出“这周改了什么”

字典一旦进了 Git，就该有 diff。工具可以顺带做一件事：把本次抽取结果和上次的 JSON 快照对比，输出新增表、删除表、新增字段、类型变更、注释变更五类差异。实现上就是两次dict的键集合运算加字段级比对，不需要复杂框架。

def diff_dict(old, new): changes = [] for table in new.keys() - old.keys(): changes.append(("新增表", table, "")) for table in old.keys() - new.keys(): changes.append(("删除表", table, "")) for table in old.keys() & new.keys(): old_f = {f["name"]: f for f in old[table]["fields"]} new_f = {f["name"]: f for f in new[table]["fields"]} for name in new_f.keys() - old_f.keys(): changes.append(("新增字段", f"{table}.{name}", "")) for name in old_f.keys() & new_f.keys(): if old_f[name]["type"] != new_f[name]["type"]: changes.append( ("类型变更", f"{table}.{name}", f"{old_f[name]['type']} -> {new_f[name]['type']}") ) return changes

这段只对比了类型，注释和可空性同理加分支即可。差异结果可以直接拼进 Markdown 的“变更记录”章节，也可以单独输出一份CHANGELOG.md。血泪经验是：快照文件一定要带时间戳命名并进版本库，否则下次对比找不到基线，这个功能就废了。

4. 避坑与排查：五个真实翻车点

工具跑通不难，难的是跑出来的东西可信。下面五条是我在不同项目里实际踩过的，按“现象 → 原因 → 解决”记下来。

4.1 字典里字段顺序和建表顺序对不上

现象：导出的字段顺序乱跳，和DESC table看到的顺序不一致。原因：查询information_schema.COLUMNS时没加ORDER BY ORDINAL_POSITION，数据库不保证返回顺序。解决：字段查询必须显式按ORDINAL_POSITION排序，且排序要在JOIN之后做，否则多表关联时序号会串。这个坑在 MySQL 5.7 上尤其常见，8.0 之后虽然多数情况有序，但不能依赖。

4.2 注释全是空的，字典变成字段名清单

现象：抽出来的“说明”列整列空白。原因：建表时没写COMMENT，或者注释写在应用层枚举里没落到库。解决：工具层面加一个“无注释字段清单”输出，按表聚合，交付前逼着补一轮；补不了的，用 3.2 的映射表兜底。别指望工具能猜出status是啥意思，猜出来的字典比没有更危险。

4.3 分表把字典撑到几千行

现象：一张逻辑表被拆成几十张物理表，字典里全是xxx_202401到xxx_202412。原因：按月/按用户分表，元数据里每张都是独立表。解决：抽取时用正则排除分表后缀，或者在渲染层做“逻辑表合并”，把同构分表折叠成一张并标注“分表规则”。参数上排除正则要写窄，_[0-9]{6}$只匹配六位数字后缀，别误伤正常表名。

4.4 敏感字段被原样写进文档

现象：字典里出现了身份证、手机号字段的示例值或默认值。原因：默认值列直接渲染，或者映射表里填了真实样例。解决：在映射表里给字段打sensitive: true，渲染时把默认值和示例列替换成***；同时工具启动时扫一遍字段名关键词（id_card、phone、password、token），命中就强制脱敏。这条不是技术问题，是交付纪律问题，但工具得帮着兜住。

4.5 换了个库，工具直接报编码错误

现象：连 PostgreSQL 或某个字符集特殊的库时，中文注释变乱码或抛UnicodeDecodeError。原因：连接串没指定字符集，或者驱动默认编码和库不一致。解决：MySQL 连接加?useUnicode=true&characterEncoding=utf8mb4，PG 在psycopg2里设client_encoding='UTF8'；导出文件统一用encoding='utf-8-sig'写，Excel 打开中文才不乱码。这个坑排查起来最费时间，因为报错点往往在渲染层而不是连接层。

5. 进阶：把字典接进 CI，让文档不再过期

工具跑通之后，真正决定它有没有长期价值的，是它能不能自动跑。我的习惯是把字典生成挂到 CI 的定时任务或合并请求钩子上：每天凌晨抽一次，和上次快照 diff，有变更就提交一个docs/dict/下的更新，没有变更就静默。这样字典永远跟着库走，而不是跟着人的记性走。

具体做法分三步。第一步，把抽取脚本包成一个 CLI，参数化库连接和输出目录：

# 生成字典并输出差异，退出码非 0 表示有结构变更 python dict_tool.py \ --dsn "mysql://reader:pass@host:3306/your_db" \ --out docs/dict/ \ --snapshot docs/dict/.snapshot.json \ --diff-exit-code

--dsn走只读账号，--out是文档输出目录，--snapshot是上次快照路径，--diff-exit-code让脚本在有变更时返回非 0，方便 CI 判断要不要提交。第二步，CI 里加一个 job，只在主分支定时触发，跑完git diff --quiet判断有无变化，有就git commit并推送。第三步，给字典目录加一个README说明“此目录由工具生成，勿手改”，避免有人手动编辑后被下次生成覆盖，白忙一场。

验证方法也简单：故意在测试库加一个字段、改一个注释，重跑工具，看 diff 是否准确报出“新增字段”和“注释变更”，再看 Markdown 里对应行是否更新。如果 diff 报了但文档没变，八成是渲染层用了旧快照；如果文档变了但 diff 没报，检查快照写入时机是不是在渲染之前。这两个方向能覆盖大部分集成问题。

还有一个容易被忽略的细节：字典里的“枚举值”最好和代码里的常量做交叉校验。比如order.status在库里注释写0=待审,1=通过，但代码枚举里多了个2=已取消，说明库注释过期了。工具可以做一次简单比对——把映射表里的enum和代码里导出的常量 JSON 对一遍，不一致就告警。这一步不是必须，但在字段语义靠注释维系的项目里，能提前发现不少“文档说一套、代码跑一套”的玄学问题。

从那以后我每次接新库，第一件事不是写查询，而是先把字典工具跑一遍、把无注释字段清单拉出来，逼着自己在动手前把表结构看明白。这份清单比任何设计文档都诚实。希望帮到你。

本文还有配套的精品资源，点击获取