简介数据字典工具是一套面向数据库开发者与DBA的自动化文档生成软件用于解决手动整理表结构、字段说明耗时且易出错的问题适合需要快速梳理数据库架构、输出规范文档的中初级技术人员。压缩包共16个文件约2.58MB以exe主程序与dll运行库为核心辅以html、css、js等模板资源及docx说明文档另含gif、jpg操作示意图开箱即可运行。资源支持自动扫描表、视图、存储过程等对象提取字段类型、长度、默认值与注释并可导出Word、HTML等格式部分场景下还能呈现外键关系。目前已有531人学习下载可作为理解数据库字典概念、快速产出结构文档的实用参考。1. 数据字典工具从建表 SQL 到可交付文档中间差了什么接手一个跑了三年的业务库最怕的不是表多而是没人说得清order_ext_03这个字段到底存的是渠道编码还是门店编号。数据字典工具解决的正是这件事把数据库里的表、字段、类型、注释、索引、外键这些元数据抽出来整理成一份人能看懂、能交付、能随版本更新的文档。它适合三类人——需要给甲方交付数据库设计说明的开发者、接手遗留系统要快速摸清结构的维护人员、以及做数据治理前需要先盘清家底的从业者。这类工具的核心价值不在“生成”而在“可重复生成”建表语句一改字典能跟着重跑而不是靠人工在 Word 里逐条誊抄。下面按我实际拆解和复现的顺序把选型、抽取、导出、排错这条链路走一遍。2. 元数据从哪来三种抽取路径的取舍数据字典工具的第一道分水岭是元数据从哪里读。常见做法有三条读information_schema这类系统视图、解析建表 DDL 脚本、连库后逐表查询。三条路各有边界选错了后面全是返工。2.1 系统视图抽取最稳的默认路径绝大多数关系型数据库都维护着描述自身结构的系统表。以 MySQL 为例information_schema.TABLES存表级信息COLUMNS存字段级信息STATISTICS存索引KEY_COLUMN_USAGE存约束。这条路的好处是元数据由数据库自己维护不会因为脚本和实际库不一致而失真。-- 抽取某库全部表与字段的基础元数据 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_SCHEMA必须写实际库名写错就是空结果TABLE_TYPE过滤掉视图能避免字典里混进视图定义但如果你的交付要求包含视图把这行去掉即可。ORDINAL_POSITION别省它是后面还原字段顺序的唯一依据。索引和外键要单独抽因为它们是多对多关系直接和字段表 JOIN 会产生笛卡尔积膨胀。索引走STATISTICS按INDEX_NAME分组外键走KEY_COLUMN_USAGE里REFERENCED_TABLE_NAME IS NOT NULL的记录。我一般把这两块抽成独立查询在应用层按表名合并而不是硬塞进一条大 SQL。2.2 DDL 脚本解析适合没有库连接权限的场景有些环境拿不到数据库连接只给了一份schema.sql。这时只能解析建表语句。正则能应付简单场景但遇到带反引号、带COMMENT、带联合索引的 DDL 就容易翻车。稳妥做法是用现成的 SQL 解析库比如 Python 的sqlparse做粗切分再针对CREATE TABLE块做结构化提取。import re def parse_create_table(ddl_text): 从 DDL 文本中粗提表名、字段名、类型与注释 result [] # 按 CREATE TABLE 切块忽略 IF NOT EXISTS 的写法差异 blocks re.split(rCREATE\sTABLE, ddl_text, flagsre.IGNORECASE)[1:] for block in blocks: # 表名第一个反引号或裸标识符 name_match re.search(r[]?(\w)[]?\s*\(, block) if not name_match: continue table name_match.group(1) # 字段行以反引号开头、逗号结尾的片段 for line in block.splitlines(): col re.match(r\s*[](\w)[]\s([\w()]), line) if not col: continue comment re.search(rCOMMENT\s([^]*), line) result.append({ table: table, column: col.group(1), type: col.group(2), comment: comment.group(1) if comment else }) return result这段代码的定位是“够用就好”的粗解析不是完整 SQL 语法分析器。re.split按CREATE TABLE切块name_match抓表名字段行用re.match逐行匹配反引号包裹的列名和类型COMMENT单独用re.search抓引号内文本。参数上要注意如果你的 DDL 用双引号而非反引号把字符类改成[]类型里的(和)要保留在[\w()]里否则varchar(64)会被截成varchar。这条路的天生缺陷是拿不到运行时才有的信息比如自增当前值、实际行数交付文档里这类字段只能留空或标注“以线上为准”。2.3 连库逐表查询只在需要采样时用还有一种做法是连上库后对每张表执行SHOW FULL COLUMNS FROM xxx或DESC。它比系统视图多一层网络往返表多时明显慢但好处是能顺带拿到一些方言特有的信息。我的取舍是结构信息一律走系统视图只有需要补充“字段实际取值样例”时才逐表采样且采样必须加LIMIT绝不对大表做全表扫描。提示抽取阶段就把“结构元数据”和“数据样例”分开处理前者进字典正文后者单独存一份采样文件。混在一起会让字典体积失控也容易把敏感数据带进交付物。3. 把元数据变成文档模板、分组与导出抽到元数据只是原料真正决定字典好不好用的是组织方式。这一章讲怎么把扁平的字段列表变成有层级、可检索、能交付的文档。3.1 按业务域分组而不是按表名字母序直接按表名排序导出的字典读起来像电话簿。合格的做法是先定义分组规则把表归到业务域下。分组信息通常不在数据库里需要一份外部映射表比如一个 CSV表名、业务域、负责人、是否核心表。工具读取这份映射把没有归类的表统一放进“未分类”逼着使用者去补全而不是默默漏掉。import csv from collections import defaultdict def group_tables(meta_rows, mapping_file): 按外部映射把表分到业务域未命中的归入未分类 domain_map {} with open(mapping_file, encodingutf-8) as f: for row in csv.DictReader(f): domain_map[row[table]] row[domain] grouped defaultdict(lambda: defaultdict(list)) for r in meta_rows: domain domain_map.get(r[table], 未分类) grouped[domain][r[table]].append(r) return grouped逻辑很直白先读映射建domain_map再遍历元数据行用dict.get带默认值归组两层defaultdict保证“域 → 表 → 字段”的嵌套结构自动创建。参数上映射文件的表名必须和数据库里的大小写完全一致MySQL 在部分系统上表名大小写敏感这里对不上就会整表掉进“未分类”。我一般会在生成后统计“未分类”表的数量超过阈值就先停下来补映射而不是带着一堆未分类直接交付。3.2 模板渲染字段表、索引表、变更记录三件套一份能交付的字典每张表下面至少要有三块内容字段明细表、索引与外键表、变更记录。字段表列固定为字段名、类型、可空、默认值、注释索引表列索引名、字段组合、是否唯一变更记录则来自版本对比这块放到最后一章讲。渲染用模板引擎最省事Jinja2 或类似方案都行关键是模板里对空值要有兜底。from jinja2 import Template TABLE_TPL Template( ### {{ table }} {{ table_comment }} | 字段 | 类型 | 可空 | 默认值 | 注释 | |---|---|---|---|---| {% for c in columns -%} | {{ c.column }} | {{ c.type }} | {{ c.nullable }} | {{ c.default or - }} | {{ c.comment or 待补充 }} | {% endfor %} ) def render_table(table, columns, table_comment): return TABLE_TPL.render( tabletable, table_commenttable_comment or , columnscolumns )模板里c.default or -和c.comment or 待补充是两处关键兜底默认值为NULL时显示短横线注释为空时显示“待补充”这样交付物里不会出现大片空白让人误以为是导出失败。{% for %}后面的-}用来吃掉多余空行否则生成的 Markdown 表格行间会插空行导致渲染错乱。表注释为空时直接留空而不是写“无”是为了让后续检索“待补充”时能同时命中缺注释的字段和缺注释的表。3.3 导出格式Markdown 给协作Excel 给评审同一份元数据我一般导出两种格式。Markdown 进代码仓库跟着建表脚本一起做版本管理改动能进 diffExcel 给不碰代码的评审方方便他们批注。Excel 导出要注意两点字段注释里的换行符要替换成空格否则单元格会被撑开长文本列要设列宽上限不然打开就是一片超宽列。导出前统一做一次字符清洗把\r\n、\t规整掉这一步省了后面全是格式投诉。导出格式适用场景注意点Markdown进仓库、随版本 diff表格单元格内不能有裸竖线需转义Excel评审批注、非技术方阅读清洗换行符限制列宽HTML内网浏览、带搜索大库分页避免单页过重4. 避坑与排查五个真实翻车点工具跑通一次不难难的是每次都能跑通。下面这几条是我在不同库里反复踩到的按“现象 → 原因 → 解决”记下来。4.1 导出后字段顺序全乱现象字典里字段顺序和建表语句对不上id跑到中间去了。原因查询没带ORDER BY或者用了DISTINCT导致排序失效。解决字段查询必须显式ORDER BY TABLE_NAME, ORDINAL_POSITION渲染层不要再做二次排序否则两处排序规则不一致会互相覆盖。4.2 注释全是空的现象字段注释列整片空白但数据库里明明有注释。原因连的库不对或者账号权限只能看到部分元数据另一种常见情况是建表时注释写在COMMENT关键字后但用了双引号某些版本下不被识别。解决先用一条SHOW FULL COLUMNS手工确认注释是否存在确认存在再查抽取 SQL 的库名和账号权限最后才怀疑解析逻辑。4.3 大表把内存打爆现象表数量上千后导出进程被系统杀掉。原因一次性把所有元数据读进内存再渲染。解决改成按业务域分批查询、分批渲染、分批写文件最后再合并目录。分批的粒度按表数量控制单批两百张表左右比较稳具体看单表字段数。4.4 索引信息重复膨胀现象某张表的字段行数比实际字段多出好几倍。原因索引表和字段表直接 JOIN一个字段命中多个索引就复制多行。解决索引单独查询、单独渲染成索引表不要和字段明细放在同一条 SQL 里 JOIN。4.5 中文注释变乱码现象导出的 Excel 打开后注释是问号或方块。原因写文件时编码和打开方式不匹配常见于 CSV 直接双击打开。解决统一用 UTF-8 写文件CSV 场景加 BOM 头或者干脆导出 xlsx 而不是 csv从源头绕开编码问题。注意排错顺序建议固定为“先手工查库确认数据在不在 → 再查抽取 SQL → 最后查渲染和导出”。跳过第一步直接改代码十有八九是在修一个不存在的问题。5. 版本对比与增量更新让字典跟得上建表脚本字典最容易死的地方不是第一次生成而是第二次之后没人更新。真正让这份工具长期可用的是把它接进版本对比流程每次建表脚本变更自动跑一次抽取和上一版字典做 diff只把变化的部分标出来。5.1 用字段指纹做增量比对思路是给每个字段算一个指纹由表名、字段名、类型、可空、默认值、注释拼成任一变化指纹就变。比对时按“表名 字段名”做键分别找出新增、删除、修改三类。import hashlib def field_fingerprint(row): 把影响字典展示的字段属性拼成指纹 raw |.join([ row[table], row[column], row[type], str(row[nullable]), str(row[default]), row[comment] ]) return hashlib.md5(raw.encode(utf-8)).hexdigest() def diff_dict(old_rows, new_rows): old {(r[table], r[column]): field_fingerprint(r) for r in old_rows} new {(r[table], r[column]): field_fingerprint(r) for r in new_rows} added [k for k in new if k not in old] removed [k for k in old if k not in new] changed [k for k in new if k in old and new[k] ! old[k]] return added, removed, changed指纹里把nullable和default也str()进去是因为这两个值可能是None直接拼接会抛类型错误。md5在这里只做等值比较用不涉及安全场景换成任意稳定哈希都行。返回的三类结果直接对应变更记录的三个小节新增字段、删除字段、修改字段。修改类还可以进一步细分是类型变了还是注释变了做法是把指纹拆成多个子指纹分别比对按需加。5.2 变更记录写进字典正文diff 结果不要只打印到控制台要写进字典对应表的“变更记录”小节带上版本号和日期。这样评审方翻到某张表时能直接看到“这个字段上个月刚从varchar(32)扩到varchar(64)”而不是去翻提交历史。版本号建议和建表脚本的版本对齐别另起一套编号否则两套版本号对不上又是一笔糊涂账。5.3 一个我固定保留的习惯从那以后我每次交付字典前都强制走一遍“空库重跑”拿一份干净的测试库从建表脚本重建结构再跑一次抽取和渲染把结果和正式库的字典做 diff。两边一致才交付不一致说明正式库里有手工改过、没进脚本的结构这种“脚本外的漂移”恰恰是后续维护最大的雷。这一步多花十分钟能省掉后面无数次“文档和库对不上”的扯皮。希望这套流程能帮到你把字典从一次性产物变成能跟着库一起演进的东西。本文还有配套的精品资源点击获取 
长河君 · 2026/10/27 6:50:06 · 阅读 1.2k 数据字典工具实战：从元数据抽取到版本对比的完整链路
简介数据字典工具是一套面向数据库开发者与DBA的自动化文档生成软件用于解决手动整理表结构、字段说明耗时且易出错的问题适合需要快速梳理数据库架构、输出规范文档的中初级技术人员。压缩包共16个文件约2.58MB以exe主程序与dll运行库为核心辅以html、css、js等模板资源及docx说明文档另含gif、jpg操作示意图开箱即可运行。资源支持自动扫描表、视图、存储过程等对象提取字段类型、长度、默认值与注释并可导出Word、HTML等格式部分场景下还能呈现外键关系。目前已有531人学习下载可作为理解数据库字典概念、快速产出结构文档的实用参考。1. 数据字典工具从建表 SQL 到可交付文档中间差了什么接手一个跑了三年的业务库最怕的不是表多而是没人说得清order_ext_03这个字段到底存的是渠道编码还是门店编号。数据字典工具解决的正是这件事把数据库里的表、字段、类型、注释、索引、外键这些元数据抽出来整理成一份人能看懂、能交付、能随版本更新的文档。它适合三类人——需要给甲方交付数据库设计说明的开发者、接手遗留系统要快速摸清结构的维护人员、以及做数据治理前需要先盘清家底的从业者。这类工具的核心价值不在“生成”而在“可重复生成”建表语句一改字典能跟着重跑而不是靠人工在 Word 里逐条誊抄。下面按我实际拆解和复现的顺序把选型、抽取、导出、排错这条链路走一遍。2. 元数据从哪来三种抽取路径的取舍数据字典工具的第一道分水岭是元数据从哪里读。常见做法有三条读information_schema这类系统视图、解析建表 DDL 脚本、连库后逐表查询。三条路各有边界选错了后面全是返工。2.1 系统视图抽取最稳的默认路径绝大多数关系型数据库都维护着描述自身结构的系统表。以 MySQL 为例information_schema.TABLES存表级信息COLUMNS存字段级信息STATISTICS存索引KEY_COLUMN_USAGE存约束。这条路的好处是元数据由数据库自己维护不会因为脚本和实际库不一致而失真。-- 抽取某库全部表与字段的基础元数据 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_SCHEMA必须写实际库名写错就是空结果TABLE_TYPE过滤掉视图能避免字典里混进视图定义但如果你的交付要求包含视图把这行去掉即可。ORDINAL_POSITION别省它是后面还原字段顺序的唯一依据。索引和外键要单独抽因为它们是多对多关系直接和字段表 JOIN 会产生笛卡尔积膨胀。索引走STATISTICS按INDEX_NAME分组外键走KEY_COLUMN_USAGE里REFERENCED_TABLE_NAME IS NOT NULL的记录。我一般把这两块抽成独立查询在应用层按表名合并而不是硬塞进一条大 SQL。2.2 DDL 脚本解析适合没有库连接权限的场景有些环境拿不到数据库连接只给了一份schema.sql。这时只能解析建表语句。正则能应付简单场景但遇到带反引号、带COMMENT、带联合索引的 DDL 就容易翻车。稳妥做法是用现成的 SQL 解析库比如 Python 的sqlparse做粗切分再针对CREATE TABLE块做结构化提取。import re def parse_create_table(ddl_text): 从 DDL 文本中粗提表名、字段名、类型与注释 result [] # 按 CREATE TABLE 切块忽略 IF NOT EXISTS 的写法差异 blocks re.split(rCREATE\sTABLE, ddl_text, flagsre.IGNORECASE)[1:] for block in blocks: # 表名第一个反引号或裸标识符 name_match re.search(r[]?(\w)[]?\s*\(, block) if not name_match: continue table name_match.group(1) # 字段行以反引号开头、逗号结尾的片段 for line in block.splitlines(): col re.match(r\s*[](\w)[]\s([\w()]), line) if not col: continue comment re.search(rCOMMENT\s([^]*), line) result.append({ table: table, column: col.group(1), type: col.group(2), comment: comment.group(1) if comment else }) return result这段代码的定位是“够用就好”的粗解析不是完整 SQL 语法分析器。re.split按CREATE TABLE切块name_match抓表名字段行用re.match逐行匹配反引号包裹的列名和类型COMMENT单独用re.search抓引号内文本。参数上要注意如果你的 DDL 用双引号而非反引号把字符类改成[]类型里的(和)要保留在[\w()]里否则varchar(64)会被截成varchar。这条路的天生缺陷是拿不到运行时才有的信息比如自增当前值、实际行数交付文档里这类字段只能留空或标注“以线上为准”。2.3 连库逐表查询只在需要采样时用还有一种做法是连上库后对每张表执行SHOW FULL COLUMNS FROM xxx或DESC。它比系统视图多一层网络往返表多时明显慢但好处是能顺带拿到一些方言特有的信息。我的取舍是结构信息一律走系统视图只有需要补充“字段实际取值样例”时才逐表采样且采样必须加LIMIT绝不对大表做全表扫描。提示抽取阶段就把“结构元数据”和“数据样例”分开处理前者进字典正文后者单独存一份采样文件。混在一起会让字典体积失控也容易把敏感数据带进交付物。3. 把元数据变成文档模板、分组与导出抽到元数据只是原料真正决定字典好不好用的是组织方式。这一章讲怎么把扁平的字段列表变成有层级、可检索、能交付的文档。3.1 按业务域分组而不是按表名字母序直接按表名排序导出的字典读起来像电话簿。合格的做法是先定义分组规则把表归到业务域下。分组信息通常不在数据库里需要一份外部映射表比如一个 CSV表名、业务域、负责人、是否核心表。工具读取这份映射把没有归类的表统一放进“未分类”逼着使用者去补全而不是默默漏掉。import csv from collections import defaultdict def group_tables(meta_rows, mapping_file): 按外部映射把表分到业务域未命中的归入未分类 domain_map {} with open(mapping_file, encodingutf-8) as f: for row in csv.DictReader(f): domain_map[row[table]] row[domain] grouped defaultdict(lambda: defaultdict(list)) for r in meta_rows: domain domain_map.get(r[table], 未分类) grouped[domain][r[table]].append(r) return grouped逻辑很直白先读映射建domain_map再遍历元数据行用dict.get带默认值归组两层defaultdict保证“域 → 表 → 字段”的嵌套结构自动创建。参数上映射文件的表名必须和数据库里的大小写完全一致MySQL 在部分系统上表名大小写敏感这里对不上就会整表掉进“未分类”。我一般会在生成后统计“未分类”表的数量超过阈值就先停下来补映射而不是带着一堆未分类直接交付。3.2 模板渲染字段表、索引表、变更记录三件套一份能交付的字典每张表下面至少要有三块内容字段明细表、索引与外键表、变更记录。字段表列固定为字段名、类型、可空、默认值、注释索引表列索引名、字段组合、是否唯一变更记录则来自版本对比这块放到最后一章讲。渲染用模板引擎最省事Jinja2 或类似方案都行关键是模板里对空值要有兜底。from jinja2 import Template TABLE_TPL Template( ### {{ table }} {{ table_comment }} | 字段 | 类型 | 可空 | 默认值 | 注释 | |---|---|---|---|---| {% for c in columns -%} | {{ c.column }} | {{ c.type }} | {{ c.nullable }} | {{ c.default or - }} | {{ c.comment or 待补充 }} | {% endfor %} ) def render_table(table, columns, table_comment): return TABLE_TPL.render( tabletable, table_commenttable_comment or , columnscolumns )模板里c.default or -和c.comment or 待补充是两处关键兜底默认值为NULL时显示短横线注释为空时显示“待补充”这样交付物里不会出现大片空白让人误以为是导出失败。{% for %}后面的-}用来吃掉多余空行否则生成的 Markdown 表格行间会插空行导致渲染错乱。表注释为空时直接留空而不是写“无”是为了让后续检索“待补充”时能同时命中缺注释的字段和缺注释的表。3.3 导出格式Markdown 给协作Excel 给评审同一份元数据我一般导出两种格式。Markdown 进代码仓库跟着建表脚本一起做版本管理改动能进 diffExcel 给不碰代码的评审方方便他们批注。Excel 导出要注意两点字段注释里的换行符要替换成空格否则单元格会被撑开长文本列要设列宽上限不然打开就是一片超宽列。导出前统一做一次字符清洗把\r\n、\t规整掉这一步省了后面全是格式投诉。导出格式适用场景注意点Markdown进仓库、随版本 diff表格单元格内不能有裸竖线需转义Excel评审批注、非技术方阅读清洗换行符限制列宽HTML内网浏览、带搜索大库分页避免单页过重4. 避坑与排查五个真实翻车点工具跑通一次不难难的是每次都能跑通。下面这几条是我在不同库里反复踩到的按“现象 → 原因 → 解决”记下来。4.1 导出后字段顺序全乱现象字典里字段顺序和建表语句对不上id跑到中间去了。原因查询没带ORDER BY或者用了DISTINCT导致排序失效。解决字段查询必须显式ORDER BY TABLE_NAME, ORDINAL_POSITION渲染层不要再做二次排序否则两处排序规则不一致会互相覆盖。4.2 注释全是空的现象字段注释列整片空白但数据库里明明有注释。原因连的库不对或者账号权限只能看到部分元数据另一种常见情况是建表时注释写在COMMENT关键字后但用了双引号某些版本下不被识别。解决先用一条SHOW FULL COLUMNS手工确认注释是否存在确认存在再查抽取 SQL 的库名和账号权限最后才怀疑解析逻辑。4.3 大表把内存打爆现象表数量上千后导出进程被系统杀掉。原因一次性把所有元数据读进内存再渲染。解决改成按业务域分批查询、分批渲染、分批写文件最后再合并目录。分批的粒度按表数量控制单批两百张表左右比较稳具体看单表字段数。4.4 索引信息重复膨胀现象某张表的字段行数比实际字段多出好几倍。原因索引表和字段表直接 JOIN一个字段命中多个索引就复制多行。解决索引单独查询、单独渲染成索引表不要和字段明细放在同一条 SQL 里 JOIN。4.5 中文注释变乱码现象导出的 Excel 打开后注释是问号或方块。原因写文件时编码和打开方式不匹配常见于 CSV 直接双击打开。解决统一用 UTF-8 写文件CSV 场景加 BOM 头或者干脆导出 xlsx 而不是 csv从源头绕开编码问题。注意排错顺序建议固定为“先手工查库确认数据在不在 → 再查抽取 SQL → 最后查渲染和导出”。跳过第一步直接改代码十有八九是在修一个不存在的问题。5. 版本对比与增量更新让字典跟得上建表脚本字典最容易死的地方不是第一次生成而是第二次之后没人更新。真正让这份工具长期可用的是把它接进版本对比流程每次建表脚本变更自动跑一次抽取和上一版字典做 diff只把变化的部分标出来。5.1 用字段指纹做增量比对思路是给每个字段算一个指纹由表名、字段名、类型、可空、默认值、注释拼成任一变化指纹就变。比对时按“表名 字段名”做键分别找出新增、删除、修改三类。import hashlib def field_fingerprint(row): 把影响字典展示的字段属性拼成指纹 raw |.join([ row[table], row[column], row[type], str(row[nullable]), str(row[default]), row[comment] ]) return hashlib.md5(raw.encode(utf-8)).hexdigest() def diff_dict(old_rows, new_rows): old {(r[table], r[column]): field_fingerprint(r) for r in old_rows} new {(r[table], r[column]): field_fingerprint(r) for r in new_rows} added [k for k in new if k not in old] removed [k for k in old if k not in new] changed [k for k in new if k in old and new[k] ! old[k]] return added, removed, changed指纹里把nullable和default也str()进去是因为这两个值可能是None直接拼接会抛类型错误。md5在这里只做等值比较用不涉及安全场景换成任意稳定哈希都行。返回的三类结果直接对应变更记录的三个小节新增字段、删除字段、修改字段。修改类还可以进一步细分是类型变了还是注释变了做法是把指纹拆成多个子指纹分别比对按需加。5.2 变更记录写进字典正文diff 结果不要只打印到控制台要写进字典对应表的“变更记录”小节带上版本号和日期。这样评审方翻到某张表时能直接看到“这个字段上个月刚从varchar(32)扩到varchar(64)”而不是去翻提交历史。版本号建议和建表脚本的版本对齐别另起一套编号否则两套版本号对不上又是一笔糊涂账。5.3 一个我固定保留的习惯从那以后我每次交付字典前都强制走一遍“空库重跑”拿一份干净的测试库从建表脚本重建结构再跑一次抽取和渲染把结果和正式库的字典做 diff。两边一致才交付不一致说明正式库里有手工改过、没进脚本的结构这种“脚本外的漂移”恰恰是后续维护最大的雷。这一步多花十分钟能省掉后面无数次“文档和库对不上”的扯皮。希望这套流程能帮到你把字典从一次性产物变成能跟着库一起演进的东西。本文还有配套的精品资源点击获取