Spring Boot + Screw 一键生成数据库设计文档

01 前言

在企业级开发过程中，编写数据库表结构文档一直是个让人头疼的问题。

许多企业要么没有这份文档，要么就是靠手动编写，后续维护起来非常麻烦，常常因为忘记更新给后续工作带来诸多不便。

而 Screw 的出现，为这一问题提供了高效的解决方案。

02、Screw 简介

Screw 是一款能够快速生成数据库文档的开源工具，支持多种数据库，包括 MySQL、MariaDB、TiDB、Oracle、SqlServer、PostgreSQL、Cache DB（2016）、H2（开发中）、DB2（开发中）、HSQL（开发中）、SQLite（开发中）等，基本涵盖了目前主流的数据库类型。

03 代码工程实战

（一）实验目的
利用 Screw 生成 MySQL 数据库的 Word 文档，实现数据库文档的自动化、标准化生成，提高开发效率，减少人工维护文档的工作量。

（二）pom.xml 文件

<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>springboot-demoartifactId>
        <groupId>com.etgroupId>
        <version>1.0-SNAPSHOTversion>
    </parent>
    <modelVersion>4.0.0modelVersion>
    <artifactId>ScrewartifactId>
    <properties>
        <maven.compiler.source>8maven.compiler.source>
        <maven.compiler.target>8maven.compiler.target>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-autoconfigureartifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        </dependency>
        <dependency>
            <groupId>cn.smallbun.screwgroupId>
            <artifactId>screw-coreartifactId>
            <version>1.0.5version>
        </dependency>
        <dependency>
            <groupId>mysqlgroupId>
            <artifactId>mysql-connector-javaartifactId>
            <scope>runtimescope>
        </dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-data-jdbcartifactId>
        </dependency>
    </dependencies>
</project>

注解 ：

1. 该文件定义了项目的依赖关系，引入了 Spring Boot 相关的 Starter 依赖，为项目提供 Web 开发、自动配置、测试等功能支持。
2. 引入 Screw 核心依赖（版本 1.0.5），这是实现数据库文档生成的关键依赖。
3. 添加了 MySQL 连接器依赖，用于项目与 MySQL 数据库的连接，方便获取数据库相关信息以生成文档。
4. 引入 Spring Data Jdbc 依赖，便于进行数据库操作，为生成数据库文档提供数据基础。

（三）生成类代码

package com.et.screw;

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.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;

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

@SpringBootApplication
publicclassApplicationimplementsApplicationRunner {

    @Autowired
    ApplicationContext applicationContext;

    publicstaticvoidmain(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Override
    publicvoidrun(ApplicationArguments args)throws Exception {
        // 获取数据源
        DataSourcedataSourceMysql= applicationContext.getBean(DataSource.class);

        // 配置文档生成引擎
        EngineConfigengineConfig= EngineConfig.builder()
                .fileOutputDir("D://tmp/")  // 设置文档输出目录
                .openOutputDir(false)  // 设置生成完文档后是否打开输出目录，默认 false
                .fileType(EngineFileType.WORD)  // 设置生成文档的文件类型为 Word
                .produceType(EngineTemplateType.freemarker)  // 使用 freemarker 模板引擎
                .build();

        // 构建文档配置
        Configurationconfig= Configuration.builder()
                .title("数据库文档")  // 设置文档标题
                .version("1.0.0")  // 设置文档版本
                .description("数据库设计文档")  // 设置文档描述
                .dataSource(dataSourceMysql)  // 设置数据源
                .engineConfig(engineConfig)  // 设置引擎配置
                .produceConfig(getProcessConfig())  // 设置处理配置
                .build();

        // 执行文档生成
        newDocumentationExecute(config).execute();
    }

    /**
     * 获取处理配置
     *
     * @return ProcessConfig 处理配置对象
     */
    privatestatic ProcessConfig getProcessConfig() {
        List<String> ignoreTableName = Arrays.asList("table1", "table2");  // 设置要忽略的表名列表
        return ProcessConfig.builder()
                .designatedTableName(newArrayList<>())  // 指定需要处理的表名列表，默认为空
                .designatedTablePrefix(newArrayList<>())  // 指定需要处理的表前缀列表，默认为空
                .designatedTableSuffix(newArrayList<>())  // 指定需要处理的表后缀列表，默认为空
                .ignoreTableName(ignoreTableName)  // 设置忽略的表名
                .build();
    }
}

注解 ：

1. 通过 @SpringBootApplication 注解，开启项目的自动配置等 Spring Boot 相关功能，同时该注解也包含了 @Configuration、@EnableAutoConfiguration、@ComponentScan 注解的功能，方便项目的整体配置和组件扫描。
2. 实现 ApplicationRunner 接口，在项目启动后执行 run 方法，从而触发数据库文档的生成流程。
3. 在 run 方法中，首先从 Spring 容器中获取数据源对象，这是与数据库交互的关键。
4. 构建 EngineConfig 对象，对文档生成引擎进行配置，包括输出目录、是否打开输出目录、文件类型以及模板引擎类型等，根据实际需求灵活设置这些参数就能实现不同格式文档的输出。
5. 构建 Configuration 对象，整合文档标题、版本、描述、数据源、引擎配置以及处理配置等信息，这是整个文档生成的核心配置对象，它将指导文档生成工具按照指定规则生成文档。
6. getProcessConfig 方法用于获取处理配置，可以指定要处理的表名、表前缀、表后缀以及忽略的表名等，方便对文档中包含的数据库表内容进行精细控制，根据实际情况灵活设置这些参数可以轻松筛选出需要生成文档的表，避免无关表信息的干扰。

（四）application.properties 文件

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/jwordpress?useUnicode=true&characterEncoding=utf-8&autoReconnect=true&failOverReadOnly=false&useSSL=false&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123456

注解 ：

1. 配置了数据库连接的相关参数，包括驱动类名、数据库地址（包含数据库名称、编码、时区等信息）、用户名和密码。
2. 通过这些参数，Spring Boot 应用能够成功连接到 MySQL 数据库，从而获取数据库中的表结构等信息，为后续的文档生成提供数据支撑。

04 测试验证

启动 Spring Boot Application，待程序运行完成后，在 D://tmp/ 目录下查看生成的数据库文档 Word 文件。

若文件成功生成且内容准确无误，便说明集成 Screw 实现数据库文档生成的功能成功实现。