【Screw】数据库表结构文档工具操作

需求

在交付型项目中，往往需要大量的数据库设计文档的编写，手动写总有遗漏或者更新不及时的问题，一个项目可能设计到的表几百上千张，手动去敲肯定会是一件劳民伤财的事儿，那么有什么工具可以直接堆数据库中现有的表进行汇总并输出相应的文档呢？

介绍

screw，原意螺丝钉，是一个简洁好用的数据库表结构文档生成工具，是gitee上的基于java开发的开源项目。

使用方式

官方介绍的使用方式有两种：
连接：https://gitee.com/leshalv/screw

1. 普通方式 - 代码实现文档生产
2. Maven 插件 - 引入插件，通过maven命令生成文档

1. 代码方式

注意：代码的方式导出Mysql,Oracle等数据库没有问题，但是***导出PG库的相关表结构信息，建议使用方式2，Maven插件的方式***。

1.1 创建spring工程，并且选择SQL依赖的JDBC API

1.2 配置application.properties配置

spring.datasource.url=jdbc:postgresql://${PG_IP}:5432/metaspace_test?currentSchema=public&useUnicode=true&characterEncoding=UTF8
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.datasource.driver-class-name=org.postgresql.Driver
#按照码云文档说明: MySQL数据库表和列字段有说明、生成文档没有说明
spring.datasource.xa.properties.userInformationSchema= true

1.3 添加依赖

<dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>${lastVersion}</version>
 </dependency>

1.4 编写测试代码

import cn.smallbun.screw.core.Configuration;
import cn.smallbun.screw.core.engine.EngineConfig;
import cn.smallbun.screw.core.engine.EngineFileType;
import cn.smallbun.screw.core.engine.EngineTemplateType;
import cn.smallbun.screw.core.execute.DocumentationExecute;
import cn.smallbun.screw.core.process.ProcessConfig;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;

import javax.sql.DataSource;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootTest
class ScrewdemoApplicationTests {

    @Autowired
    private ApplicationContext applicationContext;

    @Test
    void testGenerateDatabaseDocument() {

        DataSource dataSource = applicationContext.getBean(DataSource.class);

        EngineConfig engineConfig = EngineConfig.builder()
                //生成文件路径
                .fileOutputDir("/resources")
                // 打开目录
                .openOutputDir(true)
                // 文件类型，支持word、md和html
                .fileType(EngineFileType.HTML)

                //生成模板实现，支持freemarker和velocity
                .produceType(EngineTemplateType.freemarker).build();

        //生成配置文档
        Configuration configuration = Configuration.builder()
                .version("1.0.3")
                .description("学生数据库文档描述信息")
                .dataSource(dataSource)
                .engineConfig(engineConfig)
                .produceConfig(getProcessConfig())
                .build();

        //执行生成
        new DocumentationExecute(configuration).execute();
    }

    /**
     * 配置想要生成的表 + 配置想要忽略的表
     * @return
     */
    private ProcessConfig getProcessConfig() {

        // 忽略表名
        List<String> ignoreTable = Arrays.asList("aa","test_group");

        //忽略表前缀，如忽略a开头的数据库表
        List<String> ignorePrefix = Arrays.asList("sys");
        //忽略表后缀
        List<String> ignoreSuffix = Arrays.asList("month");

        return ProcessConfig.builder()
                // 根据名称生成指定表
                .designatedTableName(new ArrayList<String>())
                // 根据表前缀生成
                .designatedTablePrefix(new ArrayList<String>())
                // 根据表后缀生成
                .designatedTableSuffix(new ArrayList<String>())
                // 忽略表名
                .ignoreTableName(ignoreTable)
                // 忽略表前缀
                .ignoreTablePrefix(ignorePrefix)
                // 忽略表后缀
                .ignoreTableSuffix(ignoreSuffix).build();
    }
}

1.5 执行后即可在resource路径下生成相应的HTML

2. Maven 插件方式

个人建议通过maven插件的方式使用screw,主要有如下几点：

代码实现的方式，存在代码侵入。而往往数据库设计文档不会频繁的去生成它，一般就是在项目交付的时候会用到，频次低，不适合长期的代码维护。
插件的方式，可以一次配置之后，每次项目编译的时候自动更新文档，如果在开发测试或生产环境不需要执行的时候，通过修改配置或者maven命令可以跳过执行插件。

2.1 引入插件

 <plugin>
                <groupId>cn.smallbun.screw</groupId>
                <artifactId>screw-maven-plugin</artifactId>
                <version>1.0.5</version>
                <dependencies>
                    <!--screw默认使用HikariCP -->
                    <dependency>
                        <groupId>com.zaxxer</groupId>
                        <artifactId>HikariCP</artifactId>
                        <version>3.4.5</version>
                    </dependency>
                    <!--数据库驱动依赖-->
                    <dependency>
                        <groupId>org.postgresql</groupId>
                        <artifactId>postgresql</artifactId>
                        <version>42.2.12</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <!--username-->
                    <username>postgres</username>
                    <!--password-->
                    <password>postgres</password>
                    <!--driver-->
                    <driverClassName>org.postgresql.Driver</driverClassName>
                    <!--jdbc url-->
                    <jdbcUrl>jdbc:postgresql://${PG_IP}/metaspace_test?stringtype=unspecified</jdbcUrl>
                    <!--需要忽略的表名-->
                    <ignoreTableName>flyway_schema_history,sm_action_logs</ignoreTableName>
                    <!--指定表名生成文档-->
<!--                    <designatedTableName>flyway_schema_history,sm_action_logs</designatedTableName>-->
                    <!--生成文件类型：WORD、HTML、MD-->
                    <fileType>WORD</fileType>
                    <!--使用的模板类型：velocity、freemarker(默认值) -->
                    <produceType>freemarker</produceType>
                    <!--执行完后是否打开文件输出目录：默认为true-->
                    <openOutputDir>true</openOutputDir>
                    <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
                    <fileName>数据库文档</fileName>
                    <!--描述-->
                    <description>数据库文档生成</description>
                    <!--版本-->
                    <version>0.0.1</version>
                    <!--标题-->
                    <title>数据库文档</title>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

2.2 mvn执行命令

mvn -DskipTests=true cn.smallbun.screw:screw-maven-plugin:1.0.5:run

本插件绑定在compile阶段，所以执行包含compile阶段的所有命令都会触发，例如：mvn clean install mvn clean compile mvn clean deploy等

2.3 idea直接执行

2.4 执行结果

在工程的doc目录下生成相应的数据文档


注意：

1. 默认生成的文档路径：pom.xml所属的模块根目录下的doc文件夹；
2. designatedTableName优先级高于ignoreTableName配置，例：

<ignoreTableName>flyway_schema_history,sm_action_logs</ignoreTableName>
<designatedTableName>flyway_schema_history,sm_action_logs</designatedTableName>

3. 需要保证数据库的表和字段都有对应的表注释和字段注释