Java 自动生成数据库文档

发表于 阅读次数： 评论数： 本文字数： 1.1k 阅读时长 ≈ 1 分钟

前言

在企业级开发中，我们经常会有编写数据库文档的时间付出，关于数据库文档的状态：要么没有、要么有但都是手写、后期运维开发都需要手动对文档进行维护，很是繁琐。如果忘记一次维护就会给以后的工作造成很多困扰，这无形中留了很多坑给自己和后人。screw 是一款简洁好用的数据库文档生成工具，专为解决这一开发痛点而生。

screw 介绍

特色功能

  • 灵活扩展
  • 支持自定义模板
  • 支持多种数据库
  • 支持多种格式的文档
  • 简洁、轻量、设计良好

数据库支持

  • MySQL
  • MariaDB
  • TIDB
  • Oracle
  • SqlServer
  • PostgreSQL
  • Cache DB（2016）

文档类型支持

  • Html
  • Word
  • Markdown

screw 使用

基于 Java 代码

第一种使用方式是基于 Java 代码，自动生成数据库文档。

Maven 依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<dependencies>
    <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>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
        <version>3.4.5</version>
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.20</version>
    </dependency>
</dependencies>

Java 代码

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
82
83
84
85
86
87
88
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 com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

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

/**
 * 生成数据库文档
 */
public class ScrewTest {

    public static final String fileOutputDir = "D:/database/docs";

    public static void main(String[] args) {
        documentGeneration();
    }

    /**
     * 文档生成
     */
    public static void documentGeneration() {
        //数据源
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/database");
        hikariConfig.setUsername("root");
        hikariConfig.setPassword("123456");
        //设置可以获取tables remarks信息
        hikariConfig.addDataSourceProperty("useInformationSchema", "true");
        hikariConfig.setMinimumIdle(2);
        hikariConfig.setMaximumPoolSize(5);
        DataSource dataSource = new HikariDataSource(hikariConfig);
        //生成配置
        EngineConfig engineConfig = EngineConfig.builder()
                //生成文件路径
                .fileOutputDir(fileOutputDir)
                //打开目录
                .openOutputDir(true)
                //文件类型
                .fileType(EngineFileType.HTML)
                //生成模板实现
                .produceType(EngineTemplateType.freemarker)
                //自定义文件名称
                .fileName("自定义文件名称").build();

        //忽略表
        ArrayList<String> ignoreTableName = new ArrayList<>();
        //忽略表前缀
        ArrayList<String> ignorePrefix = new ArrayList<>();
        //忽略表后缀
        ArrayList<String> ignoreSuffix = new ArrayList<>();
        ProcessConfig processConfig = ProcessConfig.builder()
                //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
                //根据名称指定表生成
                .designatedTableName(new ArrayList<>())
                //根据表前缀生成
                .designatedTablePrefix(new ArrayList<>())
                //根据表后缀生成
                .designatedTableSuffix(new ArrayList<>())
                //忽略表名
                .ignoreTableName(ignoreTableName)
                //忽略表前缀
                .ignoreTablePrefix(ignorePrefix)
                //忽略表后缀
                .ignoreTableSuffix(ignoreSuffix).build();
        //配置
        Configuration config = Configuration.builder()
                //版本
                .version("1.0.0")
                //描述
                .description("数据库设计文档生成")
                //数据源
                .dataSource(dataSource)
                //生成配置
                .engineConfig(engineConfig)
                //生成配置
                .produceConfig(processConfig)
                .build();
        //执行生成
        new DocumentationExecute(config).execute();
    }
}

基于 Maven 插件

第二种使用方式是基于 Maven 插件，自动生成数据库文档。

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>123456</password>
                <!--driver-->
                <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                <!--jdbc url-->
                <jdbcUrl>jdbc:mysql://127.0.0.1:3306/database</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>

扩展模块

在日常的开发中，经过需求分析、建模之后，往往会先在数据库中建表，其次再进行代码的开发。使用 POJO 生成功能可以直接根据数据库表生成对应的 Java POJO 对象，这可以帮助开发人员节省一些重复劳动。screw 支持 POJO 生成功能，目前处于初步开发的状态，且仅支持 MySQL 数据库。

POJO 生成模块

1
2
3
4
5
<dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-extension</artifactId>
    <version>${lastVersion}</version>
 </dependency>
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
/**
 * POJO 生成
 */
void pojoGeneration() {
    //数据源
    HikariConfig hikariConfig = new HikariConfig();
    hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
    hikariConfig.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/database");
    hikariConfig.setUsername("root");
    hikariConfig.setPassword("123456");
    //设置可以获取tables remarks信息
    hikariConfig.addDataSourceProperty("useInformationSchema", "true");
    hikariConfig.setMinimumIdle(2);
    hikariConfig.setMaximumPoolSize(5);
    DataSource dataSource = new HikariDataSource(hikariConfig);

    ProcessConfig processConfig = ProcessConfig.builder()
        //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
        //根据名称指定表生成
        .designatedTableName(new ArrayList<>())
        //根据表前缀生成
        .designatedTablePrefix(new ArrayList<>())
        //根据表后缀生成
        .designatedTableSuffix(new ArrayList<>()).build();

    //设置生成pojo相关配置
    PojoConfiguration config = new PojoConfiguration();
    //设置文件存放路径
    config.setPath("/cn/smallbun/screw/");
    //设置包名
    config.setPackageName("cn.smallbun.screw");
    //设置是否使用lombok
    config.setUseLombok(false);
    //设置数据源
    config.setDataSource(dataSource);
    //设置命名策略
    config.setNameStrategy(new HumpNameStrategy());
    //设置表过滤逻辑
    config.setProcessConfig(processConfig);
    //执行生成
    new PojoExecute(config).execute();
}

常见问题

问题一

生成的数据库文档出现乱码？

在连接 MySQL 的 URL 中加入 characterEncoding=UTF-8 即可

问题二

MySQL 数据库表和列字段有注释，但生成的数据库文档却没有注释？

在连接 MySQL 的 URL 中加入 useInformationSchema=true 即可

问题三

运行抛出异常： Caused by: java.lang.NoSuchFieldError: VERSION_2_3_30

检查项目中 freemarker 的依赖版本，这是由于版本过低造成的，升级版本为 2.3.30 即可

问题四

运行抛出异常： java.lang.AbstractMethodError: com.mysql.jdbc.JDBC4Connection.getSchema()Ljava/lang/String;

这是因为 MySQL 驱动的版本过低造成的，升级 MySQL 驱动的版本为最新即可

问题五

运行抛出异常： java.lang.AbstractMethodError: oracle.jdbc.driver.T4CConnection.getSchema()Ljava/lang/String;

这是因为 Oracle 驱动版本过低造成的，删除或屏蔽当前的驱动版本，并将驱动升级为以下版本：

1
2
3
4
5
6
7
8
9
10
<dependency>
   <groupId>com.oracle.ojdbc</groupId>
   <artifactId>ojdbc8</artifactId>
   <version>19.3.0.0</version>
</dependency>
<dependency>
   <groupId>cn.easyproject</groupId>
   <artifactId>orai18n</artifactId>
   <version>12.1.0.2.0</version>
</dependency>

文档生成截图