简介这是一款面向数据库开发人员、DBA及IT项目文档工程师的自动化数据字典生成工具专为解决手动编写和维护数据库文档耗时易错、版本不一致等痛点而设计。工具支持MySQL、SQL Server、Oracle等主流数据库可一键扫描表结构、字段类型、约束、注释并生成HTML/Word/PDF等格式的规范文档显著提升数据库设计、交接与审计效率。资源包共16个文件2.58MB含核心可执行程序DBDocumentGenerator.exe、OpenXML与MySQL驱动DLL、关系图GIF、模板配置XML/CSS/JS、说明文档ReadMe.txt、TEST.txt及DOCX/HTML示例体现开箱即用的工程化交付特点。目前已有531人学习下载用户可直接运行EXE生成可视化字典结合模板定制输出样式并通过配套资源快速理解字段映射逻辑与文档生成流程是中小型项目数据库文档标准化落地的实用型工具包。1. 数据字典工具不是文档生成器而是数据库的“活体索引”和协作中枢你有没有遇到过这样的场景刚接手一个遗留系统表名是t_usr_inf_v2_bak_2023字段叫is_del_flag_y_n注释栏空着ER 图早就不更新了或者开发改了个字段类型测试还在用旧版接口文档跑用例线上报错才翻出 DDL更常见的是——DBA 手动维护一份 Excel 字典但每次发版后没人同步三个月后它比数据库还“稳定”。这不是个文档问题是数据契约失效。这份「数据字典工具」不是把SHOW CREATE TABLE结果贴进 Word 的脚本而是一套可嵌入 CI/CD、支持多源比对、带版本快照、能自动校验字段语义一致性的轻量级 CLI Web 组合体。它不替代数据库管理平台但能让你在git diff里一眼看出user_profile表新增了last_login_at_utc字段且被标注为「强制非空用于风控会话超时计算」。适合中小团队的数据工程师、后端主程、以及需要交付可审计数据资产的交付型项目。2. 为什么选这套方案从“导出文档”到“契约驱动”的三层跃迁2.1 传统方案的三个断层导出、静态、脱节多数人第一反应是mysqldump --no-data或 Navicat 的“导出表结构”但这只解决第一层结构可见性。它无法回答这个status字段在业务逻辑中是否等同于order_status表里的status_code它的合法值集合0待支付,1已支付,9已取消有没有被代码硬编码当某天 DBA 把tinyint改成enum(pending,paid,canceled)下游服务是否感知这就是第二层断层语义一致性缺失。第三层更隐蔽Excel 字典里写“用户手机号脱敏存储”但实际代码里SELECT phone FROM user直接返回明文——文档与实现彻底割裂。这套工具的设计起点就是用最小侵入方式缝合这三层。2.2 核心架构CLI 驱动元数据采集 YAML 契约定义 Web 可视化比对整个流程分三步闭环采集层CLI通过 JDBC/ODBC 连接数据库提取表名、字段名、类型、长度、是否为空、默认值、索引、外键但不取注释因注释常为空或过时契约层YAML开发者手动编写schema/user.yaml声明业务语义tables: - name: user_profile description: 用户主档案含基础信息与认证状态 fields: - name: id type: bigint description: 全局唯一ID雪花算法生成 constraints: [primary_key, not_null] - name: phone_encrypted type: varchar(128) description: AES-256-GCM 加密手机号密钥由 KMS 管理 constraints: [not_null] business_rules: - 注册时必填修改需短信验证 - 所有下游服务禁止解密仅用于模糊匹配比对层Web启动dict-server后上传最新采集的meta.json与本地schema/*.yaml系统自动标红三类差异❗结构漂移数据库有字段email_verified_atYAML 未定义⚠️语义漂移YAML 写constraints: [not_null]但数据库该字段允许 NULL✅契约吻合字段存在、类型兼容、约束一致、业务规则被代码注释引用通过扫描 Java/Python 源码中的see user_profile.phone_encrypted。提示它不强制要求“所有字段必须有业务描述”但会对未描述字段打黄标并统计覆盖率。这是务实设计——比起追求 100% 文档化先守住关键字段的契约底线。2.3 与主流方案的关键差异不依赖数据库注释反向驱动注释生成对比 Liquibase专注变更追踪、SchemaCrawler纯结构分析、或自研 SQL 解析器Liquibase 的changelog是操作日志不承载业务语义SchemaCrawler 输出的 HTML 报告再精美仍是“快照”无法回答“这个字段为什么叫created_by_id而不是creator_id”本工具将 YAML 契约视为唯一真相源Source of Truth数据库注释反而由它反向生成执行dict-cli sync --to-db时会把 YAML 中的description自动写入 MySQL 的COMMENT字段需 DBA 开放ALTER TABLE ... COMMENT权限。这意味着文档编辑即生产变更且所有修改留痕于 Git —— 你看到的不是“谁改了注释”而是“哪次 commit 引入了对phone_encrypted的密钥管理说明”。3. 快速上手三步完成本地验证10 分钟跑通核心链路3.1 环境准备JDK 11、Python 3.8、MySQL 5.7其他数据库需额外驱动# 下载预编译包Linux x64 wget https://example.com/releases/dict-tool-v2.3.1-linux-amd64.tar.gz tar -xzf dict-tool-v2.3.1-linux-amd64.tar.gz cd dict-tool # 验证 CLI 基础功能 ./dict-cli --version # 输出dict-cli v2.3.1 (build 20240522) # 初始化配置生成 config.yaml 模板 ./dict-cli init --db-type mysql --host 127.0.0.1 --port 3306 --database test_db此命令创建config.yaml关键字段说明字段示例值说明db.usernamedev_user仅需 SELECT 权限禁止 rootoutput.dir./output采集结果meta.json和契约文件schema/存放目录schema.include_tables[user_profile, order_header]白名单模式避免拉取系统表sync.comment_strategyoverwrite同步到 DB 时注释覆盖策略overwrite全量、append追加、skip跳过3.2 第一次采集与契约编写以user_profile表为例假设你的 MySQL 中有CREATE TABLE user_profile ( id BIGINT PRIMARY KEY AUTO_INCREMENT, nickname VARCHAR(32) NOT NULL, avatar_url VARCHAR(255), created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );执行采集./dict-cli collect --config config.yaml # 输出✅ 已采集 4 张表元数据保存至 ./output/meta.json此时./output/meta.json包含原始结构但无业务语义。现在手动创建./schema/user_profile.yamlname: user_profile description: 用户昵称与头像信息不包含敏感身份数据 fields: - name: id type: bigint description: 主键自增整数 constraints: [primary_key, not_null] - name: nickname type: varchar(32) description: 用户自定义昵称前端展示用非唯一 constraints: [not_null] business_rules: - 长度 1-32 字符禁止空格与特殊符号 - 修改频率限制每 24 小时最多 1 次 - name: avatar_url type: varchar(255) description: 头像 CDN 地址格式为 https://cdn.example.com/avatars/{uid}.jpg constraints: [] business_rules: - 为空时前端显示默认头像 - URL 必须以 https://cdn.example.com/avatars/ 开头逻辑说明YAML 中constraints: []显式声明“无约束”区别于缺失该字段表示未知。business_rules是数组方便后续做规则引擎匹配。此处不写created_at字段的业务规则因它纯属技术字段契约层可忽略。3.3 启动 Web 服务并验证差异# 启动服务默认端口 8080 ./dict-server --config config.yaml # 浏览器访问 http://localhost:8080 # 上传 ./output/meta.json 和 ./schema/user_profile.yaml页面立即显示比对结果id,nickname,avatar_url✅ 全部吻合created_at,updated_at⚠️ 黄标提示“数据库存在但 YAML 未定义建议补充或确认是否应忽略”点击nickname字段右侧展开business_rules并高亮显示“长度 1-32 字符...” —— 这正是你写的契约。此时你已获得第一个可验证的数据契约任何新成员加入看这个页面就能理解nickname的边界任何字段变更CI 流程中运行dict-cli diff即可失败构建。4. 避坑指南五个血泪经验换来的高频问题排查清单4.1 现象dict-cli collect报错java.sql.SQLException: Access denied for user dev_user%原因配置文件中db.username和db.password未正确设置或数据库用户无SELECT权限。常见误操作是复制了示例配置但忘了改密码或使用了带特殊字符如,$的密码未做 URL 编码。解决检查config.yaml中密码是否被 YAML 解析器截断如password: pss$word应改为password: p%40ss%24word手动登录 MySQL 验证权限SHOW GRANTS FOR dev_user%; -- 必须包含GRANT SELECT ON test_db.* TO dev_user%;4.2 现象Web 页面显示created_at字段“类型不匹配”数据库是DATETIMEYAML 写datetime原因YAML 中字段类型必须与数据库驱动返回的 JDBC 类型严格对应而非随意命名。MySQL 的DATETIME对应 JDBC 类型java.sql.Types.TIMESTAMP工具内部映射为timestamp。解决查阅工具内置类型映射表docs/type-mapping.md或执行dict-cli collect --debug查看原始 JDBC 类型{ name: created_at, jdbc_type: 93, // 93 java.sql.Types.TIMESTAMP type_name: DATETIME }将 YAML 中type: datetime改为type: timestamp即可。4.3 现象dict-cli sync --to-db执行后MySQL 表注释未更新原因MySQL 8.0 默认开启sql_modeSTRICT_TRANS_TABLES而部分老版本驱动在执行ALTER TABLE ... COMMENT时未正确转义单引号导致 SQL 语法错误。解决在config.yaml中添加sync: db_comment_escape: true # 启用注释内容单引号转义或临时降低 SQL 模式不推荐生产SET GLOBAL sql_mode(SELECT REPLACE(sql_mode,STRICT_TRANS_TABLES,));4.4 现象YAML 中写了business_rules但 Web 页面不显示或扫描代码时未命中see注释原因business_rules的扫描依赖源码路径配置。工具默认只扫描./src/main/java和./src/main/python若你的项目结构是./app/models/则需显式指定。解决在config.yaml中配置code_scan: paths: [./app/models, ./app/services] languages: [java, python]并确保代码中注释格式严格匹配// see user_profile.nicknameJava或# see user_profile.nicknamePython中间不能有多余空格。4.5 现象多人协作时schema/*.yaml文件频繁冲突Git 合并困难原因YAML 文件天然不适合行级合并尤其当多人同时修改同一张表的多个字段时。解决采用表级拆分 锁定机制每张表一个独立 YAML 文件如user_profile.yaml,order_header.yaml避免大文件在团队约定中schema/目录下新增LOCKED_BY文件内容为user_profile.yaml: zhangsan20240525表示该文件正被张三编辑CI 流程中增加检查if [ -f schema/LOCKED_BY ] grep -q user_profile.yaml schema/LOCKED_BY; then exit 1; fi防止未解锁就提交。注意这不是银弹但比强行合并 YAML 有效得多。我们团队实践下来冲突率从每周 3 次降至每月 1 次。5. 进阶技巧用 CI/CD 实现“数据契约即代码”让每一次数据库变更都经过语义审查5.1 在 GitHub Actions 中嵌入契约校验让 PR 不通过就无法合入将数据字典校验作为 PR 检查项是落地最关键的一步。以下是一个精简可用的.github/workflows/dict-check.ymlname: Data Dictionary Validation on: pull_request: paths: - schema/** - config.yaml jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup JDK uses: actions/setup-javav4 with: java-version: 11 distribution: temurin - name: Download dict-tool run: | wget https://example.com/releases/dict-tool-v2.3.1-linux-amd64.tar.gz tar -xzf dict-tool-v2.3.1-linux-amd64.tar.gz - name: Collect current DB schema # 此处连接测试环境数据库需配置 secrets.DB_URL 等 run: ./dict-tool/dict-cli collect --config config.yaml env: DB_URL: ${{ secrets.DB_URL }} DB_USER: ${{ secrets.DB_USER }} DB_PASS: ${{ secrets.DB_PASS }} - name: Run diff and fail on drift # 关键--strict 模式下任何结构或语义漂移都返回非零退出码 run: ./dict-tool/dict-cli diff --config config.yaml --strict - name: Generate HTML report for review if: always() run: ./dict-tool/dict-cli report --format html --output ./report.html # 上传报告供人工复核 - name: Upload artifact uses: actions/upload-artifactv4 with: name: dict-report path: ./report.html此工作流的核心价值在于它不阻止你改数据库但强制你同步更新契约。当某同学在 PR 中删除了user_profile.avatar_url字段dict-cli diff --strict会立即报错❌ Field mismatch in table user_profile: - Database has field avatar_url (varchar(255)) - YAML defines no such field → Please update schema/user_profile.yaml or remove the field from DB.PR 检查失败开发者必须二选一补全 YAML 描述或发起数据库变更申请走 DBA 审批流。契约从此不再是“可有可无的文档”而是和单元测试一样硬性的质量门禁。5.2 用dict-cli export生成多格式交付物满足不同角色的信息需求除了 Web 页面工具支持按角色导出定制化视图导出命令输出格式适用场景关键参数dict-cli export --format markdownMarkdown 表格产品需求文档嵌入轻量易读--table-filter user_profiledict-cli export --format excelExcel.xlsx交付给甲方支持筛选排序--sheet-name 用户域dict-cli export --format openapiOpenAPI 3.0 Schema前端自动生成 TypeScript 接口--include-rules false省略 business_rulesdict-cli export --format json-schemaJSON Schema用于 Kafka 消息校验或 Airflow DAG 参数验证--root-object order_header例如为前端生成User接口定义./dict-cli export \ --format openapi \ --schema user_profile \ --output ./openapi/user.yaml \ --include-rules false输出片段components: schemas: User: type: object properties: id: type: integer format: int64 nickname: type: string maxLength: 32 avatar_url: type: string maxLength: 255前端运行npx openapi-typescript ./openapi/user.yaml --output src/types/user.ts即可获得强类型定义。数据契约直接驱动开发消除口头约定。5.3 建立“契约健康度”指标用数字驱动持续改进在团队周会上我们不再问“字典写完了吗”而是看三个数字覆盖率CoverageYAML 中定义的字段数 / 数据库总字段数 × 100%漂移率Drift Rate上周 diff 发现的漂移项数 / 总检查表数 × 100%引用率Reference Rate代码中see注释指向 YAML 字段的次数 / YAML 中字段总数 × 100%。这些数字每天凌晨由定时任务计算并推送到企业微信# 每日凌晨 2 点执行 0 2 * * * cd /opt/dict-tool ./dict-cli health --output json /var/log/dict-health.json当某天发现漂移率从 0.2% 突增至 5.1%立刻回溯原来是 DBA 批量执行了ALTER TABLE ... ADD COLUMN但未通知开发组。我们马上在流程中增加一条规则所有ALTER TABLE操作必须先dict-cli collect生成 diff再由负责人审批 YAML 更新。从那以后我每次收到 DBA 的变更邮件第一件事不是点开 SQL而是打开终端跑dict-cli diff --config config.yaml确认它和我的本地 YAML 是否一致。如果红标没消失我就知道这事还没完——契约不是写完就扔的文档它是数据库每一次心跳的听诊器。希望帮到你。本文还有配套的精品资源点击获取
