记一次使用 screw 生成数据库设计文档

系统管理员 2022-10-28 14:21 181阅读 0赞

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70]  
网址：[https://gitee.com/leshalv/screw][https_gitee.com_leshalv_screw]

# 简介 #

在企业级开发中、我们经常会有编写数据库表结构文档的时间付出，从业以来，待过几家企业，关于数据库表结构文档状态：要么没有、要么有、但都是手写、后期运维开发，需要手动进行维护到文档中，很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人，于是萌生了要自己写一个插件工具的想法，但由于自己前期在程序设计上没有很多造诣，且能力偏低，有想法并不能很好实现，随着工作阅历的增加，和知识的不断储备，终于在2020年的3月中旬开始进行编写，4月上旬完成初版，想完善差不多在开源，但由于工作太忙，业余时间不足，没有在进行完善，到了6月份由于工作原因、频繁设计和更改数据库、经常使用自己写的此插件、节省了很多时间，解决了很多问题 ，在仅有且不多的业余时间中、进行开源准备，于2020年6月22日，开源，欢迎大家使用、建议、并贡献。  
  关于名字，想一个太难了，好在我这个聪明的小脑瓜灵感一现，怎么突出它的小，但重要呢？从小就学过雷锋的螺丝钉精神，摘自雷锋日记：虽然是细小的螺丝钉，是个细微的小齿轮，然而如果缺了它，那整个的机器就无法运转了，慢说是缺了它，即使是一枚小螺丝钉没拧紧，一个小齿轮略有破损，也要使机器的运转发生故障的…，感觉自己写的这个工具，很有这意味，虽然很小、但是开发中缺了它还不行，于是便起名为screw（螺丝钉）。

# 特点 #

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

# 数据库支持 #

MySQL  
MariaDB  
TIDB  
Oracle  
SqlServer  
PostgreSQL  
Cache DB（2016）

# 文档生成类型 #

html  
word  
markdown

# 使用方式 #

maven 引入依赖

<dependency>
        <groupId>cn.smallbun.screw</groupId>
        <artifactId>screw-core</artifactId>
        <version>${lastVersion}</version>
     </dependency>

# 实际操作（ java 代码形式） #

以下我以 Postgresql 数据库为例，用编写代码的形式来生成文档  
新建 maven spring 项目  
引入相关依赖

<?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 http://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.3.5.RELEASE</version>
            <relativePath/>
        </parent>
    
        <groupId>test</groupId>
        <artifactId>test</artifactId>
        <version>1.0-SNAPSHOT</version>
        
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-test</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.postgresql</groupId>
                <artifactId>postgresql</artifactId>
            </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>2.6.1</version>
            </dependency>
            
            <dependency>
                <groupId>org.dbunit</groupId>
                <artifactId>dbunit</artifactId>
                <version>2.7.0</version>
            </dependency>
        </dependencies>
    </project>

编写代码（此处我选择了 Postgresql 数据库）

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.Test;
    import org.springframework.boot.test.context.SpringBootTest;
    
    import javax.sql.DataSource;
    import java.util.ArrayList;
    
    /**
     * 数据库文档生成工具
     */
    @SpringBootTest
    public class ScrewUtil { 
    
        /**
         * 文档生成
         */
        @Test
        public void documentGeneration() { 
            String fileOutputDir = "【服务器上存放生成文档的物理地址】";
    
            //数据源
            HikariConfig hikariConfig = new HikariConfig();
            hikariConfig.setDriverClassName("org.postgresql.Driver");//数据库启动（此处是 Postgresql 数据库驱动）
            hikariConfig.setJdbcUrl("jdbc:postgresql://【数据库IP】:5432/【数据库名字】?currentSchema=public");
            hikariConfig.setUsername("【数据库用户名】");
            hikariConfig.setPassword("【数据库密码】");
            //设置可以获取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)		//生成 HTML 文档
                    //.fileType(EngineFileType.WORD)	//生成 WORD文档
                    //.fileType(EngineFileType.MD)		//生成 Markdown 文档
                    //生成模板实现
                    .produceType(EngineTemplateType.freemarker)
                    //自定义文件名称
                    .fileName("数据库设计文档 V1.0").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()
                    //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
                    //根据名称指定表生成
                    .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("数据库设计文档 V1.0")
                    //数据源
                    .dataSource(dataSource)
                    //生成配置
                    .engineConfig(engineConfig)
                    //生成配置
                    .produceConfig(processConfig)
                    .build();
            //执行生成
            new DocumentationExecute(config).execute();
        }
    }

运行  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70 1]  
去服务器上存放生成文档的物理地址查看  
![在这里插入图片描述][20210206152759939.png]  
双击 html 文件，浏览器查看  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70 2]

# Maven 插件配置方式 #

<build>
        <plugins>
            <plugin>
                <groupId>cn.smallbun.screw</groupId>
                <artifactId>screw-maven-plugin</artifactId>
                <version>${lastVersion}</version>
                <dependencies>
                    
                    <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>
                <configuration>
                    
                    <username>root</username>
                    
                    <password>password</password>
                    
                    <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                    
                    <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>

# 其它 #

Springboot2.X + screw数据库快速开发文档 [https://my.oschina.net/mdxlcj/blog/4341399][https_my.oschina.net_mdxlcj_blog_4341399]  
实用！一键生成数据库文档，堪称数据库界的Swagger [https://mp.weixin.qq.com/s/nPwFV7DN8Ogg54\_crLlP3g][https_mp.weixin.qq.com_s_nPwFV7DN8Ogg54_crLlP3g]

至此，使用 screw 生成数据库设计文档操作完毕，希望能够对您有所帮助！

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70]: /images/20221024/921c2af288804ef4aeafcc8905c7d707.png
[https_gitee.com_leshalv_screw]: https://gitee.com/leshalv/screw
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70 1]: /images/20221024/31b839bba7784acdad3b60bf03cb4c6e.png
[20210206152759939.png]: /images/20221024/e3e115aba7fe4250b718abe1f9aa3718.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xsd3kxNDI4_size_16_color_FFFFFF_t_70 2]: /images/20221024/d040a7c8fd814680b36e45341ad8642b.png
[https_my.oschina.net_mdxlcj_blog_4341399]: https://my.oschina.net/mdxlcj/blog/4341399
[https_mp.weixin.qq.com_s_nPwFV7DN8Ogg54_crLlP3g]: https://mp.weixin.qq.com/s/nPwFV7DN8Ogg54_crLlP3g