共计 3128 个字符，预计需要花费 8 分钟才能阅读完成。
背景
在软件行业，API 文档的自动化有着十分宽泛而成熟的计划，但数据库模型文档的自动化却还是一片蓝海，我曾在网上搜查好久，但并没有找到一款能同时满足我以下需要点的产品
- 自动化：基于数据库主动生成文档
- 版本化：文档历史版本回溯，版本差别比照
- 团队化：适应不同团队构造，多样性性能为跨团队合作赋能
- 个性化：给予使用者肯定的文档定制能力
鉴于此，我利用业余的工夫开发并开源了 这个我的项目，它专一于数据库文档的治理，外围能力就是下面提到的自动化、版本化、团队化和个性化四点。
如题，如果有更好的产品欢送留言指出，给我一个奋斗的指标，当然这里也别忘点赞珍藏零打碎敲！
我的项目地址：https://github.com/vran-dev/d…
文档地址：https://doc.databasir.com
问题
在进入正题之前，我想先聊一聊在数据库文档保护这个细分场景下，咱们平时遇到的一些问题。
一、没有文档
这是最广泛的一个问题，没有人会否定文档对一个团队的价值，但文档的保护老本也常常让人望而生畏
二、工夫无限，这次就不写文档了
在人力、工夫等资源都无限的状况下咱们通常会临时放弃文档的保护而优先实现业务指标（这本无可非议），长此以往就会导致文档内容与业务模型之间的差别越来越大，即文档失真了。
三、百家齐放，格局规范不对立
每个人对文档的格局规范都有本人的想法，只是团队外部消化的话，大家的容忍度还是很高的，如果波及跨团队合作的话，一个对立的格局规范能进步内容品质的最低上限。
四、失忆症，遗记补充文档
模型的变更 80% 的场景都是增量变动，比方加个字段、加一张表等，加了字段和表当前如果忘了更新文档就会造成后面提到的文档失真，但这非刻意为之，更相似于失忆症，根本原因与第二点不同。
事实中的问题远不止这些，但咱们能够看看 Databasir 面对这些场景给出的答案，上面就进入 Show time 吧。
自动化，文档的事儿你不必操心
Databasir 基于 JDBC 实现了对数据库表、列、索引、外键等构造的解析，通过解析后的元数据再主动生成标准化的文档内容，从而代替了人工输入文档这种传统形式，节俭人力的同时又升高了错误率。
目前 Databasir 生成的文档内容蕴含以下信息
- 表信息
- 列信息
- 索引信息
- 外键信息
- 触发器信息（仅 Mysql 反对）
文档页面的布局采纳了经典的两栏布局，左侧显示所有的表信息，右侧显示文档的具体内容，如下图所示
到这儿还算不上自动化，只能算是半自动化，因为每次模型构造有变更的话还须要手动再同步一下，如果忘了同步就会造成后面提到的文档失真问题。
为了齐全的自动化，Databasir 提供了定时主动同步机制，用户能够通过 cron 表达式设置同步工夫。
下图展现了定时同步的配置页面
零碎会依据配置的工夫定时查看模型是否有变更，如果有变更的话就会更新并生成一个新的文档版本，并通过邮件的模式将变更内容告诉到相干方。
除了规范的文档内容以外，Databasir 还反对 UML 格局文档生成，如果业务模型有应用到外键，那 UML 之间还能主动依据外键关系生成关联箭头。
版本化，内容变更高深莫测
文档版本化能够让咱们将文档轻松的回溯到任意指定存档点，在 Databasir 中版本号目前是一个递增的数字，数字越大代表版本越新。
在同步文档时检测到模型有变更才会创立新的版本号，这里的检测应用到了自研的 DIFF 引擎，目前反对以下内容的变更检测
- 数据库信息，比方版本号、产品切换
- 表信息，基于名称比对其余字段的变更，比方正文变更
- 列信息，基于名称比对其余字段的变更，比方类型变更，正文变更
- 索引信息，基于名称比对其余字段的变更，比方关联列变更
- 触发器信息，基于名称比对其余字段的变更
- 外键信息，基于名称比对其余字段的变更，比方关联列变更
下图展现了版本的切换性能
得益于自研的 DIFF 引擎，Databasir 的文档内容能够实现任意版本的差别比照。
在文档页面启用 显示版本差别 开关，而后抉择要比照的旧版本
再看一眼上图，文档内容通过三个高亮色彩来辨别差别类型
- 绿色：示意新增的内容
- 红色：示意被删除的内容
- 黄色：示意被批改的内容
比方下图我抉择了一个版本号为 18 的内容与以后版本做比照，零碎提醒有以下变更内容
- dept_emp 表被批改
- document_description 被批改
- oauth_app 是新增的表
表具体的批改内容，能够在表内容展现地位查看，如下图就展现了 document_description 的具体变更内容
留神黄色的 content 字段由两行组成，其中高亮黄色标识是以后版本的信息，灰色的是旧版本的信息。
团队化，该有的都有了
既然是面向团队的文档治理产品，那么天然就得思考团队通常须要的性能
- 权限
- 合作
- 系统集成
- 审计
先说权限，Databasir 的根本理念是 凋谢，即所有非法的用户都应该有权限查看团队的文档，这样做能够保障信息的价值最大化，防止孤岛效应。
为此，在 Databasir 中将用户分为四种角色
- 普通用户：即能登录零碎的用户，能查看所有分组和所有文档
- 组员：某个分组的一般成员，领有所属分组的所有读权限，局部写权限
- 组长：分组的负责人，领有所属分组的所有权限
- 系统管理员：领有零碎最高权限
而在合作方面，文档内容反对针对表、列、索引进行跨团队的探讨
系统集成方面，Databasir 反对 Github / Gitlab 的 OAuth2 登录配置，仅需简略的配置即可
操作审计方面，Databasir 反对残缺的系统日志查看
个性化，20% 的需要也满足
程序员对性能的要求是最为挑剔的，既要简略又不能简单，在这方面 Databasir 只管不能做到 100% 称心，那也是为这 20% 的需要付出了 80% 的致力。
第一个个性化的能力就是数据库类型的扩大。
Databasir 为 Mysql 和 Postgresql 两款数据库提供了开箱即用的配置，但这并不代表其余数据库就不能用了，实践上 Databasir 是反对所有领有 JDBC 驱动的数据库类型的，比方常见的
- sqlserver
- oracle
- h2
- …
扩大它们只须要简略的图形化配置即可，如下图所示
用户能够在 Maven 仓库找到对应的数据库 JDBC 驱动地址填进表单，Databasir 负责下载并动静加载驱动去连贯数据库。
留神哦，因为某些家喻户晓的起因，驱动的下载地址请尽量抉择国内的公共镜像仓库，比方阿里云或企业自建的私库。
除了数据库的扩大外，Databasir 也致力反对为文档内容进行自定义，比方文档内容中的表格头默认都是英文字段显示，如下
这些你都能够通过模板进行编辑，下图就展现了将表头的英文替换成了中文，将来将还会反对字段的暗藏与展现
保留当前再次查看文档，所有的表头就是咱们本人设置的中文名称了，而且导出的文档文件也同样失效
将来布局
因为工夫和精力有限，Databasir 目前尚有许多性能正在布局之中，短期内会着重关注以下几点
- 提供更多的事件告诉，比方被退出分组、成为组长等
- 提供文档内容自定义水平，比方字段的展现与暗藏，字段值自定义等
- 丰盛文档文件导出格局，比方 Excel、DOC、PDF 等
- 我的项目品质，补充足够的单元测试
结语
文档的重要性是毋庸置疑的，随着工夫线的拉长，它的价值回报会越来越高，但对于初创团队来说生存才是第一要务，短期的高老本与低收益让团队不得不做出临时放弃保护文档的决策，而 Databasir 的指标就是要解决这个矛盾点，在占用极低资源的状况下让团队不仅能活在当下，还能立足将来。
如果你对这个产品有趣味，请在 Github 点击 star 继续关注倒退
Github：https://github.com/vran-dev/d…
文档地址：https://doc.databasir.com
我的项目反馈：https://github.com/vran-dev/d…