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

1. 简介

在企业级开发中、我们经常会有编写数据库表结构文档的时间付出,每次需要手动进行维护到文档中,很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人,随着项目的需求频繁设计和更改数据库、使用此插件、节省了很多时间,解决了很多问题 。

虽然是细小的螺丝钉,是个细微的小齿轮,然而如果缺了它,那整个的机器就无法运转了,慢说是缺了它,即使是一枚小螺丝钉没拧紧,一个小齿轮略有破损,也要使机器的运转发生故障的…

本篇文章用到的开源项目地址是:https://toscode.gitee.com/leshalv/screw

2. 特点

  • 简介、轻量、设计良好
  • 多数据库支持
    • 已支持:Mysql、Mariadb、Tidb、oracle、sqlserver、postgreSql、Cache DB(2016)
    • 开发中:H2、DB2、HSQL、SQLite、达梦、虚谷、人大金仓、瀚高
  • 多种格式文档
  • 灵活扩展
  • 支持自定义模板

3. 文档生成支持

  • html
  • word
  • markdown

4. 使用案例-pom引入

  1. 引入依赖

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    </dependency>
    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
    <version>2.5.2</version>
    </dependency>
    <dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.25</version>
    </dependency>
    <dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid</artifactId>
    <version>1.2.1</version>
    </dependency>
    <dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.31</version>
    </dependency>
    <dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>1.0.5</version>
    </dependency>
    <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.12</version>
    <scope>test</scope>
    </dependency>
  2. 配置数据库连接信息

    1
    2
    3
    4
    5
    spring.datasource.url=jdbc:mysql://localhost:3306/gang?useSSL=false&useUnicode=true&characterEncoding=UTF8&serverTimezone=Asia/Shanghai 
    spring.datasource.username= root
    spring.datasource.password= xiaoyuge
    spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
    spring.datasource.xa.properties.useInformationSchema=true
  3. 编写测试代码

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    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.Test;
    import org.junit.runner.RunWith;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.test.context.SpringBootTest;
    import org.springframework.context.ApplicationContext;
    import org.springframework.test.context.junit4.SpringRunner;

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

    @SpringBootTest(classes = App.class)
    @RunWith(SpringRunner.class)
    public class AppTest {

    @Autowired
    ApplicationContext applicationContext;

    @Test
    public void exportDbDoc() {
    DataSource dataSourceMysql = applicationContext.getBean(DataSource.class);
    // 生成文件配置
    EngineConfig engineConfig = EngineConfig.builder()
    // 生成文件路径,自己mac本地的地址,这里需要自己更换下路径
    .fileOutputDir("/Users/xiaoyuge/Desktop/screw")
    // 打开目录
    .openOutputDir(false)
    // 文件类型,我这用的是HTML, EngineFileType有以下三种类型:
    //HTML(".html", "documentation_html", "HTML文件"),
    //WORD(".doc", "documentation_word", "WORD文件"),
    //MD(".md", "documentation_md", "Markdown文件");
    .fileType(EngineFileType.HTML)
    // 生成模板实现
    .produceType(EngineTemplateType.freemarker).build();
    // 生成文档配置(包含以下自定义版本号、描述等配置连接)
    Configuration config = Configuration.builder()
    .version("1.0.5")
    .description("生成文档信息描述")
    .dataSource(dataSourceMysql)
    .engineConfig(engineConfig)
    .produceConfig(getProcessConfig())
    .build();

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

    /**
    * 配置想要生成的表+ 配置想要忽略的表
    * @return 生成表配置
    */
    public static ProcessConfig getProcessConfig(){
    // 忽略表名
    List<String> ignoreTableName = Arrays.asList("aa","test_group");
    // 忽略表前缀,如忽略a开头的数据库表
    List<String> ignorePrefix = Arrays.asList("a","t");
    // 忽略表后缀
    List<String> ignoreSuffix = Arrays.asList("_test","czb_");

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

5. 使用案例-Maven插件

在pom.xml文件中添加以下配置即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
<build>
<plugins>
<plugin>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-maven-plugin</artifactId>
<version>${lastVersion}</version>
<dependencies>
<!-- HikariCP -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>3.4.5</version>
</dependency>
<!--mysql driver-->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.20</version>
</dependency>
</dependencies>
<configuration>
<!--username-->
<username>root</username>
<!--password-->
<password>password</password>
<!--driver-->
<driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
<!--jdbc url-->
<jdbcUrl>jdbc:mysql://127.0.0.1:3306/xxxx</jdbcUrl>
<!--生成文件类型-->
<fileType>HTML</fileType>
<!--打开文件输出目录-->
<openOutputDir>false</openOutputDir>
<!--生成模板-->
<produceType>freemarker</produceType>
<!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
<fileName>测试文档名称</fileName>
<!--描述-->
<description>数据库文档生成</description>
<!--版本-->
<version>${project.version}</version>
<!--标题-->
<title>数据库文档</title>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>