一、简介
在企业级开发中,我们经常需要编写数据库表结构文档的。从业以来,待过几家企业,关于数据库表结构文档状态:要么没有、要么有、但都是手写、后期运维开发,需要手动进行维护到文档中,很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人。为了不重复 CV 操作,抱着一丝希望开始在GitHub
里找,看看有没有什么工具可以用,结果就真的发现了宝藏,screw(螺丝钉),居然可以生成数据库文档,优秀啊~。
screw
提供了多种文件类型和多种模板的自动生成工具,如下所示:
- 支持数据库类型
- MySQL、MariaDB、TIDB、Oracle、SqlServer、PostgreSQL等,其他正在开发中
- 文件类型
EngineFileType
枚举类中提供三种类型:HTML
、WORD
、MD
。
- 模板类型
EngineTemplateType
枚举类中提供两种类型:freemarker
、velocity
。
二、添加必需依赖
创建SpringBoot项目,添加相关依赖:
<properties>
<!--java 版本-->
<java.version>1.8</java.version>
<!--项目编码-->
<project.encoding>UTF-8</project.encoding>
<project.build.sourceencoding>UTF-8</project.build.sourceencoding>
<project.reporting.outputencoding>UTF-8</project.reporting.outputencoding>
<java.source.version>1.8</java.source.version>
<java.target.version>1.8</java.target.version>
<main.user.dir>${user.dir}</main.user.dir>
<mysql-connector-java.version>8.0.22</mysql-connector-java.version>
<hikaricp.version>3.4.5</hikaricp.version>
<screw.version>1.0.5</screw.version>
</properties>
<dependencies>
<!--数据库文档核心依赖-->
<!-- https://mvnrepository.com/artifact/cn.smallbun.screw/screw-core -->
<dependency>
<groupid>cn.smallbun.screw</groupid>
<artifactid>screw-core</artifactid>
<version>${screw.version}</version>
</dependency>
<dependency>
<groupid>mysql</groupid>
<artifactid>mysql-connector-java</artifactid>
<version>${mysql-connector-java.version}</version>
</dependency>
<!-- HikariCP 号称性能最出色的数据库连接池 -->
<!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
<dependency>
<groupid>com.zaxxer</groupid>
<artifactid>HikariCP</artifactid>
<version>${HikariCP.version}</version>
</dependency>
</dependencies>
三、代码部分
-
通过自定义代码配置文档生成
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; import java.util.Arrays; import java.util.List; public class ScrewApplication { /** * 文档生成 * @param fileOutputDir 文件路径 * @param fileName 文件名称 */ public static void documentGeneration(String fileOutputDir, String fileName) { // 生成文件配置 EngineConfig engineConfig = EngineConfig.builder() // 生成文件路径 .fileOutputDir(fileOutputDir) // 打开目录 .openOutputDir(true) // 文件类型 .fileType(EngineFileType.MD) // 生成模板实现 .produceType(EngineTemplateType.freemarker) // 自定义文件名称 .fileName(fileName).build(); // 生成文档配置(包含以下自定义版本号、描述等配置连接) Configuration config = Configuration.builder() // 版本 .version("1.0.0") // 生成文档信息描述 .description("数据库设计文档生成") // 数据源 .dataSource(getDataSource()) // 生成配置 .engineConfig(engineConfig) // 生成配置 .produceConfig(getProcessConfig()) .build(); // 执行生成 new DocumentationExecute(config).execute(); } /** * 获取数据源信息 * * @return 返回数据源信息 */ private static DataSource getDataSource() { //数据源 HikariConfig hikariConfig = new HikariConfig(); hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver"); hikariConfig.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/database"); hikariConfig.setUsername("root"); hikariConfig.setPassword("password"); // 设置可以获取tables remarks信息 hikariConfig.addDataSourceProperty("useInformationSchema", "true"); hikariConfig.setMinimumIdle(2); hikariConfig.setMaximumPoolSize(5); DataSource dataSource = new HikariDataSource(hikariConfig); return dataSource; } /** * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时,将生成指定表,其余表不生成、并跳过忽略表配置 * * @return 生成表配置 */ private 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<string>()) // 根据表前缀生成 .designatedTablePrefix(new ArrayList<string>()) // 根据表后缀生成 .designatedTableSuffix(new ArrayList<string>()) // 忽略表名 .ignoreTableName(ignoreTableName) // 忽略表前缀 .ignoreTablePrefix(ignorePrefix) // 忽略表后缀 .ignoreTableSuffix(ignoreSuffix).build(); } }
-
如果是SpringBoot项目的话,先在application.yml里面配置数据库连接信息
spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://127.0.0.1:3306/database username: root password: password xa: properties: useInformationSchema: true
public class ScrewApplication { @Autowired ApplicationContext applicationContext; /** * 文档生成 * @param fileOutputDir 文件路径 * @param fileName 文件名称 */ public static void documentGeneration(String fileOutputDir, String fileName) { // 数据源信息 DataSource dataSource = applicationContext.getBean(DataSource.class); // 生成文件配置 EngineConfig engineConfig = EngineConfig.builder() // 生成文件路径 .fileOutputDir(fileOutputDir) // 打开目录 .openOutputDir(true) // 文件类型 .fileType(EngineFileType.MD) // 生成模板实现 .produceType(EngineTemplateType.freemarker) // 自定义文件名称 .fileName(fileName).build(); // 生成文档配置(包含以下自定义版本号、描述等配置连接) Configuration config = Configuration.builder() // 版本 .version("1.0.0") // 生成文档信息描述 .description("数据库设计文档生成") // 数据源 .dataSource(dataSource) // 生成配置 .engineConfig(engineConfig) // 生成配置 .produceConfig(getProcessConfig()) .build(); // 执行生成 new DocumentationExecute(config).execute(); } /** * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时,将生成指定表,其余表不生成、并跳过忽略表配置 * * @return 生成表配置 */ private 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<string>()) // 根据表前缀生成 .designatedTablePrefix(new ArrayList<string>()) // 根据表后缀生成 .designatedTableSuffix(new ArrayList<string>()) // 忽略表名 .ignoreTableName(ignoreTableName) // 忽略表前缀 .ignoreTablePrefix(ignorePrefix) // 忽略表后缀 .ignoreTableSuffix(ignoreSuffix).build(); } }
-
通过插件的形式生成文档
<build> <plugins> <plugin> <groupid>cn.smallbun.screw</groupid> <artifactid>screw-maven-plugin</artifactid> <version>${screw.version}</version> <dependencies> <!-- HikariCP --> <dependency> <groupid>com.zaxxer</groupid> <artifactid>HikariCP</artifactid> <version>${HikariCP.version}</version> </dependency> <!--mysql driver--> <dependency> <groupid>mysql</groupid> <artifactid>mysql-connector-java</artifactid> <version>${mysql-connector-java.version}</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/database</jdbcurl> <!--生成文件类型--> <filetype>MD</filetype> <!-- 生成文件路径,自己mac本地的地址,这里需要自己更换下路径 --> <fileoutputdir>/Users/dllwh/Downloads/</fileoutputdir> <!--打开文件输出目录--> <openoutputdir>true</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>
配置完以后在 maven project->screw 双击执行ok。