Contents
1. screw开源项目简介
1.1 screw是什么
一句话简介:screw是一个简洁好用的数据库表结构文档生成器
作者开发缘由:在企业级开发中、我们经常会有编写数据库表结构文档的时间付出,从业以来,待过几家企业,关于数据库表结构文档状态:要么没有、要么有、但都是手写、后期运维开发,需要手动进行维护到文档中,很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人。
我使用它的缘由:以前都是用Word来维护公司项目的数据库设计文档,后续每次修改数据库都要记录到文档中,太过麻烦,而且合作开发过程中可能会有的同事更改了数据库而没有及时记入文档,为后续的维护带来了麻烦。
Github项目地址:screw(内置使用教程及常见问题的解决方法,本文内容大多摘自于此)
1.2 screw的特点及支持
特点:[1] 简洁、轻量、设计良好 [2] 多数据库支持 [3] 多种格式文档 [4] 灵活扩展 [5] 支持自定义模板
数据库支持:MySQL、MariaDB、TIDB、Oracle、SqlServer、PostgreSQL、Cache DB
文档生成支持:html、md、word
2. 如何使用screw生成数据库设计文档
2.1 配置Maven开发环境
(1)maven下载安装
[1] 官网下载Maven:Apache Maven
[2] 将下载的 apache-maven-3.6.3-bin.zip移动到文件夹内解压
(2)maven环境变量配置
[1] 右键“计算机”,选择“属性”,之后点击“高级系统设置”,点击“环境变量”
[2] 环境变量配置:
- 新建系统变量 MAVEN_HOME 变量值: D:\Maven\apache-maven-3.6.3
-
编辑系统变量 Path 添加变量值: ;%MAVEN_HOME%\bin
[3] 验证:在cmd界面输入: mvn --version
(3)maven设置
修改maven的settings.xml配置文件的profiles标签为:
1 2 3 4 5 6 7 8 9 10 11 12 |
<profile> <id>jdk‐1.8</id> <activation> <activeByDefault>true</activeByDefault> <jdk>1.8</jdk> </activation> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <maven.compiler.compilerVersion>1.8</maven.compiler.compilerVersion> </properties> </profile> |
(4)将maven整合进IDEA
打开IDEA——Configure——设置——构建,执行,部署——构建工具——Maven——Maven home directory、User settings file、Local repoository(自己新建),这三项选中自己安装的那个。
2.2 创建SpringBoot项目
此处使用Spring Initializer快速创建Springboot项目,如果你手上有现成的项目,拿来直接用即可,就不必重新创建了。
[1] 创建Spring Initializr工程
[2] 填写Project Metadata相关信息
[3] 根据需要选择模块
[4] 进去后右下角选择“Enable Auto-import”(更改配置文件时IEDA会自动下载导入所需要的jar包)
2.3 配置screw并使用其生成文档
官网提供了“普通方式”和“Maven插件”两种使用方式,本文只讲“普通方式”的使用方法,以最常见的MySQL和Oracle为例。
(1)配置Maven依赖
将以下代码添加到pom.xml文件中,然后打开Maven窗口,点击Lifecycle里的install安装依赖包
注:screw核心的版本号填最新的,点此查看最新版本号
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 |
<!-- screw核心 --> <dependency> <groupId>cn.smallbun.screw</groupId> <artifactId>screw-core</artifactId> <version>1.0.5</version> </dependency> <!-- 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> <!--oracle driver--> <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> |
(2)编写数据库设计文档的生成代码
在test目录下创建一个测试类 ScrewConfig.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 89 90 91 92 |
package com.example.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 com.zaxxer.hikari.HikariConfig; import com.zaxxer.hikari.HikariDataSource; import javax.sql.DataSource; import java.util.ArrayList; public class ScrewConfig { /** * 数据库设计文档生成 */ static void documentGeneration() { //数据源 HikariConfig hikariConfig = new HikariConfig(); //数据库driver hikariConfig.setDriverClassName("oracle.jdbc.driver.OracleDriver"); //oracle //hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver"); //mysql //数据库URL hikariConfig.setJdbcUrl("jdbc:oracle:thin:@IP地址:端口:数据库名?useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=CTT"); //hikariConfig.setJdbcUrl("jdbc:mysql://IP地址:端口/数据库名?useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=CTT"); //数据库用户名 hikariConfig.setUsername("Username"); //数据库用户密码 hikariConfig.setPassword("Password"); //设置可以获取tables remarks信息 hikariConfig.addDataSourceProperty("useInformationSchema", "true"); hikariConfig.setMinimumIdle(2); hikariConfig.setMaximumPoolSize(5); DataSource dataSource = new HikariDataSource(hikariConfig); //生成配置 EngineConfig engineConfig = EngineConfig.builder() //生成文件路径 .fileOutputDir("E:/crater/") //打开目录 .openOutputDir(true) //文件类型 HTML、MD、WORD .fileType(EngineFileType.HTML) //生成模板实现 .produceType(EngineTemplateType.freemarker) //自定义文件名称 .fileName("demo").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") //数据源 .dataSource(dataSource) //生成配置 .engineConfig(engineConfig) //生成配置 .produceConfig(processConfig) .build(); //执行生成 new DocumentationExecute(config).execute(); } public static void main(String[] args) { documentGeneration(); } } |
必须修改项:数据库driver、数据库URL、数据库用户名、数据库用户密码
可选修改项:生成文件路径、文件类型、自定义文件名称、版本
(3)运行screw生成数据库设计文档
直接运行 ScrewConfig.java代码,即可生成数据库设计文档。
3. 常见问题及解决方案
[1] 生成后文档乱码?
MySQL:URL加入 ?characterEncoding=UTF-8。
[2] Caused by: java.lang.NoSuchFieldError: VERSION_2_3_30?
检查项目 freemarker依赖,这是由于版本过低造成的,升级版本为 2.3.30即可。
[3] 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> |
[4] MySQL数据库表和列字段有说明、生成文档没有说明?
URL链接加入 useInformationSchema=true即可。
[5] java.lang.AbstractMethodError: com.mysql.jdbc.JDBC4Connection.getSchema()Ljava/lang/String;
这是因为mysql驱动版本过低造成的,升级mysql驱动版本为最新即可。
4. 参考资料
[1] screw:简洁好用的数据库表结构文档生成器 from Github
[2] 尚硅谷-使用向导快速创建Springboot项目 from Bilibili
[3] 实用!一键生成数据库文档,堪称数据库界的Swagger from 51CTO