首页 Java知识正文

SpringBoot + Screw 一键生成数据库文档

admin Java知识 2021-07-22 76 0


  • 1. 概述

    闲来无事的周六,被 ? 芳放了鸽子,只好蹲在被窝里研究会技术,安慰下自己受伤的心灵。

    鸽子

    相信胖友们都手写数据库表结构文档 ,一通无脑的 CV 大法之后,小几十页的  Word 文档就出炉了。

    那么有没什么工具,可以帮我们偷懒高效的自动 生成数据库表结构文档呢?有,通过使用 screw 生成工具。

    2. screw 简介

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

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

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

    3. 快速入门

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

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

    3.1 使用 Java 代码的方式

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

    示例示例

    友情提示:示例代码的完整地址,可见 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-70-db-doc/lab-70-db-doc-screw-01。

    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>

    依赖 HikariCPmysql-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 插件 的方式,生成文档。

    示例示例

    友情提示:示例代码的完整地址,可见 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-70-db-doc/lab-70-db-doc-screw-02。

    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 实体类。

    示例示例

    友情提示:示例代码的完整地址,可见 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-70-db-doc/lab-70-db-doc-screw-03。

    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 作为执行器。

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

    4.3 简单测试

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

    Java 实体类

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

    666. 彩蛋

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

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


    End~继续抠脚。

    我是艿艿,一个每天徘徊在煞笔牛啤 的死胖子。

    - END -



    版权声明

    本文仅代表作者观点,不代表本站立场。
    本文系作者授权发表,未经许可,不得转载。

    评论