数据库表结构文档生成工具

背景

之前在一家小公司工作时，由于没有完善的应用发布流程，包括配置发布平台，和数据库发布系统，导致测试环境（实际上就是一个IP撑起来的简简单单的服务节点）正常的逻辑，到生产环境（3个云服务器节点构成的带有简单负载均衡逻辑的微型集群应用）出现问题。排查才知道，有些字段未同步更新到生产环境。问题：测试环境这么多数据表，我怎么知道哪些表字段更新有同步到生产环境呢？

调研

最简单的方法当然就是对所有的数据表，借助于DataGrip工具的快捷键Ctrl + Alt + G，生成建表语句Schema，粘贴到一个文件，然后使用Beyond Compare这样的文本对比工具。效率很低很低。意外得知Screw工具，可大大解放生产力。

概述

一款能够生成数据库表结构文档的高效工具，支持 MySQL、Oracle、PostgreSQL 等主流的关系数据库。
GitHub
生成的文档有 HTML、Word、Markdown 三种格式，有两种方式生成文档，Java 代码或 Maven 插件 。

实战

引入依赖：

<dependencies>
    <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>

创建 ScrewMain 类：

public class ScrewMain {
    private static final String DB_URL = "jdbc:mysql://localhost:3306";
    private static final String DB_NAME = "shop";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "root";

    private static final String FILE_OUTPUT_DIR = ".";
    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_DESC = "文档描述";

    public static void main(String[] args) {
        Configuration config = Configuration.builder()
                .version(DOC_VERSION)
                .description(DOC_DESC)
                .dataSource(buildDataSource())
                .engineConfig(buildEngineConfig())
                .produceConfig(buildProcessConfig())
                .build();
        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();
    }
}

Maven插件

<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://localhost:3306/shop</jdbcUrl>
                <username>root</username>
                <password>root</password>
                <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>

Maven面板，Plugins多了一个screw，双击screw::run即可。

拓展

screw除了可以生成表结构，还具备mybatis-generator类似功能，即根据数据库连接信息，生成数据表POJO，对应的Mapper接口，以及对应的Mapper.xml文件。
多引入一个screw-extension子模块：

<dependency>
    <groupId>cn.smallbun.screw</groupId>
	<artifactId>screw-extension</artifactId>
	<version>1.0.5</version>
</dependency>

public class ScrewMain {
    private static final String DB_URL = "jdbc:mysql://localhost:3306";
    private static final String DB_NAME = "shop";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "root";

    private static final String FILE_OUTPUT_DIR = ".";
    private static final String JAVA_CLASS_PACKAGE = "com.johnny.po";

    public static void main(String[] args) {
        PojoConfiguration config = PojoConfiguration.builder()
                .path(FILE_OUTPUT_DIR)
                .packageName(JAVA_CLASS_PACKAGE)
                .nameStrategy(new HumpNameStrategy()) // 包名策略
                .useLombok(false)
                .dataSource(buildDataSource())
                .processConfig(buildProcessConfig())
                .build();
        new PojoExecute(config).execute();
    }

    private static DataSource buildDataSource() {
        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");
        return new HikariDataSource(hikariConfig);
    }

    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();
    }
}

参考

Screw 一键生成数据库文档