搜索

数据库界的Swagger：一键生成数据库文档！你不了解一下？

公众号程序猿DD

共 27241字，需浏览 55分钟

 · 2021-10-08

对于API的文档，我们有Swagger等工具来自动生成了。但有有一类文档还是常常困扰着我们，那就是数据库表结构的文档。相信很多同学都有过手写数据库表结构文档 的经历吧？常规操作就是一通无脑的 CV 大法，产出一份小几十页的 Word 文档。

那么，是否有什么工具，可以帮我们偷懒高效的自动 生成数据库表结构文档呢？

还真有！下面就来介绍这样一个工具：screw！

2. screw 简介

screw 是一个简洁好用的数据库表结构文档的生成工具 ，支持 MySQL、Oracle、PostgreSQL 等主流的关系数据库。

screw 的仓库地址是 https://github.com/pingfangushi/screw，感兴趣的胖友，可以研究一波。

生成的文档有 HTML、Word、Markdown 三种格式 ，示例如下图所示：

格式图
HTML
Word
Markdown
如果您正在学习Spring Boot，推荐一个连载多年还在继续更新的免费教程：http://blog.didispace.com/spring-boot-learning-2x/

3. 快速入门

screw 有两种方式 来生成文档，通过 Java 代码 或者 Maven 插件 。

下面，我们来分别快速入门下。

3.1 使用 Java 代码的方式

创建 lab-70-db-doc-screw-01 示例项目，使用 screw 的 Java 代码 的方式，生成文档。

示例示例

3.1.1 引入依赖

在 pom.xml 文件中，引入 screw 的依赖 screw-core。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-01</artifactId>

    <dependencies>
        <!-- screw 库，简洁好用的数据库表结构文档生成器 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>

        <!-- 数据库连接 -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.22</version>
        </dependency>
    </dependencies>

</project>

依赖 HikariCP 和 mysql-connector-java 是为了连接 MySQL 数据库。

3.1.2 ScrewMain

创建 ScrewMain 类，使用 screw 生成文档。代码如下：

public class ScrewMain {

    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";

    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final EngineFileType FILE_OUTPUT_TYPE = EngineFileType.HTML; // 可以设置 Word 或者 Markdown 格式
    private static final String DOC_FILE_NAME = "数据库文档";
    private static final String DOC_VERSION = "1.0.0";
    private static final String DOC_DESCRIPTION = "文档描述";

    public static void main(String[] args) {
        // 创建 screw 的配置
        Configuration config = Configuration.builder()
                .version(DOC_VERSION)  // 版本
                .description(DOC_DESCRIPTION) // 描述
                .dataSource(buildDataSource()) // 数据源
                .engineConfig(buildEngineConfig()) // 引擎配置
                .produceConfig(buildProcessConfig()) // 处理配置
                .build();

        // 执行 screw，生成数据库文档
        new DocumentationExecute(config).execute();
    }

    /**
     * 创建数据源
     */
    private static DataSource buildDataSource() {
        // 创建 HikariConfig 配置类
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
        hikariConfig.setUsername(DB_USERNAME);
        hikariConfig.setPassword(DB_PASSWORD);
        hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
        // 创建数据源
        return new HikariDataSource(hikariConfig);
    }

    /**
     * 创建 screw 的引擎配置
     */
    private static EngineConfig buildEngineConfig() {
        return EngineConfig.builder()
                .fileOutputDir(FILE_OUTPUT_DIR) // 生成文件路径
                .openOutputDir(false) // 打开目录
                .fileType(FILE_OUTPUT_TYPE) // 文件类型
                .produceType(EngineTemplateType.freemarker) // 文件类型
                .fileName(DOC_FILE_NAME) // 自定义文件名称
                .build();
    }

    /**
     * 创建 screw 的处理配置，一般可忽略
     * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
     */
    private static ProcessConfig buildProcessConfig() {
        return ProcessConfig.builder()
                .designatedTableName(Collections.<String>emptyList())  // 根据名称指定表生成
                .designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
                .designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
                .ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
                .ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
                .ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
                .build();
    }

}

代码比较简单，胖友看看注释即可。

比较重要的变量，已经抽取成静态 变量，胖友看着修改哈。

3.1.3 简单测试

执行 ScrewMain 程序，进行文档的生成。这里我们生成的是 HTML 文档，效果如下图所示：

HTML 文档

3.2 使用 Maven 插件的方式

创建 lab-70-db-doc-screw-02 示例项目，使用 screw 的 Maven 插件 的方式，生成文档。

示例示例

3.2.1 引入插件

在 pom.xml 文件中，引入 screw 的插件 screw-maven-plugin。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-02</artifactId>

    <build>
        <plugins>
            <plugin>
                <groupId>cn.smallbun.screw</groupId>
                <artifactId>screw-maven-plugin</artifactId>
                <version>1.0.5</version>
                <dependencies>
                    <!-- 数据库连接 -->
                    <dependency>
                        <groupId>com.zaxxer</groupId>
                        <artifactId>HikariCP</artifactId>
                        <version>3.4.5</version>
                    </dependency>
                    <dependency>
                        <groupId>mysql</groupId>
                        <artifactId>mysql-connector-java</artifactId>
                        <version>8.0.22</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <!-- 数据库相关配置 -->
                    <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                    <jdbcUrl>jdbc:mysql://400-infra.server.iocoder.cn:3306/mall_system</jdbcUrl>
                    <username>root</username>
                    <password>3WLiVUBEwTbvAfsh</password>
                    <!-- screw 配置 -->
                    <fileType>HTML</fileType>
                    <title>数据库文档</title> <!--标题-->
                    <fileName>测试文档名称</fileName> <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
                    <description>数据库文档生成</description> <!--描述-->
                    <version>${project.version}</version> <!--版本-->
                    <openOutputDir>false</openOutputDir> <!--打开文件输出目录-->
                    <produceType>freemarker</produceType> <!--生成模板-->
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

Maven 插件的配置项 比较少，胖友按需修改下 <configuration/> 即可。

3.2.2 简单测试

执行 screw-maven-plugin 插件，会在 doc 目录下生成文档。如下图所示：

执行 Maven 插件

4. 生成实体类

screw 的实现原理，是基于数据库中的表结构 ，生成对应的文档。

那么，是否可以自动 生成 Java 实体类呢？答案是可以的，在 screw-extension 项目中，拓展 提供了该功能。

这样，日常开发中，在我们完成数据库的建表 之后，可以直接生成对应的 Java 实体类，避免枯燥的重复劳动。

下面，我们来快速入门下。创建 lab-70-db-doc-screw-03 示例项目，使用 screw 的 Java 代码 的方式，生成 Java 实体类。

示例示例

4.1 引入依赖

在 pom.xml 文件中，额外 引入 screw 的依赖 screw-extension。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-03</artifactId>

    <dependencies>
        <!-- screw 库，简洁好用的数据库表结构文档生成器 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-extension</artifactId>
            <version>1.0.5</version>
        </dependency>

        <!-- 数据库连接 -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.22</version>
        </dependency>
    </dependencies>

</project>

友情提示：由于 screw-extension 项目处于初步开发阶段，暂时未将该依赖推到 Maven 中央仓库，所以需要自己克隆项目，进行编译打包到本地。

4.2 ScrewMain

创建 ScrewMain 类，使用 screw 生成 Java 实体类。代码如下：

public class ScrewMain {

    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";

    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final String JAVA_CLASS_PACKAGE = "cn.iocoder.dataobject";

    public static void main(String[] args) {
        // 创建 screw 的配置
        PojoConfiguration config = PojoConfiguration.builder()
                .path(FILE_OUTPUT_DIR) // 生成 POJO 相关的目录
                .packageName(JAVA_CLASS_PACKAGE) // 包名
                .nameStrategy(new HumpNameStrategy()) // 包名策略
                .useLombok(false) // 是否使用 Lombok
                .dataSource(buildDataSource()) // 数据源
                .processConfig(buildProcessConfig()) // 处理配置
                .build();

        // 执行 screw，生成 POJO 实体类
        new PojoExecute(config).execute();
    }

    /**
     * 创建数据源
     */
    private static DataSource buildDataSource() {
        // 创建 HikariConfig 配置类
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
        hikariConfig.setUsername(DB_USERNAME);
        hikariConfig.setPassword(DB_PASSWORD);
        hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
        // 创建数据源
        return new HikariDataSource(hikariConfig);
    }

    /**
     * 创建 screw 的处理配置，一般可忽略
     * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
     */
    private static ProcessConfig buildProcessConfig() {
        return ProcessConfig.builder()
                .designatedTableName(Collections.<String>emptyList())  // 根据名称指定表生成
                .designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
                .designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
                .ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
                .ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
                .ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
                .build();
    }

}

代码比较简单，胖友看看注释即可。不同于上面的快速入门，这里我们使用 PojoConfiguration 作为配置类，使用 PojoExecute 作为执行器。

比较重要的变量，已经抽取成静态 变量，胖友看着修改哈。

如果您正在学习Spring Boot，推荐一个连载多年还在继续更新的免费教程：http://blog.didispace.com/spring-boot-learning-2x/

4.3 简单测试

执行 ScrewMain 程序，进行 Java 实体类的生成。效果如下图所示：

Java 实体类

生成的 Java 实体类的成员属性 还不太正确，需要等待作者进行下修复。

666. 彩蛋

至此，我们已经完成 screw 的学习，一起来简单总结下：

  • screw 支持生成数据库表结构文档 ，通过 Java 代码或者 Maven 插件的方式。
  • screw 支持生成 Java 实体类 ，通过 screw-extension 提供。

初略喵了下 screw 的代码，总体代码量在 5000+ 行，核心代码在 2000 行左右。项目分层干净，代码注释完成，胖友可以选择阅读了解下。这样，我们可以根据我们实际项目的需要，进行二次开发 。


往期推荐

被前公司辞退后，前领导打电话命令你给前同事解释代码，该怎么办？

国庆第一天：先换个头像，然后分享下国庆学习计划吧！

Spring Boot 实现扫码登录，这种方式太香了！！

这是什么神仙公司？居然公布离职员工信息，还给差评？

“80后的人，真的该退出IT行业了”，某IT公司领导言论惹争议！



技术交流群

最近有很多人问，有没有读者交流群，想知道怎么加入。加入方式很简单，有兴趣的同学，只需要点击下方卡片，回复“加群“，即可免费加入我们的高质量技术交流群！

点击阅读原文，送你免费Spring Boot教程！

浏览 18
点赞
评论
收藏
分享

手机扫一扫分享

举报
评论
图片
表情
推荐
金融研究 | 使用Python测量关键审计事项的「信息含量」
Tips: 公众号推送后内容只能更改一次，且只能改20字符。如果内容出问题，或者想更新内容， 只能重复推送。为了更好的阅读体验，建议阅读本文博客版， 链接地址https://textdata.cn/blog/2023-01-13-information-content-of-critical-aud
大邓和他的Python
0
我看阿里的年终奖总算发了！
到4月底了，这两天看朋友圈，发现阿里的年终奖终于发了，问了问老同学，也从网上检索了不少信息，基本搞清楚了阿里今年的年终奖情况。近来来阿里一些集团对绩效等级做了较大的调整，以前的旧绩效系统中，绩效分为3.25、3.5、3.75、4和5五个等级，其中4和5是较高绩效等级，较少见。而且之前3.5绩效内部划
公子龙
0
金融研究(更新) | 使用Python构建关键审计事项的「信息含量」
Tips: 公众号推送后内容只能更改一次，且只能改20字符。如果内容出问题，或者想更新内容， 只能重复推送。为了更好的阅读体验，建议阅读本文博客版， 链接地址https://textdata.cn/blog/2023-01-13-information-content-of-critical-aud
大邓和他的Python
0
偷偷告诉你如何一台电脑开多个微信！
大家好，我是轩辕。前几天在粉丝群里，有人问我是怎么在一台电脑上同时登录两个微信的？正好之前写过一篇文章，分析过原理，分享给没看过的小伙伴学习一下。手机端多开微信估计很多人都知道，像华为、小米等手机系统都对此做了支持，不过在运行Windows系统的电脑上怎么启动两个微信呢？其实很简单，你只需要写一个批
编程技术宇宙
0
盘点Lombok的几个骚操作，你绝对没用过！
👉 欢迎加入小哈的星球 ，你将获得: 专属的项目实战 / Java 学习路线 / 一对一提问 / 学习打卡 /  赠书福利全栈前后端分离博客项目 2.0 版本完结啦， 演示链接：http://116.62.199.48/ ，新项目正在酝酿中
小哈学Java
0
堪称最优秀的Docker可视化管理工具——Portainer你真的会用吗？
来源：blog.csdn.net/shark_chili3007/article/details/123366179👉 欢迎加入小哈的星球 ，你将获得: 专属的项目实战 / Java 学习路线 / 一对一提问 / 学习打卡 /  赠书福利全栈前后端分离博客项目
小哈学Java
0
Apache Paimon毕业，湖仓架构的未来发展趋势！
北京时间 2024 年 4 月 16日，开源软件基金会 Apache Software Foundation（以下简称 ASF）正式宣布 Apache Paimon 毕业成为 Apache 顶级项目(TLP, Top Level Project)。经过社区的共同努力和持续创新，Apache Paim
程序源代码
0
JS的这些新特性，你都用过么？
大厂技术  高级前端  Node进阶点击上方 程序员成长指北，关注公众号回复1，加入高级Node交流群作为一门不断演进的语言，JavaScript每年都会引入新特性。这些特性的加入，能够帮助我们编写更加简洁、高效、易于维护的代码。然而，并非所有新特性
程序员成长指北
1
【深度学习】人人都能看懂的LSTM
熟悉深度学习的朋友知道，LSTM是一种RNN模型，可以方便地处理时间序列数据，在NLP等领域有广泛应用。在看了台大李宏毅教授的深度学习视频后，特别是介绍的第一部分RNN以及LSTM，整个人醍醐灌顶。本文就是对视频的记录加上了一些个人的思考。0. 从RNN说起循环神经网络（Recurrent Neur
机器学习初学者
0
我发现 Lombok的几个骚操作，哈哈好用
大家好，我是小富～前言本文不讨论对错，只讲骚操作。有的方法看看就好，知道可以这么用，但是否应用到实际开发中，那就仁者见仁，智者见智了。一万个读者就会有一万个哈姆雷特，希望这篇文章能够给您带来一些思考。耐心看完，你一定会有所收获。@onX例如 onConstructor, oMet
程序员内点事
0
点赞
评论
收藏
分享

手机扫一扫分享

举报