上个月接了一个算不上复杂、但特别磨人的内部需求把sldd里维护的数据字典导出成Excel发给业务方做数据资产评审。一开始我的想法跟大多数人一样工具里自带导出功能点两下不就完事了结果折腾下来才发现sldd导出的HTML和Word压根不是业务方想要的格式字段注释、主键标识、可筛选这些需求全部要重新整合最后不得不绕了一圈自己写了套解析和生成脚本。整个过程踩了不少坑但也沉淀出一套可以反复使用的流程。这篇文章就把完整的导出链路、脚本思路和踩坑记录分享出来给正在被数据字典折磨的人一个参考。1. 一个“导出”需求背后的真实战场谁在看数据字典1.1 数据字典不是给自己看的数据字典在很多人眼里就是开发期的“附属品”表结构定完了顺手导出一份扔到文档库里就完事。但真正用起来之后你会发现在不同阶段、不同角色面前数据字典扮演的角色完全不一样。开发阶段新同学接手模块第一件事就是对着数据字典看表结构字段注释写得不清楚后面排查问题全靠猜。评审阶段架构师和数据负责人要逐条核对字段命名是否规范、类型是否合理、默认值是否符合约定这时候表格化的字典比ER图更实用因为可以按字段顺序逐行评审。到了数据治理阶段业务方会拿着字典去标注敏感字段、盘点数据资产、核对哪些字段还挂在线上流程里他们需要在Excel里筛选、打批注、标颜色、甚至把你的字段说明改一版发回来。审计和外审场景更不用说需要带版本记录的字典文件。这也就意味着数据字典的消费对象远不止开发团队。如果一个字典产物只适合技术人员阅读它在业务协作环节就是失灵的。而Excel恰好是跨角色协作里接受度最高的格式——会筛选就能用会批注就能反馈不需要装数据库客户端也不需要懂SQL。这也是为什么“导成Excel”听起来像个简单需求实际上每个人拿到手之后都会有自己的一套加工动作。1.2 sldd自带的导出产物和业务需求差在哪sldd本身是一款很顺手的表结构设计工具设计表、维护字段、画关系图都挺方便。但它自带的导出功能默认产物是面向“开发人员阅读”的不是面向“业务消费”的。以我使用的版本为例导出菜单里最常见的输出格式是HTML、Word和PDF。这些格式有个共同问题信息结构是“从上往下排”的一张表下面跟着一堆字段适合在线阅读但不适合二维筛选和二次加工。就算某些版本支持直接导出Excel导出来的表头通常是英文的字段名类型显示的是类似于“int”“varchar”这种原始数据库类型完全没有把“业务含义”放在最显眼的列上。更要命的是表注释和外键关系经常被拆到单独的区域字段和注释对不上行顺序也和sldd设计区里的展示不完全一致。还有人会想到一招HTML导出后用Excel打开或者Word转Excel。这条路在小表场景下勉强能用但表一多就露馅——合并单元格错位、换行符丢失、列宽混乱稍微调整一下格式大半天时间就没了。经历过一次之后就明白这不是“换个导出格式”的问题而是sldd内部的数据结构是“模型化的”里面有表、字段、约束、关系这些对象Excel是“表格化的”只有行和列。从对象模型到二维表格中间需要一次真正的映射转换而不是简单的另存为。所以把sldd数据字典导出为Excel本质上不是工具操作问题而是一个数据转换工程。这也是为什么值得写一套稳定的脚本来处理而不是每次手工点导出。1.3 先定方案三条路线我为什么选了SQL脚本中转拿到需求后我先列了几条可能的实现路线简单做了个对比。方案优点缺点适用场景sldd自带导出HTML/Word再用Office转换操作门槛低不需要写代码格式乱套、注释丢失、大表基本不可用表数量极少、一次性临时用sldd导出SQL脚本自己写脚本解析成Excel完全可控格式标准可反复使用需要一定的编程能力首次搭建耗时表数量多、需要长期维护、有交付模板要求跳过sldd直接从数据库元数据抽取不依赖sldd版本数据准确需要数据库连接权限模型的逻辑结构可能没同步到库里数据库和模型已同步、可以直连时我最开始试了第一条路结果被格式问题劝退。第三条路也评估过但当时项目里的数据库和sldd模型存在一些偏差——有几个字段只在模型里还没来得及同步到库表直接从库里取会漏字段。综合下来选了第二条路从sldd导出建表SQL脚本把脚本作为中间产物然后用Python解析脚本里的DDL语句还原出表、字段、注释、约束这些结构化信息最后用openpyxl生成一份经过精心布局的Excel。这样既保证数据来源和sldd模型一致又绕开了自带导出的格式问题。后面的事实也证明这个选择是对的。2. 动手前必须清楚sldd导出的SQL里藏着哪些信息2.1 完整数据字典的四层信息结构写解析脚本之前先得搞清楚一份完整的数据字典到底由哪些信息构成不然脚本写到一半才发现漏了字段返工很痛苦。我按信息层级拆成了四层。第一层是表基本信息表名、表注释、存储引擎、字符集。这些信息通常在DDL的末尾比如MySQL里ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户信息表这一段。表注释特别重要业务方看字典时首先看的就是“这张表是干什么的”。第二层是字段信息也是最核心的一层。包括字段名、字段类型、长度、精度、是否允许为空、默认值、字段注释。sldd生成的DDL里每个字段行都会带COMMENT xxx这就是字段的业务含义导出Excel时一定要放到显眼的位置。第三层是约束信息主键、唯一键、索引。主键字段需要在Excel里单独标识因为业务方在梳理主数据时第一眼就要找主键。索引不一定需要展开成明细但至少要能看出哪些字段被索引覆盖。第四层是关系信息外键、字段间的关联关系。Excel的二维表格不太好表达关系但至少可以在备注列标注“关联xxx表xxx字段”方便了解表之间的关联。如果需求里明确要画ER图那就别指望Excel了直接导出到专业建模工具或再配合图表工具处理。2.2 导出DDL时的几个关键配置项从sldd导出SQL脚本的时候有几个配置项会直接影响后续的解析质量这里特别值得注意。第一个是导出范围。sldd一般支持全库导出、按模块导出、选中指定表导出。做完整数据字典时建议选择全库导出但如果你只想导出某几个业务模块就按模块选减少Excel里不相关的表。第二个是注释的保留。这个必须确认勾选无论是表注释还是字段注释都要带上。没有注释的数据字典基本等于废纸后面解析出来的Excel业务方根本看不懂。第三个是索引和外键的包含选项。索引信息看需求如果只需要基础字典可以先不导出外键减少解析复杂度。但如果要做数据血缘或者字段关联分析外键信息就必须保留。第四个是字符集设置。一定要确保导出文件是UTF-8编码否则中文注释到了后面脚本解析和Excel生成环节大概率会出现乱码。这个坑我在4.3节详细讲但源头就在这里导出时就要注意。这些配置在不同版本里菜单位置可能不一样但思路是通用的。拿到SQL文件后建议先用文本编辑器打开看一小段确认里面的注释完整、编码正常再进入解析环节。2.3 不同数据库方言对解析脚本的影响sldd支持多种数据库导出SQL的方言也不一样这个因素在写解析脚本前就要评估好。我这次处理的是MySQLDDL格式相对规整字段行一般是\字段名 varchar(64) NOT NULL DEFAULT COMMENT 备注这种结构表尾有一段ENGINE... COMMENT...。解析起来比较直接。但如果你面对的是Oracle、PostgreSQL或者SQL ServerDDL形态差异会很大。Oracle习惯用NUMBER(10,2)、VARCHAR2(100)注释存在COMMENT ON COLUMN 表名.字段名 IS 备注这种独立语句里而不是字段行尾PostgreSQL用character varying(100)和COMMENT ON COLUMNSQL Server则是[字段名] nvarchar(100)。这意味着解析逻辑要跟着数据库类型走不能拿一套正则硬套所有方言。所以动手写脚本前先确认sldd导出的SQL是哪种数据库风格再决定字段解析规则。如果项目里混合了多种数据库建议每个数据库类型单独写一个解析器或者抽象出一个接口避免后续维护时逻辑纠缠在一起。3. 从DDL到Excel完整实现过程与核心代码3.1 DDL解析表、字段、约束的一次性梳理解析DDL是整个流程里最关键的一步也是我返工最多的地方。一开始图省事用了一堆正则表达式去硬配结果被各种边界情况折磨得不行。后来改用分层解析的思路先把整个SQL文件按CREATE TABLE分割成独立的建表块再逐个块解析表名、字段、主键和表注释。这里给出一个解析MySQL DDL的参考实现核心思路是把表拆成块再从块里抽字段。import re from dataclasses import dataclass, field from typing import List, Optional dataclass class FieldInfo: name: str col_type: str length: str nullable: bool default: Optional[str] comment: str is_primary: bool False dataclass class TableInfo: table_name: str table_comment: str fields: List[FieldInfo] field(default_factorylist) FIELD_RE re.compile( r(?Pname[^])\s r(?Ptype[a-zA-Z0-9_]) r(?:\((?Plength[^)]*)\))? r(?:\sUNSIGNED)? r(?:\sNOT\sNULL)? r(?:\sDEFAULT\s(?PdefaultNULL|[^]*|[\w.]|CURRENT_TIMESTAMP(?:\([^)]*\))?))? r(?:\sCOMMENT\s(?Pcomment(?:[^]|)*))?, re.IGNORECASE, ) def parse_sql_file(sql_path: str) - List[TableInfo]: with open(sql_path, r, encodingutf-8) as f: sql_content f.read() create_blocks re.split( rCREATE\sTABLE\s(?:IF\sNOT\sEXISTS\s)?, sql_content, flagsre.IGNORECASE ) tables [] for block in create_blocks[1:]: table_name_match re.match(r?(\w)?\s*\(, block.strip()) if not table_name_match: continue table_name table_name_match.group(1) table_comment_match re.search( rCOMMENT\s*\s*(?Pcomment(?:[^]|)*), block, re.IGNORECASE ) table_comment ( table_comment_match.group(comment).replace(, ) if table_comment_match else ) fields_body block[block.find(() 1: block.rfind())] primary_match re.search( rPRIMARY\sKEY\s*\((?Pcols[^](?:\s*,\s*[^])*)\), block, re.IGNORECASE, ) primary_cols set() if primary_match: for col in re.findall(r([^]), primary_match.group(cols)): primary_cols.add(col.lower()) table_info TableInfo(table_nametable_name, table_commenttable_comment) lines fields_body.split(\n) for line in lines: line line.strip().rstrip(,) if not line or line.startswith((PRIMARY, KEY, UNIQUE, CONSTRAINT, INDEX)): continue m FIELD_RE.match(line) if not m: continue fname m.group(name) ftype m.group(type) length m.group(length) default m.group(default) if default is not None: default default.strip() comment m.group(comment) or comment comment.replace(, ) table_info.fields.append( FieldInfo( namefname, col_typeftype, lengthlength or , nullableNOT NULL not in line.upper(), defaultdefault, commentcomment, is_primaryfname.lower() in primary_cols, ) ) tables.append(table_info) return tables这个脚本有几个关键点。分割建表块时用了CREATE TABLE关键字避免块之间互相干扰。字段正则里重点处理了DEFAULT和COMMENT的排列组合因为sldd导出的DDL在不同配置下顺序可能不一样。主键单独从块尾找再回填到字段对象里。表注释用COMMENTxxx来匹配注意处理SQL里用转义单引号的情况。这个实现不完美有些极端场景比如字段类型是enum(a,b)或者带ON UPDATE CURRENT_TIMESTAMP的字段可能解析不准。我实际跑的时候遇到这种情况是单独加正则分支处理的或者干脆用sqlparse这类库。但如果你处理的表结构比较规整这套逻辑足够作为起点。3.2 Excel生成版式、样式、列宽与数据格式解析出结构化信息之后下一件事就是把它们写进Excel。这一步的重点不是“能写进去”而是“写出来的表格让业务方愿意用”。我踩过用pandas一把梭的坑——导出的表格能用但很粗糙表头灰扑扑没有任何样式用户拿到手还得自己调半天。后来改用openpyxl把版式细节都放进脚本里。我的设计原则是每个Sheet放一张表Sheet名用“表注释_表名”的格式第一行加粗深色底纹作为列头冻结首行开启筛选主键字段整行浅黄色标记。列的顺序按“序号、字段名、字段说明、数据类型、长度、允许空、默认值、主键、备注”来排。字段说明之所以放在第三列而不是第一列是因为业务方最关心的是“这个字段干嘛的”字段名反而是开发人员才盯的。关键代码如下。import os import re from openpyxl import Workbook from openpyxl.styles import Font, PatternFill, Alignment, Border, Side from openpyxl.utils import get_column_letter HEADER_FILL PatternFill(start_colorD9E1F2, end_colorD9E1F2, fill_typesolid) PRIMARY_FILL PatternFill(start_colorFFF2CC, end_colorFFF2CC, fill_typesolid) HEADER_FONT Font(boldTrue, size11) THIN_BORDER Border( leftSide(stylethin, colorD0D0D0), rightSide(stylethin, colorD0D0D0), topSide(stylethin, colorD0D0D0), bottomSide(stylethin, colorD0D0D0), ) HEADERS [序号, 字段名, 字段说明, 数据类型, 长度, 允许空, 默认值, 主键, 备注] def safe_sheet_name(name: str) - str: name re.sub(r[\\/*?:\[\]], _, name) return name[:31] or Sheet def calc_width(value: str) - int: if not value: return 10 width sum(2 if ord(ch) 127 else 1 for ch in str(value)) return min(max(width 4, 10), 50) def build_excel(tables, output_path: str): wb Workbook() wb.remove(wb.active) for table in tables: sheet_name safe_sheet_name(f{table.table_comment}_{table.table_name}) ws wb.create_sheet(titlesheet_name) ws.append(HEADERS) for col_idx, header in enumerate(HEADERS, start1): cell ws.cell(row1, columncol_idx) cell.fill HEADER_FILL cell.font HEADER_FONT cell.alignment Alignment(horizontalcenter, verticalcenter) cell.border THIN_BORDER for row_idx, f in enumerate(table.fields, start2): row_data [ row_idx - 1, f.name, f.comment, f.col_type, f.length, 是 if f.nullable else 否, f.default if f.default is not None else , PK if f.is_primary else , , ] ws.append(row_data) for col_idx, value in enumerate(row_data, start1): cell ws.cell(rowrow_idx, columncol_idx) cell.border THIN_BORDER if col_idx 1: cell.alignment Alignment(horizontalcenter, verticalcenter) elif col_idx 3: cell.alignment Alignment(horizontalleft, verticalcenter, wrap_textTrue) else: cell.alignment Alignment(horizontalcenter, verticalcenter) if f.is_primary: cell.fill PRIMARY_FILL for col_idx, header in enumerate(HEADERS, start1): max_width 0 for row in ws.iter_rows(min_colcol_idx, max_colcol_idx, min_row1, max_rowws.max_row): for cell in row: max_width max(max_width, calc_width(cell.value)) ws.column_dimensions[get_column_letter(col_idx)].width max_width ws.freeze_panes A2 ws.auto_filter.ref ws.dimensions os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_okTrue) wb.save(output_path) return output_path几个设计细节说明一下。Sheet名用了“表注释_表名”因为业务方看到“用户信息表_user_info”比看“user_info”直观得多。但Excel的Sheet名限制31个字符所以加了safe_sheet_name做清洗和截断。如果注释特别长导致截断后不同表重名可以在脚本里检测重名并追加序号这个我实际处理过问题不大。列宽我根据内容动态计算中文字符按宽度2、英文字符按宽度1估算再限个上下限。字段说明列允许自动换行长注释不会把行撑得特别高。主键行用浅黄色高亮业务方扫一眼就能定位每张表的核心字段。冻结首行和自动筛选属于标配没有这两项的Excel在业务方手里基本等于半成品。3.3 校验导出结果宁可多写检查不可上线翻车脚本跑通之后很多人会直接打开Excel看一眼觉得差不多就交付了。但表多了之后肉眼校验根本看不过来尤其是字段数量、注释完整性、主键标识这些细节一旦出错业务方会在评审会上直接挑出来非常被动。我后来在流程里加了一个校验环节脚本生成完Excel之后自动做三件事。第一对比表数量。解析出的表数量要和sldd里选中的表数量一致少了任何一张都是大问题。第二对比字段数量。从DDL解析出的字段数和Excel里每个Sheet的最大行数减1做比对不一致说明生成环节有遗漏。第三抽查字段注释。检查有没有字段的comment为空或者comment里出现异常符号。from openpyxl import load_workbook def validate_excel(output_path: str, tables) - List[str]: problems [] wb load_workbook(output_path) for t in tables: sheet_name safe_sheet_name(f{t.table_comment}_{t.table_name}) if sheet_name not in wb.sheetnames: problems.append(f表 {t.table_name} 缺少Sheet: {sheet_name}) continue ws wb[sheet_name] field_count ws.max_row - 1 if field_count ! len(t.fields): problems.append( f表 {t.table_name} 字段数不一致期望 {len(t.fields)}实际 {field_count} ) empty_comment_cols [] for row in ws.iter_rows(min_row2, min_col3, max_col3): cell row[0] if not cell.value or not str(cell.value).strip(): empty_comment_cols.append(cell.row) if empty_comment_cols: problems.append( f表 {t.table_name} 存在空注释字段行号: {empty_comment_cols[:10]} ) return problems这个校验脚本虽然简单但在后续反复导出的时候特别管用。数据库模型会有调整sldd里的表结构会变如果哪次导出的SQL文件有问题校验脚本会第一时间拦住不会让一个规格不对的Excel流到业务方手里。4. 导出Excel后最容易踩的格式坑逐个排查给你看4.1 科学计数法身份证号、长数字、默认值都中过招很多人第一次把字典导出到Excel打开一看就懵了有些默认值字段明明写的是1234567890123结果单元格里变成了1.23457E12后几位全成了0。业务方要是拿着这种Excel去核对主数据基本等于报废。这个问题的根源在于Excel的单元格类型是自动推断的超过一定长度的数字会被识别成科学计数法。我遇到过的场景包括身份证号、订单号、长整型默认值。sldd的DDL里这些值可能是纯数字字符串但Excel不认。解决方法有两个层面。一个是从源头避免openpyxl写入时把可能的数字字符串统一设置成文本格式让Excel把它当字符串处理而不是数字。具体可以在写单元格时设置number_format 。cell.number_format 另一个是事后修复如果Excel已经生成全选那列菜单里选“数据-分列-文本”或者设置单元格格式为“文本”后重新粘贴一遍。但能自动化的事就不要手工做直接在脚本里对所有非数值型字段强制文本格式是最省心的。之前在排查一个从Oracle导出的身份证信息变成科学计数法的问题时本质也是一样的。数据本身没错错在读和写的环节把它当成数字了。处理方式就是不依赖Excel自动识别明确告诉它“这是文本”。4.2 长注释被截断根因在解析逻辑而不是Excel这个问题排查起来比较隐蔽。现象是导出的Excel里某些字段的中文注释只剩前半截后半截不翼而飞。如果直接怀疑Excel你会发现Excel单元格本身可以容纳很多字符根本不存在“截断”的能力。问题出在DDL解析环节。我最初解析字段注释用的正则是COMMENT (.?)这是非贪婪匹配它会匹配到字段行注释的第一个单引号就停下来。正常情况下没问题但如果注释里面包含了单引号比如“用户昵称”或者注释非常长、中间有换行正则就会在中途断掉注释自然就少了一段。排查过程可以这样复现先用文本编辑器打开sldd导出的SQL文件找到对应字段的原始DDL确认注释是完整的。然后跑Python解析把解析出来的comment打出来对比就能看出是解析截断。我当时的解决方式是把正则在COMMENT段改成匹配连续非单引号字符或者双单引号转义的形式COMMENT (?:[^]|)*然后取中间内容再反转义。如果你不想处理这些边界情况直接引入sqlparse库来做SQL语法解析会更稳。这个坑给我最大的教训是解析SQL时不要迷信正则的“看起来差不多”。一旦数据量上来各种边界情况都会出现宁可多花半小时把解析规则写严谨也不要在交付前被业务方发现注释不完整。4.3 中文乱码编码问题在不同环节的“传染链”乱码问题一旦出现影响面特别大因为整张Excel里的中文注释会全部变成乱码或者问号基本等于不能用。而且乱码的根源可能出现在多个环节排查起来很烦。我遇到过的情况主要有三种。第一种是sldd导出SQL时用了非UTF-8编码文件本身就是GBK或者其他编码。用文本编辑器打开看着正常因为编辑器会自动识别但脚本读取时如果按UTF-8解码就报编码错误或者静默产生乱码。解决办法是读取文件时做编码探测常见编码列表[utf-8, gb18030, utf-8-sig]逐个尝试。def read_sql_with_encoding(path: str) - str: encodings [utf-8-sig, utf-8, gb18030] for enc in encodings: try: with open(path, r, encodingenc) as f: return f.read() except UnicodeDecodeError: continue raise RuntimeError(f无法识别文件编码: {path})第二种是脚本处理过程中字符串的编码转换出错比如在Windows控制台环境时默认GBK编码日志和交互环境互相干扰。建议在脚本入口显式统一编码环境或者尽量用UTF-8输出。第三种是Excel本身没问题但列宽太窄导致中文字符显示成“###”这个不算乱码调列宽就行。虽然这个不算严格意义上的乱码但业务方会一样把它当成bug反馈过来所以也列进了排查清单。4.4 表多了就卡死大字典Excel的性能优化当数据库比较大比如几十张表、上千个字段的时候Excel文件容易变得又大又卡。我碰到过一次生成出的Excel在同事电脑上打开要转圈十几秒滚动的时候一卡一卡直接被吐槽。排查下来主要有几个原因。首先是合并单元格。很多人喜欢把表头做得很花哨几行合并、跨列合并Excel打开时合并单元格的渲染开销很大。数据越多越明显。解决方式是尽量少用合并我设计的版式里第一行就是列头没有合并且每个Sheet的第一行保持一致处理起来最干净。其次是条件格式。条件格式是“按需计算”的字段数量多的时候每次重算都会拖慢性能。我的方案里只用普通单元格底色来标主键不用条件格式规则性能好很多。再就是自动筛选和冻结窗格。这两个功能虽然是刚需但如果同时叠加再加上几百行数据打开速度也会受影响。我的做法是保留这两个功能但不再叠加其他东西。如果单表数据量超过几千行建议再拆Sheet或者拆文件。最后是文件体积。如果Excel里塞了大量无意义的样式或者空行文件会膨胀。生成后可以检查一下文件大小超过5MB基本就要想想是不是哪里有问题。5. 从一次导出到自动化流水线5.1 用配置文件约束每次导出的边界第一次手工跑通脚本后我觉得这事不能只干一次因为数据字典是活的东西表结构一调整就要重新导出。所以很快就想着把流程包装成一条可重复使用的“小流水线”。我做的第一件事是把脚本参数外置成配置文件避免每次改代码。用一个YAML或者JSON文件管起来内容包括SQL文件路径、Excel输出路径、需要排除的表、是否导出索引、Sheet命名风格等等。input: sql_file: ./schema.sql output: excel_file: ./数据字典_20250601.xlsx tables: include: [] # 空表示全部 exclude: - tmp_% - audit_log% options: include_index: true include_foreign_key: false sheet_name_style: comment_table # comment_table 或 table_only脚本入口统一接收配置文件路径再读配置决定行为。这样每次导出只需要更新SQL文件和输出文件名不用改动脚本本身。表排除规则我用的是通配符匹配比如临时表、日志表这类不进入正式数据字典的表在配置里一写就过滤掉了省得每次导出后还要手动删Sheet。5.2 数据库直连方案没有sldd也能一键出字典自动化到一定程度后你会意识到一个问题sldd里的模型和线上数据库可能不同步。如果团队里有人直接在数据库里改了表结构没有回头更新sldd模型那从sldd导出的字典就会漏掉这些变更。所以我又加了一个备用入口直接连接数据库从系统的元数据表里抽取字典信息。以MySQL为例information_schema.COLUMNS表里有所有字段的信息一条SQL就能把库里的建表元数据拉出来再套用同一套Excel生成逻辑。SELECT TABLE_NAME, COLUMN_NAME, ORDINAL_POSITION, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_KEY, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your_database_name ORDER BY TABLE_NAME, ORDINAL_POSITION;拿到这个查询结果之后再用pandas或者直接遍历组装成同样的结构化数据喂给之前的build_excel函数就行。表注释从information_schema.TABLES里取。这条方案的好处是数据永远跟线上库一致坏处是它只能反映“物理表”的现状无法还原sldd模型里的逻辑设计、外键关系图这些“设计意图”。所以我的建议是两条腿走路模型同步及时的项目用sldd导出SQL模型和库不一致的用数据库直连救急。两种方式的产出都是同一个Excel格式对下游无感。5.3 定时任务与版本归档到了这一步自动化已经完成80%了最后剩下的就是“定时自动跑”。数据字典不是一次性交付物我这边约定的是每周生成一版留档备查。这个需求用Linux的cron或者Windows的计划任务就能搞定。我用的是Linux环境cron表达式大概是这样0 18 * * 5 cd /opt/dict_export /usr/bin/python3 build_dict.py -c config.yaml logs/dict_export.log 21每周五下午6点生成一版文件命名带日期归档到固定目录。要注意的是定时任务跑Python时环境变量可能和手动执行不一样容易出现“找不到模块”“编码不对”一类的诡异问题。我的经验是在cron里把Python解释器路径写全并且在脚本内部用之前写的编码探测函数不要依赖系统默认编码。归档目录的命名规则我建议做成数据字典_YYYYMMDD.xlsx这样后续查找历史版本很方便。如果团队有数据资产平台也可以把这套脚本生成的Excel挂到平台上按周更新彻底摆脱手工操作。6. 这套流程用下来的边界和最终选型建议6.1 实测效果从半小时到两分钟整套流程跑通之后我最直观的感受是导出数据字典这件事从“每次都要重新折腾”变成了“两分钟搞定”。之前手工处理一份覆盖几十张表、上千字段的字典从sldd导出、调整格式、校正注释、整理成业务方能看的Excel少说半小时多则一两个小时而且每次都会有那么几个格式问题要修。现在流程变成sldd里更新模型并导出SQL然后跑一条命令自动生成带样式的Excel。校验脚本还会自动检查表数量、字段数量和空注释基本上不需要人工核对。整体时间压缩到两分钟左右而且质量比手工操作稳定太多。这套流程还带来一个隐形收益每次评审时如果业务方提出要调整格式比如增加一列“所属模块”或者把“允许空”改成“必填”的布尔语义我只需要改脚本里的表头配置再重新跑一次即可。所有历史版本都能重新生成不存在“改了一版其他版没同步”的问题。6.2 别指望Excel包打天下不适合的场景虽说Excel是通用格式但也不能无限拔高它的作用。有几个场景我是建议别硬用Excel的。第一个是实时在线查询。如果团队日常需要快速查字段含义、看表结构不如直接用数据库客户端或者内部的知识库平台Excel文件每次都要下载打开效率太低。第二个是多人同时编辑。Excel的协作能力再强也比不上在线表格或者专业的数据建模协同工具。多人同时批注、修改字段说明时Excel文件很容易出现版本冲突。第三个是字段血缘和依赖关系。Excel只能展示字段本身的一行信息表达不了“这个字段从哪来、被哪个下游任务引用”这种数据血缘关系这类需求要找专门的数据治理工具。我自己遇到最多的是第二种场景。业务方拿回一份Excel标注了几个字段的修改意见然后发回来。这时如果没做好版本管理很容易出现“你改你的我改我的”的混乱局面。我的处理方式是业务方的反馈意见统一收到一个意见收集表里我再统一改sldd模型并重新生成字典而不是直接编辑已交付的Excel。这样源头模型永远是准的下游产物只是模型的一个投影。6.3 个人建议把注释当代码一样维护最后聊一点工作中的体会。这整套导出流程再自动化也只是把数据字典的“呈现层”问题解决掉了。更关键的是源头——sldd模型里的注释质量。注释写得好不好直接决定导出的Excel有没有价值。见过太多项目的字段注释是空的或者写的是备注、名称、状态这类说了等于没说的内容。这种注释导出去业务方根本没法用。所以我在团队里定的一个规范是每个字段必须写注释注释里要体现业务含义尽量包含口径说明比如“订单状态0待支付1已支付2已取消”而不是简单写“状态”。这个规范执行得越好后面所有依赖数据字典的环节就越轻松。再一个体会是数据字典这类“看起来不起眼”的交付物恰恰是团队协作里最容易出现信息损耗的环节。模型在sldd里业务方在Excel上开发在代码里三方的信息如果不一致迟早出问题。把从模型到Excel的转换链路脚本化、标准化本质上是把这种损耗降到了最低。这也是这篇文章真正想表达的东西——真正解决问题的不是某一次导出操作而是把这件小事当成一个工程来对待。另外补充一个环境层面的小技巧。如果日常是在Windows上跑脚本注意设置PYTHONIOENCODINGutf-8不然控制台输出中文注释时经常报UnicodeEncodeError。这个坑很小但第一次遇到会觉得莫名其妙顺手记录一下。
数据字典导出Excel：从DDL解析到自动化生成
上个月接了一个算不上复杂、但特别磨人的内部需求把sldd里维护的数据字典导出成Excel发给业务方做数据资产评审。一开始我的想法跟大多数人一样工具里自带导出功能点两下不就完事了结果折腾下来才发现sldd导出的HTML和Word压根不是业务方想要的格式字段注释、主键标识、可筛选这些需求全部要重新整合最后不得不绕了一圈自己写了套解析和生成脚本。整个过程踩了不少坑但也沉淀出一套可以反复使用的流程。这篇文章就把完整的导出链路、脚本思路和踩坑记录分享出来给正在被数据字典折磨的人一个参考。1. 一个“导出”需求背后的真实战场谁在看数据字典1.1 数据字典不是给自己看的数据字典在很多人眼里就是开发期的“附属品”表结构定完了顺手导出一份扔到文档库里就完事。但真正用起来之后你会发现在不同阶段、不同角色面前数据字典扮演的角色完全不一样。开发阶段新同学接手模块第一件事就是对着数据字典看表结构字段注释写得不清楚后面排查问题全靠猜。评审阶段架构师和数据负责人要逐条核对字段命名是否规范、类型是否合理、默认值是否符合约定这时候表格化的字典比ER图更实用因为可以按字段顺序逐行评审。到了数据治理阶段业务方会拿着字典去标注敏感字段、盘点数据资产、核对哪些字段还挂在线上流程里他们需要在Excel里筛选、打批注、标颜色、甚至把你的字段说明改一版发回来。审计和外审场景更不用说需要带版本记录的字典文件。这也就意味着数据字典的消费对象远不止开发团队。如果一个字典产物只适合技术人员阅读它在业务协作环节就是失灵的。而Excel恰好是跨角色协作里接受度最高的格式——会筛选就能用会批注就能反馈不需要装数据库客户端也不需要懂SQL。这也是为什么“导成Excel”听起来像个简单需求实际上每个人拿到手之后都会有自己的一套加工动作。1.2 sldd自带的导出产物和业务需求差在哪sldd本身是一款很顺手的表结构设计工具设计表、维护字段、画关系图都挺方便。但它自带的导出功能默认产物是面向“开发人员阅读”的不是面向“业务消费”的。以我使用的版本为例导出菜单里最常见的输出格式是HTML、Word和PDF。这些格式有个共同问题信息结构是“从上往下排”的一张表下面跟着一堆字段适合在线阅读但不适合二维筛选和二次加工。就算某些版本支持直接导出Excel导出来的表头通常是英文的字段名类型显示的是类似于“int”“varchar”这种原始数据库类型完全没有把“业务含义”放在最显眼的列上。更要命的是表注释和外键关系经常被拆到单独的区域字段和注释对不上行顺序也和sldd设计区里的展示不完全一致。还有人会想到一招HTML导出后用Excel打开或者Word转Excel。这条路在小表场景下勉强能用但表一多就露馅——合并单元格错位、换行符丢失、列宽混乱稍微调整一下格式大半天时间就没了。经历过一次之后就明白这不是“换个导出格式”的问题而是sldd内部的数据结构是“模型化的”里面有表、字段、约束、关系这些对象Excel是“表格化的”只有行和列。从对象模型到二维表格中间需要一次真正的映射转换而不是简单的另存为。所以把sldd数据字典导出为Excel本质上不是工具操作问题而是一个数据转换工程。这也是为什么值得写一套稳定的脚本来处理而不是每次手工点导出。1.3 先定方案三条路线我为什么选了SQL脚本中转拿到需求后我先列了几条可能的实现路线简单做了个对比。方案优点缺点适用场景sldd自带导出HTML/Word再用Office转换操作门槛低不需要写代码格式乱套、注释丢失、大表基本不可用表数量极少、一次性临时用sldd导出SQL脚本自己写脚本解析成Excel完全可控格式标准可反复使用需要一定的编程能力首次搭建耗时表数量多、需要长期维护、有交付模板要求跳过sldd直接从数据库元数据抽取不依赖sldd版本数据准确需要数据库连接权限模型的逻辑结构可能没同步到库里数据库和模型已同步、可以直连时我最开始试了第一条路结果被格式问题劝退。第三条路也评估过但当时项目里的数据库和sldd模型存在一些偏差——有几个字段只在模型里还没来得及同步到库表直接从库里取会漏字段。综合下来选了第二条路从sldd导出建表SQL脚本把脚本作为中间产物然后用Python解析脚本里的DDL语句还原出表、字段、注释、约束这些结构化信息最后用openpyxl生成一份经过精心布局的Excel。这样既保证数据来源和sldd模型一致又绕开了自带导出的格式问题。后面的事实也证明这个选择是对的。2. 动手前必须清楚sldd导出的SQL里藏着哪些信息2.1 完整数据字典的四层信息结构写解析脚本之前先得搞清楚一份完整的数据字典到底由哪些信息构成不然脚本写到一半才发现漏了字段返工很痛苦。我按信息层级拆成了四层。第一层是表基本信息表名、表注释、存储引擎、字符集。这些信息通常在DDL的末尾比如MySQL里ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户信息表这一段。表注释特别重要业务方看字典时首先看的就是“这张表是干什么的”。第二层是字段信息也是最核心的一层。包括字段名、字段类型、长度、精度、是否允许为空、默认值、字段注释。sldd生成的DDL里每个字段行都会带COMMENT xxx这就是字段的业务含义导出Excel时一定要放到显眼的位置。第三层是约束信息主键、唯一键、索引。主键字段需要在Excel里单独标识因为业务方在梳理主数据时第一眼就要找主键。索引不一定需要展开成明细但至少要能看出哪些字段被索引覆盖。第四层是关系信息外键、字段间的关联关系。Excel的二维表格不太好表达关系但至少可以在备注列标注“关联xxx表xxx字段”方便了解表之间的关联。如果需求里明确要画ER图那就别指望Excel了直接导出到专业建模工具或再配合图表工具处理。2.2 导出DDL时的几个关键配置项从sldd导出SQL脚本的时候有几个配置项会直接影响后续的解析质量这里特别值得注意。第一个是导出范围。sldd一般支持全库导出、按模块导出、选中指定表导出。做完整数据字典时建议选择全库导出但如果你只想导出某几个业务模块就按模块选减少Excel里不相关的表。第二个是注释的保留。这个必须确认勾选无论是表注释还是字段注释都要带上。没有注释的数据字典基本等于废纸后面解析出来的Excel业务方根本看不懂。第三个是索引和外键的包含选项。索引信息看需求如果只需要基础字典可以先不导出外键减少解析复杂度。但如果要做数据血缘或者字段关联分析外键信息就必须保留。第四个是字符集设置。一定要确保导出文件是UTF-8编码否则中文注释到了后面脚本解析和Excel生成环节大概率会出现乱码。这个坑我在4.3节详细讲但源头就在这里导出时就要注意。这些配置在不同版本里菜单位置可能不一样但思路是通用的。拿到SQL文件后建议先用文本编辑器打开看一小段确认里面的注释完整、编码正常再进入解析环节。2.3 不同数据库方言对解析脚本的影响sldd支持多种数据库导出SQL的方言也不一样这个因素在写解析脚本前就要评估好。我这次处理的是MySQLDDL格式相对规整字段行一般是\字段名 varchar(64) NOT NULL DEFAULT COMMENT 备注这种结构表尾有一段ENGINE... COMMENT...。解析起来比较直接。但如果你面对的是Oracle、PostgreSQL或者SQL ServerDDL形态差异会很大。Oracle习惯用NUMBER(10,2)、VARCHAR2(100)注释存在COMMENT ON COLUMN 表名.字段名 IS 备注这种独立语句里而不是字段行尾PostgreSQL用character varying(100)和COMMENT ON COLUMNSQL Server则是[字段名] nvarchar(100)。这意味着解析逻辑要跟着数据库类型走不能拿一套正则硬套所有方言。所以动手写脚本前先确认sldd导出的SQL是哪种数据库风格再决定字段解析规则。如果项目里混合了多种数据库建议每个数据库类型单独写一个解析器或者抽象出一个接口避免后续维护时逻辑纠缠在一起。3. 从DDL到Excel完整实现过程与核心代码3.1 DDL解析表、字段、约束的一次性梳理解析DDL是整个流程里最关键的一步也是我返工最多的地方。一开始图省事用了一堆正则表达式去硬配结果被各种边界情况折磨得不行。后来改用分层解析的思路先把整个SQL文件按CREATE TABLE分割成独立的建表块再逐个块解析表名、字段、主键和表注释。这里给出一个解析MySQL DDL的参考实现核心思路是把表拆成块再从块里抽字段。import re from dataclasses import dataclass, field from typing import List, Optional dataclass class FieldInfo: name: str col_type: str length: str nullable: bool default: Optional[str] comment: str is_primary: bool False dataclass class TableInfo: table_name: str table_comment: str fields: List[FieldInfo] field(default_factorylist) FIELD_RE re.compile( r(?Pname[^])\s r(?Ptype[a-zA-Z0-9_]) r(?:\((?Plength[^)]*)\))? r(?:\sUNSIGNED)? r(?:\sNOT\sNULL)? r(?:\sDEFAULT\s(?PdefaultNULL|[^]*|[\w.]|CURRENT_TIMESTAMP(?:\([^)]*\))?))? r(?:\sCOMMENT\s(?Pcomment(?:[^]|)*))?, re.IGNORECASE, ) def parse_sql_file(sql_path: str) - List[TableInfo]: with open(sql_path, r, encodingutf-8) as f: sql_content f.read() create_blocks re.split( rCREATE\sTABLE\s(?:IF\sNOT\sEXISTS\s)?, sql_content, flagsre.IGNORECASE ) tables [] for block in create_blocks[1:]: table_name_match re.match(r?(\w)?\s*\(, block.strip()) if not table_name_match: continue table_name table_name_match.group(1) table_comment_match re.search( rCOMMENT\s*\s*(?Pcomment(?:[^]|)*), block, re.IGNORECASE ) table_comment ( table_comment_match.group(comment).replace(, ) if table_comment_match else ) fields_body block[block.find(() 1: block.rfind())] primary_match re.search( rPRIMARY\sKEY\s*\((?Pcols[^](?:\s*,\s*[^])*)\), block, re.IGNORECASE, ) primary_cols set() if primary_match: for col in re.findall(r([^]), primary_match.group(cols)): primary_cols.add(col.lower()) table_info TableInfo(table_nametable_name, table_commenttable_comment) lines fields_body.split(\n) for line in lines: line line.strip().rstrip(,) if not line or line.startswith((PRIMARY, KEY, UNIQUE, CONSTRAINT, INDEX)): continue m FIELD_RE.match(line) if not m: continue fname m.group(name) ftype m.group(type) length m.group(length) default m.group(default) if default is not None: default default.strip() comment m.group(comment) or comment comment.replace(, ) table_info.fields.append( FieldInfo( namefname, col_typeftype, lengthlength or , nullableNOT NULL not in line.upper(), defaultdefault, commentcomment, is_primaryfname.lower() in primary_cols, ) ) tables.append(table_info) return tables这个脚本有几个关键点。分割建表块时用了CREATE TABLE关键字避免块之间互相干扰。字段正则里重点处理了DEFAULT和COMMENT的排列组合因为sldd导出的DDL在不同配置下顺序可能不一样。主键单独从块尾找再回填到字段对象里。表注释用COMMENTxxx来匹配注意处理SQL里用转义单引号的情况。这个实现不完美有些极端场景比如字段类型是enum(a,b)或者带ON UPDATE CURRENT_TIMESTAMP的字段可能解析不准。我实际跑的时候遇到这种情况是单独加正则分支处理的或者干脆用sqlparse这类库。但如果你处理的表结构比较规整这套逻辑足够作为起点。3.2 Excel生成版式、样式、列宽与数据格式解析出结构化信息之后下一件事就是把它们写进Excel。这一步的重点不是“能写进去”而是“写出来的表格让业务方愿意用”。我踩过用pandas一把梭的坑——导出的表格能用但很粗糙表头灰扑扑没有任何样式用户拿到手还得自己调半天。后来改用openpyxl把版式细节都放进脚本里。我的设计原则是每个Sheet放一张表Sheet名用“表注释_表名”的格式第一行加粗深色底纹作为列头冻结首行开启筛选主键字段整行浅黄色标记。列的顺序按“序号、字段名、字段说明、数据类型、长度、允许空、默认值、主键、备注”来排。字段说明之所以放在第三列而不是第一列是因为业务方最关心的是“这个字段干嘛的”字段名反而是开发人员才盯的。关键代码如下。import os import re from openpyxl import Workbook from openpyxl.styles import Font, PatternFill, Alignment, Border, Side from openpyxl.utils import get_column_letter HEADER_FILL PatternFill(start_colorD9E1F2, end_colorD9E1F2, fill_typesolid) PRIMARY_FILL PatternFill(start_colorFFF2CC, end_colorFFF2CC, fill_typesolid) HEADER_FONT Font(boldTrue, size11) THIN_BORDER Border( leftSide(stylethin, colorD0D0D0), rightSide(stylethin, colorD0D0D0), topSide(stylethin, colorD0D0D0), bottomSide(stylethin, colorD0D0D0), ) HEADERS [序号, 字段名, 字段说明, 数据类型, 长度, 允许空, 默认值, 主键, 备注] def safe_sheet_name(name: str) - str: name re.sub(r[\\/*?:\[\]], _, name) return name[:31] or Sheet def calc_width(value: str) - int: if not value: return 10 width sum(2 if ord(ch) 127 else 1 for ch in str(value)) return min(max(width 4, 10), 50) def build_excel(tables, output_path: str): wb Workbook() wb.remove(wb.active) for table in tables: sheet_name safe_sheet_name(f{table.table_comment}_{table.table_name}) ws wb.create_sheet(titlesheet_name) ws.append(HEADERS) for col_idx, header in enumerate(HEADERS, start1): cell ws.cell(row1, columncol_idx) cell.fill HEADER_FILL cell.font HEADER_FONT cell.alignment Alignment(horizontalcenter, verticalcenter) cell.border THIN_BORDER for row_idx, f in enumerate(table.fields, start2): row_data [ row_idx - 1, f.name, f.comment, f.col_type, f.length, 是 if f.nullable else 否, f.default if f.default is not None else , PK if f.is_primary else , , ] ws.append(row_data) for col_idx, value in enumerate(row_data, start1): cell ws.cell(rowrow_idx, columncol_idx) cell.border THIN_BORDER if col_idx 1: cell.alignment Alignment(horizontalcenter, verticalcenter) elif col_idx 3: cell.alignment Alignment(horizontalleft, verticalcenter, wrap_textTrue) else: cell.alignment Alignment(horizontalcenter, verticalcenter) if f.is_primary: cell.fill PRIMARY_FILL for col_idx, header in enumerate(HEADERS, start1): max_width 0 for row in ws.iter_rows(min_colcol_idx, max_colcol_idx, min_row1, max_rowws.max_row): for cell in row: max_width max(max_width, calc_width(cell.value)) ws.column_dimensions[get_column_letter(col_idx)].width max_width ws.freeze_panes A2 ws.auto_filter.ref ws.dimensions os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_okTrue) wb.save(output_path) return output_path几个设计细节说明一下。Sheet名用了“表注释_表名”因为业务方看到“用户信息表_user_info”比看“user_info”直观得多。但Excel的Sheet名限制31个字符所以加了safe_sheet_name做清洗和截断。如果注释特别长导致截断后不同表重名可以在脚本里检测重名并追加序号这个我实际处理过问题不大。列宽我根据内容动态计算中文字符按宽度2、英文字符按宽度1估算再限个上下限。字段说明列允许自动换行长注释不会把行撑得特别高。主键行用浅黄色高亮业务方扫一眼就能定位每张表的核心字段。冻结首行和自动筛选属于标配没有这两项的Excel在业务方手里基本等于半成品。3.3 校验导出结果宁可多写检查不可上线翻车脚本跑通之后很多人会直接打开Excel看一眼觉得差不多就交付了。但表多了之后肉眼校验根本看不过来尤其是字段数量、注释完整性、主键标识这些细节一旦出错业务方会在评审会上直接挑出来非常被动。我后来在流程里加了一个校验环节脚本生成完Excel之后自动做三件事。第一对比表数量。解析出的表数量要和sldd里选中的表数量一致少了任何一张都是大问题。第二对比字段数量。从DDL解析出的字段数和Excel里每个Sheet的最大行数减1做比对不一致说明生成环节有遗漏。第三抽查字段注释。检查有没有字段的comment为空或者comment里出现异常符号。from openpyxl import load_workbook def validate_excel(output_path: str, tables) - List[str]: problems [] wb load_workbook(output_path) for t in tables: sheet_name safe_sheet_name(f{t.table_comment}_{t.table_name}) if sheet_name not in wb.sheetnames: problems.append(f表 {t.table_name} 缺少Sheet: {sheet_name}) continue ws wb[sheet_name] field_count ws.max_row - 1 if field_count ! len(t.fields): problems.append( f表 {t.table_name} 字段数不一致期望 {len(t.fields)}实际 {field_count} ) empty_comment_cols [] for row in ws.iter_rows(min_row2, min_col3, max_col3): cell row[0] if not cell.value or not str(cell.value).strip(): empty_comment_cols.append(cell.row) if empty_comment_cols: problems.append( f表 {t.table_name} 存在空注释字段行号: {empty_comment_cols[:10]} ) return problems这个校验脚本虽然简单但在后续反复导出的时候特别管用。数据库模型会有调整sldd里的表结构会变如果哪次导出的SQL文件有问题校验脚本会第一时间拦住不会让一个规格不对的Excel流到业务方手里。4. 导出Excel后最容易踩的格式坑逐个排查给你看4.1 科学计数法身份证号、长数字、默认值都中过招很多人第一次把字典导出到Excel打开一看就懵了有些默认值字段明明写的是1234567890123结果单元格里变成了1.23457E12后几位全成了0。业务方要是拿着这种Excel去核对主数据基本等于报废。这个问题的根源在于Excel的单元格类型是自动推断的超过一定长度的数字会被识别成科学计数法。我遇到过的场景包括身份证号、订单号、长整型默认值。sldd的DDL里这些值可能是纯数字字符串但Excel不认。解决方法有两个层面。一个是从源头避免openpyxl写入时把可能的数字字符串统一设置成文本格式让Excel把它当字符串处理而不是数字。具体可以在写单元格时设置number_format 。cell.number_format 另一个是事后修复如果Excel已经生成全选那列菜单里选“数据-分列-文本”或者设置单元格格式为“文本”后重新粘贴一遍。但能自动化的事就不要手工做直接在脚本里对所有非数值型字段强制文本格式是最省心的。之前在排查一个从Oracle导出的身份证信息变成科学计数法的问题时本质也是一样的。数据本身没错错在读和写的环节把它当成数字了。处理方式就是不依赖Excel自动识别明确告诉它“这是文本”。4.2 长注释被截断根因在解析逻辑而不是Excel这个问题排查起来比较隐蔽。现象是导出的Excel里某些字段的中文注释只剩前半截后半截不翼而飞。如果直接怀疑Excel你会发现Excel单元格本身可以容纳很多字符根本不存在“截断”的能力。问题出在DDL解析环节。我最初解析字段注释用的正则是COMMENT (.?)这是非贪婪匹配它会匹配到字段行注释的第一个单引号就停下来。正常情况下没问题但如果注释里面包含了单引号比如“用户昵称”或者注释非常长、中间有换行正则就会在中途断掉注释自然就少了一段。排查过程可以这样复现先用文本编辑器打开sldd导出的SQL文件找到对应字段的原始DDL确认注释是完整的。然后跑Python解析把解析出来的comment打出来对比就能看出是解析截断。我当时的解决方式是把正则在COMMENT段改成匹配连续非单引号字符或者双单引号转义的形式COMMENT (?:[^]|)*然后取中间内容再反转义。如果你不想处理这些边界情况直接引入sqlparse库来做SQL语法解析会更稳。这个坑给我最大的教训是解析SQL时不要迷信正则的“看起来差不多”。一旦数据量上来各种边界情况都会出现宁可多花半小时把解析规则写严谨也不要在交付前被业务方发现注释不完整。4.3 中文乱码编码问题在不同环节的“传染链”乱码问题一旦出现影响面特别大因为整张Excel里的中文注释会全部变成乱码或者问号基本等于不能用。而且乱码的根源可能出现在多个环节排查起来很烦。我遇到过的情况主要有三种。第一种是sldd导出SQL时用了非UTF-8编码文件本身就是GBK或者其他编码。用文本编辑器打开看着正常因为编辑器会自动识别但脚本读取时如果按UTF-8解码就报编码错误或者静默产生乱码。解决办法是读取文件时做编码探测常见编码列表[utf-8, gb18030, utf-8-sig]逐个尝试。def read_sql_with_encoding(path: str) - str: encodings [utf-8-sig, utf-8, gb18030] for enc in encodings: try: with open(path, r, encodingenc) as f: return f.read() except UnicodeDecodeError: continue raise RuntimeError(f无法识别文件编码: {path})第二种是脚本处理过程中字符串的编码转换出错比如在Windows控制台环境时默认GBK编码日志和交互环境互相干扰。建议在脚本入口显式统一编码环境或者尽量用UTF-8输出。第三种是Excel本身没问题但列宽太窄导致中文字符显示成“###”这个不算乱码调列宽就行。虽然这个不算严格意义上的乱码但业务方会一样把它当成bug反馈过来所以也列进了排查清单。4.4 表多了就卡死大字典Excel的性能优化当数据库比较大比如几十张表、上千个字段的时候Excel文件容易变得又大又卡。我碰到过一次生成出的Excel在同事电脑上打开要转圈十几秒滚动的时候一卡一卡直接被吐槽。排查下来主要有几个原因。首先是合并单元格。很多人喜欢把表头做得很花哨几行合并、跨列合并Excel打开时合并单元格的渲染开销很大。数据越多越明显。解决方式是尽量少用合并我设计的版式里第一行就是列头没有合并且每个Sheet的第一行保持一致处理起来最干净。其次是条件格式。条件格式是“按需计算”的字段数量多的时候每次重算都会拖慢性能。我的方案里只用普通单元格底色来标主键不用条件格式规则性能好很多。再就是自动筛选和冻结窗格。这两个功能虽然是刚需但如果同时叠加再加上几百行数据打开速度也会受影响。我的做法是保留这两个功能但不再叠加其他东西。如果单表数据量超过几千行建议再拆Sheet或者拆文件。最后是文件体积。如果Excel里塞了大量无意义的样式或者空行文件会膨胀。生成后可以检查一下文件大小超过5MB基本就要想想是不是哪里有问题。5. 从一次导出到自动化流水线5.1 用配置文件约束每次导出的边界第一次手工跑通脚本后我觉得这事不能只干一次因为数据字典是活的东西表结构一调整就要重新导出。所以很快就想着把流程包装成一条可重复使用的“小流水线”。我做的第一件事是把脚本参数外置成配置文件避免每次改代码。用一个YAML或者JSON文件管起来内容包括SQL文件路径、Excel输出路径、需要排除的表、是否导出索引、Sheet命名风格等等。input: sql_file: ./schema.sql output: excel_file: ./数据字典_20250601.xlsx tables: include: [] # 空表示全部 exclude: - tmp_% - audit_log% options: include_index: true include_foreign_key: false sheet_name_style: comment_table # comment_table 或 table_only脚本入口统一接收配置文件路径再读配置决定行为。这样每次导出只需要更新SQL文件和输出文件名不用改动脚本本身。表排除规则我用的是通配符匹配比如临时表、日志表这类不进入正式数据字典的表在配置里一写就过滤掉了省得每次导出后还要手动删Sheet。5.2 数据库直连方案没有sldd也能一键出字典自动化到一定程度后你会意识到一个问题sldd里的模型和线上数据库可能不同步。如果团队里有人直接在数据库里改了表结构没有回头更新sldd模型那从sldd导出的字典就会漏掉这些变更。所以我又加了一个备用入口直接连接数据库从系统的元数据表里抽取字典信息。以MySQL为例information_schema.COLUMNS表里有所有字段的信息一条SQL就能把库里的建表元数据拉出来再套用同一套Excel生成逻辑。SELECT TABLE_NAME, COLUMN_NAME, ORDINAL_POSITION, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_KEY, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your_database_name ORDER BY TABLE_NAME, ORDINAL_POSITION;拿到这个查询结果之后再用pandas或者直接遍历组装成同样的结构化数据喂给之前的build_excel函数就行。表注释从information_schema.TABLES里取。这条方案的好处是数据永远跟线上库一致坏处是它只能反映“物理表”的现状无法还原sldd模型里的逻辑设计、外键关系图这些“设计意图”。所以我的建议是两条腿走路模型同步及时的项目用sldd导出SQL模型和库不一致的用数据库直连救急。两种方式的产出都是同一个Excel格式对下游无感。5.3 定时任务与版本归档到了这一步自动化已经完成80%了最后剩下的就是“定时自动跑”。数据字典不是一次性交付物我这边约定的是每周生成一版留档备查。这个需求用Linux的cron或者Windows的计划任务就能搞定。我用的是Linux环境cron表达式大概是这样0 18 * * 5 cd /opt/dict_export /usr/bin/python3 build_dict.py -c config.yaml logs/dict_export.log 21每周五下午6点生成一版文件命名带日期归档到固定目录。要注意的是定时任务跑Python时环境变量可能和手动执行不一样容易出现“找不到模块”“编码不对”一类的诡异问题。我的经验是在cron里把Python解释器路径写全并且在脚本内部用之前写的编码探测函数不要依赖系统默认编码。归档目录的命名规则我建议做成数据字典_YYYYMMDD.xlsx这样后续查找历史版本很方便。如果团队有数据资产平台也可以把这套脚本生成的Excel挂到平台上按周更新彻底摆脱手工操作。6. 这套流程用下来的边界和最终选型建议6.1 实测效果从半小时到两分钟整套流程跑通之后我最直观的感受是导出数据字典这件事从“每次都要重新折腾”变成了“两分钟搞定”。之前手工处理一份覆盖几十张表、上千字段的字典从sldd导出、调整格式、校正注释、整理成业务方能看的Excel少说半小时多则一两个小时而且每次都会有那么几个格式问题要修。现在流程变成sldd里更新模型并导出SQL然后跑一条命令自动生成带样式的Excel。校验脚本还会自动检查表数量、字段数量和空注释基本上不需要人工核对。整体时间压缩到两分钟左右而且质量比手工操作稳定太多。这套流程还带来一个隐形收益每次评审时如果业务方提出要调整格式比如增加一列“所属模块”或者把“允许空”改成“必填”的布尔语义我只需要改脚本里的表头配置再重新跑一次即可。所有历史版本都能重新生成不存在“改了一版其他版没同步”的问题。6.2 别指望Excel包打天下不适合的场景虽说Excel是通用格式但也不能无限拔高它的作用。有几个场景我是建议别硬用Excel的。第一个是实时在线查询。如果团队日常需要快速查字段含义、看表结构不如直接用数据库客户端或者内部的知识库平台Excel文件每次都要下载打开效率太低。第二个是多人同时编辑。Excel的协作能力再强也比不上在线表格或者专业的数据建模协同工具。多人同时批注、修改字段说明时Excel文件很容易出现版本冲突。第三个是字段血缘和依赖关系。Excel只能展示字段本身的一行信息表达不了“这个字段从哪来、被哪个下游任务引用”这种数据血缘关系这类需求要找专门的数据治理工具。我自己遇到最多的是第二种场景。业务方拿回一份Excel标注了几个字段的修改意见然后发回来。这时如果没做好版本管理很容易出现“你改你的我改我的”的混乱局面。我的处理方式是业务方的反馈意见统一收到一个意见收集表里我再统一改sldd模型并重新生成字典而不是直接编辑已交付的Excel。这样源头模型永远是准的下游产物只是模型的一个投影。6.3 个人建议把注释当代码一样维护最后聊一点工作中的体会。这整套导出流程再自动化也只是把数据字典的“呈现层”问题解决掉了。更关键的是源头——sldd模型里的注释质量。注释写得好不好直接决定导出的Excel有没有价值。见过太多项目的字段注释是空的或者写的是备注、名称、状态这类说了等于没说的内容。这种注释导出去业务方根本没法用。所以我在团队里定的一个规范是每个字段必须写注释注释里要体现业务含义尽量包含口径说明比如“订单状态0待支付1已支付2已取消”而不是简单写“状态”。这个规范执行得越好后面所有依赖数据字典的环节就越轻松。再一个体会是数据字典这类“看起来不起眼”的交付物恰恰是团队协作里最容易出现信息损耗的环节。模型在sldd里业务方在Excel上开发在代码里三方的信息如果不一致迟早出问题。把从模型到Excel的转换链路脚本化、标准化本质上是把这种损耗降到了最低。这也是这篇文章真正想表达的东西——真正解决问题的不是某一次导出操作而是把这件小事当成一个工程来对待。另外补充一个环境层面的小技巧。如果日常是在Windows上跑脚本注意设置PYTHONIOENCODINGutf-8不然控制台输出中文注释时经常报UnicodeEncodeError。这个坑很小但第一次遇到会觉得莫名其妙顺手记录一下。
