數(shù)據(jù)庫(kù)界的Swagger：一鍵生成數(shù)據(jù)庫(kù)文檔！你不了解一下？
對(duì)于API的文檔，我們有Swagger等工具來(lái)自動(dòng)生成了。但有有一類(lèi)文檔還是常常困擾著我們，那就是數(shù)據(jù)庫(kù)表結(jié)構(gòu)的文檔。相信很多同學(xué)都有過(guò)手寫(xiě)數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔 的經(jīng)歷吧？常規(guī)操作就是一通無(wú)腦的 CV 大法，產(chǎn)出一份小幾十頁(yè)的 Word 文檔。
那么，是否有什么工具，可以幫我們偷懶高效的自動(dòng) 生成數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔呢？
還真有！下面就來(lái)介紹這樣一個(gè)工具：screw！
2. screw 簡(jiǎn)介
screw 是一個(gè)簡(jiǎn)潔好用的數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔的生成工具 ，支持 MySQL、Oracle、PostgreSQL 等主流的關(guān)系數(shù)據(jù)庫(kù)。
screw 的倉(cāng)庫(kù)地址是 https://github.com/pingfangushi/screw，感興趣的胖友，可以研究一波。
生成的文檔有 HTML、Word、Markdown 三種格式 ，示例如下圖所示：
| 格式 | 圖 |
|---|---|
| HTML |  |
| Word |  |
| Markdown |  |
3. 快速入門(mén)
screw 有兩種方式 來(lái)生成文檔，通過(guò) Java 代碼 或者 Maven 插件 。
下面，我們來(lái)分別快速入門(mén)下。
3.1 使用 Java 代碼的方式
創(chuàng)建 lab-70-db-doc-screw-01 示例項(xiàng)目，使用 screw 的 Java 代碼 的方式，生成文檔。
示例示例
3.1.1 引入依賴(lài)
在 pom.xml 文件中，引入 screw 的依賴(lài) screw-core。
<?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">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-01</artifactId>
<dependencies>
<!-- screw 庫(kù)，簡(jiǎn)潔好用的數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔生成器 -->
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-core</artifactId>
<version>1.0.5</version>
</dependency>
<!-- 數(shù)據(jù)庫(kù)連接 -->
<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.22</version>
</dependency>
</dependencies>
</project>
依賴(lài) HikariCP 和 mysql-connector-java 是為了連接 MySQL 數(shù)據(jù)庫(kù)。
創(chuàng)建 ScrewMain 類(lèi)，使用 screw 生成文檔。代碼如下：
public class ScrewMain {
private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
private static final String DB_NAME = "mall_system";
private static final String DB_USERNAME = "root";
private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
private static final EngineFileType FILE_OUTPUT_TYPE = EngineFileType.HTML; // 可以設(shè)置 Word 或者 Markdown 格式
private static final String DOC_FILE_NAME = "數(shù)據(jù)庫(kù)文檔";
private static final String DOC_VERSION = "1.0.0";
private static final String DOC_DESCRIPTION = "文檔描述";
public static void main(String[] args) {
// 創(chuàng)建 screw 的配置
Configuration config = Configuration.builder()
.version(DOC_VERSION) // 版本
.description(DOC_DESCRIPTION) // 描述
.dataSource(buildDataSource()) // 數(shù)據(jù)源
.engineConfig(buildEngineConfig()) // 引擎配置
.produceConfig(buildProcessConfig()) // 處理配置
.build();
// 執(zhí)行 screw，生成數(shù)據(jù)庫(kù)文檔
new DocumentationExecute(config).execute();
}
/**
* 創(chuàng)建數(shù)據(jù)源
*/
private static DataSource buildDataSource() {
// 創(chuàng)建 HikariConfig 配置類(lèi)
HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
hikariConfig.setUsername(DB_USERNAME);
hikariConfig.setPassword(DB_PASSWORD);
hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 設(shè)置可以獲取 tables remarks 信息
// 創(chuàng)建數(shù)據(jù)源
return new HikariDataSource(hikariConfig);
}
/**
* 創(chuàng)建 screw 的引擎配置
*/
private static EngineConfig buildEngineConfig() {
return EngineConfig.builder()
.fileOutputDir(FILE_OUTPUT_DIR) // 生成文件路徑
.openOutputDir(false) // 打開(kāi)目錄
.fileType(FILE_OUTPUT_TYPE) // 文件類(lèi)型
.produceType(EngineTemplateType.freemarker) // 文件類(lèi)型
.fileName(DOC_FILE_NAME) // 自定義文件名稱(chēng)
.build();
}
/**
* 創(chuàng)建 screw 的處理配置，一般可忽略
* 指定生成邏輯、當(dāng)存在指定表、指定表前綴、指定表后綴時(shí)，將生成指定表，其余表不生成、并跳過(guò)忽略表配置
*/
private static ProcessConfig buildProcessConfig() {
return ProcessConfig.builder()
.designatedTableName(Collections.<String>emptyList()) // 根據(jù)名稱(chēng)指定表生成
.designatedTablePrefix(Collections.<String>emptyList()) //根據(jù)表前綴生成
.designatedTableSuffix(Collections.<String>emptyList()) // 根據(jù)表后綴生成
.ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
.ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前綴
.ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后綴
.build();
}
}
代碼比較簡(jiǎn)單，胖友看看注釋即可。
比較重要的變量，已經(jīng)抽取成靜態(tài) 變量，胖友看著修改哈。
3.1.3 簡(jiǎn)單測(cè)試
執(zhí)行 ScrewMain 程序，進(jìn)行文檔的生成。這里我們生成的是 HTML 文檔，效果如下圖所示：
HTML 文檔
3.2 使用 Maven 插件的方式
創(chuàng)建 lab-70-db-doc-screw-02 示例項(xiàng)目，使用 screw 的 Maven 插件 的方式，生成文檔。
示例示例
3.2.1 引入插件
在 pom.xml 文件中，引入 screw 的插件 screw-maven-plugin。
<?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">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-02</artifactId>
<build>
<plugins>
<plugin>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-maven-plugin</artifactId>
<version>1.0.5</version>
<dependencies>
<!-- 數(shù)據(jù)庫(kù)連接 -->
<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.22</version>
</dependency>
</dependencies>
<configuration>
<!-- 數(shù)據(jù)庫(kù)相關(guān)配置 -->
<driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
<jdbcUrl>jdbc:mysql://400-infra.server.iocoder.cn:3306/mall_system</jdbcUrl>
<username>root</username>
<password>3WLiVUBEwTbvAfsh</password>
<!-- screw 配置 -->
<fileType>HTML</fileType>
<title>數(shù)據(jù)庫(kù)文檔</title> <!--標(biāo)題-->
<fileName>測(cè)試文檔名稱(chēng)</fileName> <!--文檔名稱(chēng) 為空時(shí):將采用[數(shù)據(jù)庫(kù)名稱(chēng)-描述-版本號(hào)]作為文檔名稱(chēng)-->
<description>數(shù)據(jù)庫(kù)文檔生成</description> <!--描述-->
<version>${project.version}</version> <!--版本-->
<openOutputDir>false</openOutputDir> <!--打開(kāi)文件輸出目錄-->
<produceType>freemarker</produceType> <!--生成模板-->
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Maven 插件的配置項(xiàng) 比較少，胖友按需修改下 <configuration/> 即可。
執(zhí)行 screw-maven-plugin 插件，會(huì)在 doc 目錄下生成文檔。如下圖所示：
執(zhí)行 Maven 插件
4. 生成實(shí)體類(lèi)
screw 的實(shí)現(xiàn)原理，是基于數(shù)據(jù)庫(kù)中的表結(jié)構(gòu) ，生成對(duì)應(yīng)的文檔。
那么，是否可以自動(dòng) 生成 Java 實(shí)體類(lèi)呢？答案是可以的，在 screw-extension 項(xiàng)目中，拓展 提供了該功能。
這樣，日常開(kāi)發(fā)中，在我們完成數(shù)據(jù)庫(kù)的建表 之后，可以直接生成對(duì)應(yīng)的 Java 實(shí)體類(lèi)，避免枯燥的重復(fù)勞動(dòng)。
下面，我們來(lái)快速入門(mén)下。創(chuàng)建 lab-70-db-doc-screw-03 示例項(xiàng)目，使用 screw 的 Java 代碼 的方式，生成 Java 實(shí)體類(lèi)。
示例示例
4.1 引入依賴(lài)
在 pom.xml 文件中，額外 引入 screw 的依賴(lài) screw-extension。
<?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">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-03</artifactId>
<dependencies>
<!-- screw 庫(kù)，簡(jiǎn)潔好用的數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔生成器 -->
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-core</artifactId>
<version>1.0.5</version>
</dependency>
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-extension</artifactId>
<version>1.0.5</version>
</dependency>
<!-- 數(shù)據(jù)庫(kù)連接 -->
<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.22</version>
</dependency>
</dependencies>
</project>
友情提示：由于
screw-extension項(xiàng)目處于初步開(kāi)發(fā)階段，暫時(shí)未將該依賴(lài)推到 Maven 中央倉(cāng)庫(kù)，所以需要自己克隆項(xiàng)目，進(jìn)行編譯打包到本地。
4.2 ScrewMain
創(chuàng)建 ScrewMain 類(lèi)，使用 screw 生成 Java 實(shí)體類(lèi)。代碼如下：
public class ScrewMain {
private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
private static final String DB_NAME = "mall_system";
private static final String DB_USERNAME = "root";
private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
private static final String JAVA_CLASS_PACKAGE = "cn.iocoder.dataobject";
public static void main(String[] args) {
// 創(chuàng)建 screw 的配置
PojoConfiguration config = PojoConfiguration.builder()
.path(FILE_OUTPUT_DIR) // 生成 POJO 相關(guān)的目錄
.packageName(JAVA_CLASS_PACKAGE) // 包名
.nameStrategy(new HumpNameStrategy()) // 包名策略
.useLombok(false) // 是否使用 Lombok
.dataSource(buildDataSource()) // 數(shù)據(jù)源
.processConfig(buildProcessConfig()) // 處理配置
.build();
// 執(zhí)行 screw，生成 POJO 實(shí)體類(lèi)
new PojoExecute(config).execute();
}
/**
* 創(chuàng)建數(shù)據(jù)源
*/
private static DataSource buildDataSource() {
// 創(chuàng)建 HikariConfig 配置類(lèi)
HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
hikariConfig.setUsername(DB_USERNAME);
hikariConfig.setPassword(DB_PASSWORD);
hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 設(shè)置可以獲取 tables remarks 信息
// 創(chuàng)建數(shù)據(jù)源
return new HikariDataSource(hikariConfig);
}
/**
* 創(chuàng)建 screw 的處理配置，一般可忽略
* 指定生成邏輯、當(dāng)存在指定表、指定表前綴、指定表后綴時(shí)，將生成指定表，其余表不生成、并跳過(guò)忽略表配置
*/
private static ProcessConfig buildProcessConfig() {
return ProcessConfig.builder()
.designatedTableName(Collections.<String>emptyList()) // 根據(jù)名稱(chēng)指定表生成
.designatedTablePrefix(Collections.<String>emptyList()) //根據(jù)表前綴生成
.designatedTableSuffix(Collections.<String>emptyList()) // 根據(jù)表后綴生成
.ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
.ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前綴
.ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后綴
.build();
}
}
代碼比較簡(jiǎn)單，胖友看看注釋即可。不同于上面的快速入門(mén)，這里我們使用 PojoConfiguration 作為配置類(lèi)，使用 PojoExecute 作為執(zhí)行器。
比較重要的變量，已經(jīng)抽取成靜態(tài) 變量，胖友看著修改哈。
如果您正在學(xué)習(xí)Spring Boot，推薦一個(gè)連載多年還在繼續(xù)更新的免費(fèi)教程：http://blog.didispace.com/spring-boot-learning-2x/
4.3 簡(jiǎn)單測(cè)試
執(zhí)行 ScrewMain 程序，進(jìn)行 Java 實(shí)體類(lèi)的生成。效果如下圖所示：
Java 實(shí)體類(lèi)
生成的 Java 實(shí)體類(lèi)的成員屬性 還不太正確，需要等待作者進(jìn)行下修復(fù)。
666. 彩蛋
至此，我們已經(jīng)完成 screw 的學(xué)習(xí)，一起來(lái)簡(jiǎn)單總結(jié)下：
screw 支持生成數(shù)據(jù)庫(kù)表結(jié)構(gòu)文檔 ，通過(guò) Java 代碼或者 Maven 插件的方式。 screw 支持生成 Java 實(shí)體類(lèi) ，通過(guò) screw-extension提供。
初略喵了下 screw 的代碼，總體代碼量在 5000+ 行，核心代碼在 2000 行左右。項(xiàng)目分層干凈，代碼注釋完成，胖友可以選擇閱讀了解下。這樣，我們可以根據(jù)我們實(shí)際項(xiàng)目的需要，進(jìn)行二次開(kāi)發(fā) 。
往期推薦
技術(shù)交流群最近有很多人問(wèn)，有沒(méi)有讀者交流群，想知道怎么加入。加入方式很簡(jiǎn)單，有興趣的同學(xué)，只需要點(diǎn)擊下方卡片，回復(fù)“加群“，即可免費(fèi)加入我們的高質(zhì)量技術(shù)交流群！
點(diǎn)擊閱讀原文，送你免費(fèi)Spring Boot教程！