springboot：接手老项目，领导让更新数据库说明文档，如何3分钟完成任务
0 引言
最新在重新整理老项目的文档，其中数据库说明文档上一版更新还是在1年多前，文档中的数据结构说明与当前数据库严重脱节，所以更新数据库说明文档已经是迫在眉睫的事情了。
因为项目是一个比较大型且“年长‘的项目，涉及了多个数据库，N多张表，所以作为一个好（懒）的开发者，一张表一张表手写是不可能，当然可以通过sql导出表结构，但是依然很慢。
能不能有一个工具，能帮我自动生成数据库说明文档，当然是有的，今天我们就来说一说数据库中的swagger——screw组件
1. screw简介
screw是用来生成数据库表结构说明文档的组件，通过引用jar包，通过简单的配置就可以自动生成文档，相当于数据库中的swagger，支持html, word, md三种格式的文档
2. screw使用
1、创建springboot项目，引入依赖：
- 因为我们要作为一个springboot web项目运行，所以引入
spring web - 因为要使用mysql连接驱动器，所以引入
mysql-connector-java screw-core和HikariCP是screw组件使用需要的依赖- 最后，我们需要用单元测试的方式来调用生成文档的方法，所以需要
spring-boot-starter-test依赖
<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>
<!-- 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>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
2、application.yml配置文件配置数据库连接信息，同时开启xa.properties.useInformationSchema，该配置用于开启读取表注释（remarks）信息
spring:
application:
name: datebase_doc_demo
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
name: defaultDataSource
url: jdbc:mysql://localhost:3306/bladex?serverTimezone=UTC
username: root
password: 123456
xa:
properties:
useInformationSchema: true
3、创建生成文档代码
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 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 javax.sql.DataSource;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
@SpringBootTest
class DatebaseDocDemoApplicationTests2 {
@Autowired
private ApplicationContext applicationContext;
@Test
void generateDBDoc2(){
DataSource dataSource = applicationContext.getBean(DataSource.class);
EngineConfig engineConfig = EngineConfig.builder()
//生成文件路径
.fileOutputDir("/Users/wuhanxue/Downloads")
// 打开目录
.openOutputDir(true)
// 文件类型，支持word、md和html
.fileType(EngineFileType.HTML)
//生成模板实现，支持freemarker和velocity
.produceType(EngineTemplateType.freemarker).build();
//生成配置文档
Configuration configuration = Configuration.builder()
.version("1.0.0")
.description("数据库说明文档")
.dataSource(dataSource)
.engineConfig(engineConfig)
.produceConfig(getProcessConfig())
.build();
//执行生成
new DocumentationExecute(configuration).execute();
}
/**
* 配置想要生成的表 + 配置想要忽略的表
* @return
*/
private ProcessConfig getProcessConfig() {
// 忽略表名
List<String> ignoreTable = Arrays.asList("test_xxx");
//忽略表前缀，如忽略a开头的数据库表
List<String> ignorePrefix = Arrays.asList("test_");
//忽略表后缀
List<String> ignoreSuffix = Arrays.asList("_test");
return ProcessConfig.builder()
// 根据名称生成指定表
.designatedTableName(new ArrayList<String>())
// 根据表前缀生成
.designatedTablePrefix(new ArrayList<String>())
// 根据表后缀生成
.designatedTableSuffix(new ArrayList<String>())
// 忽略表名
.ignoreTableName(ignoreTable)
// 忽略表前缀
.ignoreTablePrefix(ignorePrefix)
// 忽略表后缀
.ignoreTableSuffix(ignoreSuffix).build();
}
}
当然这个是需要springboot项目的配置文件配置的，如果你是spring项目引入的，或者其他纯maven项目引入，也可以通过一下代码生成
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.boot.test.context.SpringBootTest;
import javax.sql.DataSource;
import java.util.ArrayList;
@SpringBootTest
class DatebaseDocDemoApplicationTests {
@Test
void generateDBDoc(){
HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
hikariConfig.setJdbcUrl("jdbc:mysql://localhost:3306/bladex?serverTimezone=UTC");
hikariConfig.setUsername("root");
hikariConfig.setPassword("123456");
// 设置可以获取remark信息
hikariConfig.addDataSourceProperty("useInformationSchema","true");
hikariConfig.setMinimumIdle(2);
hikariConfig.setMaximumPoolSize(5);
DataSource dataSource = new HikariDataSource(hikariConfig);
// 生成配置
EngineConfig engineConfig = EngineConfig.builder()
// 生成文件路径
.fileOutputDir("/Users/wuhanxue/Downloads")
// 打开目录 设置为true执行完代码后会自动打开对应路径文件夹
.openOutputDir(true)
// 文件类型,支持三种类型
// .fileType(EngineFileType.HTML)
.fileType(EngineFileType.WORD)
// 生成模板实现
.produceType(EngineTemplateType.freemarker).build();
// 忽略表,这些表不会在文档中生成
ArrayList<String> ignoreTableName = new ArrayList<>();
ignoreTableName.add("test_xxx");
// 忽略表前缀,这些表不会在文档中生成
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();
}
}
4、运行测试
- html格式
- word格式
- md格式
源码
文中源码可在如下地址下载：
git地址
总结
如上所示，我们的数据库说明文档就做完了，当然我在实际项目中的数据库比上述演示的要大的多，但数据库越大，我们省的时间就越多
但是大家也要把握screw组件的适用场景，有的人会觉得它很鸡肋，因为我们实际开发时是先写数据库设计文档，再开发的，但有的场景，比如接手老项目，或者项目迭代比较快的，数据库文档更新不及时时，就可以使用这个组件来帮助我们自动生成文档
这里大家还可以继续做拓展，将生成方法包装为一个接口，通过监控binlog中的DDL语句，来触发接口调用，从而实现自动生成数据库文档，可以通过生成html格式的，放到后台项目中，这样就实现了实时自动更新的数据库说明文档