使用Spring Boot和Screw轻松生成数据库设计文档

目录

1. 引言

2. 准备工作

   • 项目初始化

   • 引入依赖

3. 配置数据库连接

4. 集成Screw生成文档

   • 基本配置

   • 生成数据库文档

5. 实战操作

   • 示例项目

   • 生成效果

6. 结论

7. 常见问题

8. 延伸阅读

引言

数据库设计文档是项目技术文档的重要组成部分。它不仅有助于开发人员理解数据库结构，还能为将来的维护和扩展提供重要参考。然而，手动维护这些文档效率低且容易出错。Spring Boot 和 Screw 提供了一种快速、准确、自动化生成数据库设计文档的方式。

Screw 是一款开源的数据库文档生成工具，它支持多种数据库类型，并能生成丰富格式的文档，如 HTML、Word 和 Markdown 等。本文将通过一个实际的例子，展示如何使用 Spring Boot 集成 Screw 生成数据库设计文档。

准备工作

项目初始化

首先，我们需要初始化一个 Spring Boot 项目。你可以通过 Spring Initializr 来完成这一步。

使用 Spring Initializr 初始化项目

1. 打开 Spring Initializr

2. 选择项目构建工具为 Maven 或 Gradle

3. 输入相关项目信息，如 Group、Artifact、名称等

4. 选择 Spring Boot 版本

5. 选择依赖项：

   • Spring Web

   • Spring Data JPA

   • MySQL Driver（或其他你使用的数据库驱动）

点击"Generate"按钮生成项目，并将其解压到本地开发环境。

引入依赖

在初始化的项目中，我们需要添加 Screw 的依赖。打开 pom.xml 文件，添加以下依赖：

<dependency>

    <groupId>cn.smallbun.screw</groupId>

    <artifactId>screw-core</artifactId>

    <version>1.0.9</version>

</dependency>

确保 Spring Boot 和数据库相关的依赖已经添加。一个完整的 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">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>

    <artifactId>screw-demo</artifactId>

    <version>0.0.1-SNAPSHOT</version>

    <packaging>jar</packaging>

    <name>screw-demo</name>

    <description>Demo project for Spring Boot and Screw integration</description>



    <parent>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-parent</artifactId>

        <version>2.5.4</version>

        <relativePath/> <!-- lookup parent from repository -->

    </parent>



    <properties>

        <java.version>11</java.version>

    </properties>



    <dependencies>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-data-jpa</artifactId>

        </dependency>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

        <dependency>

            <groupId>mysql</groupId>

            <artifactId>mysql-connector-java</artifactId>

            <scope>runtime</scope>

        </dependency>

        <dependency>

            <groupId>cn.smallbun.screw</groupId>

            <artifactId>screw-core</artifactId>

            <version>1.0.9</version>

        </dependency>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-test</artifactId>

            <scope>test</scope>

        </dependency>

    </dependencies>



    <build>

        <plugins>

            <plugin>

                <groupId>org.springframework.boot</groupId>

                <artifactId>spring-boot-maven-plugin</artifactId>

            </plugin>

        </plugins>

    </build>



</project>

配置数据库连接

在进行 Screw 集成之前，我们需要配置数据库连接。在 application.properties 中添加数据库连接信息：

spring.datasource.url=jdbc:mysql://localhost:3306/your_database_name?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC

spring.datasource.username=root

spring.datasource.password=your_password

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

spring.jpa.database-platform=org.hibernate.dialect.MySQL8Dialect

spring.jpa.show-sql=true

spring.jpa.hibernate.ddl-auto=update

根据你的实际情况更改数据库 URL、用户名和密码等信息。

集成Screw生成文档

基本配置

接下来，我们需要创建一个配置类，用于设置 Screw 生成数据库文档的相关参数。

在 src/main/java/com/example/screwdemo/config 目录下创建一个新的 Java 类 ScrewConfiguration：

package com.example.screwdemo.config;



import cn.smallbun.screw.core.Configuration;

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.DefaultSchemaProcess;

import cn.smallbun.screw.core.process.ProcessConfig;

import com.zaxxer.hikari.HikariConfig;

import com.zaxxer.hikari.HikariDataSource;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;



import javax.sql.DataSource;

import java.util.Arrays;

import java.util.Collections;



@Configuration

public class ScrewConfiguration {



    @Value("${spring.datasource.url}")

    private String url;



    @Value("${spring.datasource.username}")

    private String username;



    @Value("${spring.datasource.password}")

    private String password;



    @Value("${spring.datasource.driver-class-name}")

    private String driverClassName;



    @Bean

    public DataSource dataSource() {

        HikariConfig hikariConfig = new HikariConfig();

        hikariConfig.setDriverClassName(driverClassName);

        hikariConfig.setJdbcUrl(url);

        hikariConfig.setUsername(username);

        hikariConfig.setPassword(password);

        return new HikariDataSource(hikariConfig);

    }



    @Bean

    public void documentGeneration() {

        DataSource dataSource = dataSource();



        // Screw 配置

        Configuration config = Configuration.builder()

                .version("1.0.3")

                .description("数据库设计文档生成")

                .dataSource(dataSource)

                .engineConfig(getEngineConfig())

                .produceConfig(getProcessConfig())

                .build();



        new DocumentationExecute(config).execute();

    }



    /**

     * 文档引擎配置

     */

    private cn.smallbun.screw.core.engine.EngineConfig getEngineConfig() {

        return cn.smallbun.screw.core.engine.EngineConfig.builder()

                // 生成文件路径

                .fileOutputDir("src/main/resources/docs")

                // 打开输出目录

                .openOutputDir(true)

                // 文件类型

                .fileType(EngineFileType.HTML)

                // 使用模板

                .produceType(EngineTemplateType.freemarker)

                .build();

    }



    /**

     * 生成配置

     */

    private ProcessConfig getProcessConfig() {

        return ProcessConfig.builder()

                // 指定生成表名, null时表示生成所有表

                .designatedTableName(Collections.emptyList())

                // 指定表前缀

                .designatedTablePrefix(Collections.emptyList())

                // 指定表后缀

                .designatedTableSuffix(Collections.emptyList())

                .build();

    }

}

生成数据库文档

通过上面的配置，我们已经完成了所有必要的步骤。现在，只需启动 Spring Boot 应用，我们的配置类会自动生成数据库设计文档并将其输出到 src/main/resources/docs 目录下。

你可以通过自己的 IDE 或命令行工具来启动 Spring Boot 应用：

mvn spring-boot:run

也可以生成一个可执行的 JAR 文件并运行：

mvn clean package

java -jar target/screw-demo-0.0.1-SNAPSHOT.jar

实战操作

示例项目

假设我们有以下的一些数据库表：

CREATE TABLE `user` (

    `id` bigint(20) NOT NULL AUTO_INCREMENT,

    `username` varchar(50) NOT NULL,

    `email` varchar(100) NOT NULL,

    `password` varchar(100) NOT NULL,

    `created_time` datetime NOT NULL,

    PRIMARY KEY (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;



CREATE TABLE `role` (

    `id` bigint(20) NOT NULL AUTO_INCREMENT,

    `role_name` varchar(50) NOT NULL,

    `description` varchar(255) DEFAULT NULL,

    PRIMARY KEY (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;



CREATE TABLE `user_role` (

    `user_id` bigint(20) NOT NULL,

    `role_id` bigint(20) NOT NULL,

    PRIMARY KEY (`user_id`, `role_id`),

    KEY `fk_role_id` (`role_id`),

    CONSTRAINT `fk_role_id` FOREIGN KEY (`role_id`) REFERENCES `role` (`id`) ON DELETE CASCADE,

    CONSTRAINT `fk_user_id` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`) ON DELETE CASCADE

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

生成效果

启动应用后，Screw 会自动生成数据库设计文档，我们可以在 src/main/resources/docs 目录下找到生成的 HTML 文件。

该文件包含所有数据库表的详细信息，包括列名、数据类型、约束条件、索引等信息，还会提供各表之间的关系信息，方便开发者理解和维护数据库。

结论

通过本文所展示的方法，可以利用 Spring Boot 与 Screw 轻松生成数据库设计文档。相比手工制作，这种自动化方法不仅高效，还能保证文档的准确性和实时性。希望本文能够帮助你理解和使用 Screw，以提升项目的开发和维护效率。

常见问题

1. 为什么 Screw 生成的文档不包含表之间的关系？

确保数据库中的外键约束配置正确，因为 Screw 会根据外键信息生成表关系图。如果数据库没有外键约束，生成的文档将缺少表关系信息。

2. Screw 支持哪些数据库？

Screw 支持多种数据库，包括但不限于 MySQL、PostgreSQL、Oracle 和 SQL Server。

3. 文件生成路径可以更改吗？

可以通过 getEngineConfig 方法中的 fileOutputDir 参数来设置输出路径。

4. 支持哪些格式的文档?

Screw 支持 HTML、Word、Markdown 等多种文档格式，可以通过 fileType 参数进行配置。

延伸阅读

• Screw GitHub 仓库

• Spring Boot 官方文档

• Spring Data JPA 官方文档

通过结合 Spring Boot 和 Screw，我们可以大大简化数据库设计文档的生成过程，提高开发效率。如果你对数据库设计和文档生成有更高的要求，建议进一步研究 Screw 的高级特性和配置选项。