自動生成數據庫文檔 springboot+screw

https://mp.weixin.qq.com/s/6Q6ptDp8o7sN7F1mCs31Pw

1. 概述
2. screw 簡介
3. 快速入門

3.1 使用 Java 代碼的方式
3.2 使用 Maven 插件的方式

4. 生成實體類
666. 彩蛋

1. 概述

閑來無事的周六，被 ?? 芳放了鴿子，只好蹲在被窩里研究會技術，安慰下自己受傷的心靈。

鴿子

相信胖友們都手寫過數據庫表結構文檔 ，一通無腦的 CV 大法之后，小幾十頁的 Word 文檔就出爐了。

那么有沒什么工具，可以幫我們偷懶高效的自動生成數據庫表結構文檔呢？有，通過使用 screw 生成工具。

2. screw 簡介

screw 是一個簡潔好用的數據庫表結構文檔的生成工具 ，支持 MySQL、Oracle、PostgreSQL 等主流的關系數據庫。

良心艿：screw 的倉庫地址是 https://github.com/pingfangushi/screw，感興趣的胖友，可以研究一波。

生成的文檔有 HTML、Word、Markdown 三種格式，示例如下圖所示：

格式	圖
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>

依賴 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 插件 的方式，生成文檔。

示例示例

友情提示：示例代碼的完整地址，可見 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 支持生成數據庫表結構文檔 ，通過 Java 代碼或者 Maven 插件的方式。
screw 支持生成 Java 實體類 ，通過 screw-extension 提供。

初略喵了下 screw 的代碼，總體代碼量在 5000+ 行，核心代碼在 2000 行左右。項目分層干凈，代碼注釋完成，胖友可以選擇閱讀了解下。這樣，我們可以根據我們實際項目的需要，進行二次開發 。

posted @ 2021-07-22 18:30 冬天不眠閱讀(651) 評論(0) 收藏舉報

刷新頁面返回頂部

公告