工具库一键生成数据库说明文档

最新推荐文章于 2024-04-25 18:01:24 发布

不会打字314

最新推荐文章于 2024-04-25 18:01:24 发布

阅读量378

点赞数

分类专栏： springboot 工具库文章标签：数据库

本文链接：https://blog.csdn.net/shaoming314/article/details/111636898

版权

springboot 同时被 2 个专栏收录

161 篇文章 9 订阅

订阅专栏

工具库

38 篇文章 0 订阅

订阅专栏

一键生成数据库文档

参考网址:

https://mp.weixin.qq.com/s?__biz=MzI4Njc5NjM1NQ==&mid=2247501250&idx=1&sn=4908cc0df374ff99bf89e27cb5aadd51&chksm=ebd5faeedca273f84a97477d296e48fbb515e65d94a543f2222943fd151e10184d5e526d8a47&mpshare=1&scene=23&srcid=1223r3UA0gszHBV74dRmcA05&sharer_sharetime=1608730912167&sharer_shareid=9d1e76e919cc0b2f3ca23ed1f5ef67a8#rd

https://mp.weixin.qq.com/s/Bo_U5_cl82hfQ6GmRs2vtA

1.简介

在企业级开发中、我们经常会有编写数据库表结构文档的时间付出，从业以来，待过几家企业，关于数据库表结构文档状态：要么没有、要么有、但都是手写、后期运维开发，需要手动进行维护到文档中，很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人，于是需要一个插件工具screw[1]来维护。

2.特点

简洁、轻量、设计良好。不需要 powerdesigner 这种重量的建模工具
多数据库支持。支持市面常见的数据库类型 MySQL、Oracle、SqlServer
多种格式文档。支持 MD、HTML、WORD 格式
灵活扩展。支持用户自定义模板和展示样式

3.使用方式

通过自定义代码配置文档生成
通过插件的形式生成文档

个人推荐使用通过自定义代码配置文档生成

说明:通过自定义代码配置文档生成原因

使用springboot项目,我们不需要再pom.xml进行配置,减少耦合

4.实践说明

举例的数据库,是开源项目ruoyi的数据表

1.新建springboot项目

2.导入相关的依赖

<?xml version="1.0" encoding="UTF-8"?>
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.shaoming</groupId>
    <artifactId>springboot-sql-dev-file</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-sql-dev-file</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>

        <!--需要引入的依赖-->
        <!-- mysql 驱动 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- springboot的web依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--springBoot数据库连接 必须配置数据源等信息 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <!-- 数据库生成文档所需要的依赖
         freemarker模板依赖
         -->
        <dependency>
            <groupId>org.freemarker</groupId>
            <artifactId>freemarker</artifactId>
            <version>2.3.30</version>
        </dependency>
        <!-- 数据库生成模板的核心依赖 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.3</version>
        </dependency>


        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </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>

3.配置springboot配置文件

spring.datasource.url=jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8&useInformationSchema=true
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.xa.properties.useInformationSchema=true

4.写springboot测试方法进行生成文档

4.1 springboot方式生成数据库文档

package com.shaoming;

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 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 org.springframework.util.ResourceUtils;

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

@SpringBootTest
class SpringbootSqlDevFileApplicationTests {

    @Autowired
    ApplicationContext applicationContext;

    @Test
    void contextLoads() {
        DataSource dataSourceMysql = applicationContext.getBean(DataSource.class);


        // 生成文件配置
        EngineConfig engineConfig = EngineConfig.builder()
                // 生成文件路径，自己mac本地的地址，这里需要自己更换下路径
                .fileOutputDir(System.getProperty("user.dir") + "/src/main/resources/sqlfile/")
                // 打开目录
                .openOutputDir(false)
                // 文件类型
                .fileType(EngineFileType.MD)
                // 生成模板实现
                .produceType(EngineTemplateType.freemarker).build();

        // 生成文档配置（包含以下自定义版本号、描述等配置连接）
        Configuration config = Configuration.builder()
                .version("1.0.3")
                .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<>())
                //根据表前缀生成
                .designatedTablePrefix(new ArrayList<>())
                //根据表后缀生成
                .designatedTableSuffix(new ArrayList<>())
                //忽略表名
                .ignoreTableName(ignoreTableName)
                //忽略表前缀
                .ignoreTablePrefix(ignorePrefix)
                //忽略表后缀
                .ignoreTableSuffix(ignoreSuffix).build();
    }

   
}

4.2 maven项目方式生成数据库文档

package com.shaoming;

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 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 org.springframework.util.ResourceUtils;

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

@SpringBootTest
class SpringbootSqlDevFileApplicationTests {

    @Autowired
    ApplicationContext applicationContext;

    /**
     * 使用maven工程生成数据库说明文档
     * 参考网址:
     https://mp.weixin.qq.com/s/Bo_U5_cl82hfQ6GmRs2vtA
     */
    @Test
    public void shouldAnswerWithTrue() {
        //数据源
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl("jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8&useInformationSchema=true");
        hikariConfig.setUsername("root");
        hikariConfig.setPassword("root");
        //设置可以获取tables remarks信息
        hikariConfig.addDataSourceProperty("useInformationSchema", "true");
        hikariConfig.setMinimumIdle(2);
        hikariConfig.setMaximumPoolSize(5);
        DataSource dataSource = new HikariDataSource(hikariConfig);
        //生成配置
        EngineConfig engineConfig = EngineConfig.builder()
                //生成文件路径
                .fileOutputDir(System.getProperty("user.dir") + "/src/main/resources/sqlfile/")
                //打开目录
                .openOutputDir(true)
                //文件类型
                .fileType(EngineFileType.HTML)
                //生成模板实现
                .produceType(EngineTemplateType.freemarker).build();

        //忽略表
        ArrayList<String> ignoreTableName = new ArrayList<>();
        ignoreTableName.add("test_user");
        ignoreTableName.add("test_group");
        //忽略表前缀
        ArrayList<String> ignorePrefix = new ArrayList<>();
        ignorePrefix.add("test_");
        //忽略表后缀
        ArrayList<String> ignoreSuffix = new ArrayList<>();
        ignoreSuffix.add("_test");
        ProcessConfig processConfig = ProcessConfig.builder()
                //忽略表名
                .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();
    }

}

5.文档类型说明

定位到这个方法

  EngineConfig engineConfig = EngineConfig.builder()
                //生成文件路径
                .fileOutputDir(System.getProperty("user.dir") + "/src/main/resources/sqlfile/")
                //打开目录
                .openOutputDir(true)
                //文件类型
                .fileType(EngineFileType.HTML)
                //生成模板实现
                .produceType(EngineTemplateType.freemarker).build();

.fileType(EngineFileType.HTML)

这表示生成html格式的说明文档

一共有三种类型的说明文档可以生成

html
md
word

下面是对应的枚举类源码(了解即可)

//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by Fernflower decompiler)
//

package cn.smallbun.screw.core.engine;

import java.io.Serializable;

public enum EngineFileType implements Serializable {
    HTML(".html", "documentation_html", "HTML文件"),
    WORD(".doc", "documentation_word", "WORD文件"),
    MD(".md", "documentation_md", "Markdown文件");

    private String fileSuffix;
    private String templateNamePrefix;
    private String desc;

    private EngineFileType(String type, String templateFile, String desc) {
        this.fileSuffix = type;
        this.templateNamePrefix = templateFile;
        this.desc = desc;
    }

    public String getFileSuffix() {
        return this.fileSuffix;
    }

    public void setFileSuffix(String fileSuffix) {
        this.fileSuffix = fileSuffix;
    }

    public String getTemplateNamePrefix() {
        return this.templateNamePrefix;
    }

    public void setTemplateNamePrefix(String templateNamePrefix) {
        this.templateNamePrefix = templateNamePrefix;
    }

    public String getDesc() {
        return this.desc;
    }

    public void setDesc(String desc) {
        this.desc = desc;
    }
}

6.需要注意的问题

生成后文档乱码？

MySQL：URL加入?characterEncoding=UTF-8。
Caused by: java.lang.NoSuchFieldError: VERSION_2_3_30？

检查项目freemarker依赖，这是由于版本过低造成的，升级版本为2.3.30即可。
java.lang.AbstractMethodError: oracle.jdbc.driver.T4CConnection.getSchema()Ljava/lang/String;

这是因为oracle驱动版本过低造成的，删除或屏蔽目前驱动版本，驱动添加升级为以下版本：
MySQL数据库表和列字段有说明、生成文档没有说明？

URL链接加入useInformationSchema=true即可。
java.lang.AbstractMethodError: com.mysql.jdbc.JDBC4Connection.getSchema()Ljava/lang/String;

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

个人csdn博客网址:https://blog.csdn.net/shaoming314

不会打字314

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
3
评论
工具库一键生成数据库说明文档

一键生成数据库文档参考网址:https://mp.weixin.qq.com/s?__biz=MzI4Njc5NjM1NQ==&mid=2247501250&idx=1&sn=4908cc0df374ff99bf89e27cb5aadd51&chksm=ebd5faeedca273f84a97477d296e48fbb515e65d94a543f2222943fd151e10184d5e526d8a47&mpshare=1&scene=23&sr
复制链接

扫一扫

专栏目录