环境:SpringBoot3.2.5 + Screw1.0.5
1. 简介
任何一个项目对于维护一份数据库表结构文档是至关重要的,总结起来有以下原因:
- 清晰的数据模型:
文档提供了一个清晰的数据库数据模型视图,让项目团队成员(如开发者、测试人员、运维人员等)都能理解数据如何存储、字段的含义、数据之间的关系等。
便于沟通和协作:
- 文档是团队成员之间沟通数据库结构的重要工具。当需要讨论数据模型或进行数据库变更时,文档可以作为参考和讨论的起点。
支持变更管理:
- 当数据库结构需要变更时(如添加新字段、修改字段类型、删除字段等),文档可以记录这些变更,并解释变更的原因和影响。这有助于团队成员理解并跟踪数据库结构的变化。
便于新成员快速上手:
- 对于新加入项目的成员,一份详细的数据库表结构文档可以帮助他们快速了解项目的数据模型,减少学习成本。
提高可维护性:
- 一份维护良好的数据库表结构文档可以提高数据库的可维护性。当出现问题或需要修复时,文档可以帮助开发者快速定位问题所在,并找到解决方案。
在编写数据库表结构时,需要投入相当的时间,并且存在遗漏或错误的风险。而Screw是一款强大的工具,通过简单的配置,它就能够自动生成多种数据格式的数据库表结构文档,从而节省时间并确保文档的准确性和完整性。
2. Screw简介
2.1 Screw特点
- 简洁、轻量、设计良好
- 多数据库支持
- 多种格式文档
- 灵活扩展
- 支持自定义模板
2.2 支持的数据库
MySQL、MariaDB、TIDB、Oracle、SqlServer、PostgreSQL、Cache DB(2016)
2.3 支持的文档
html
目录
图片
具体表
图片
word
图片
markdown
目录
图片
具体表
图片
3. 实战案例
3.1 引入Screw依赖
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-core</artifactId>
<version>1.0.5</version>
</dependency>
3.2 定义Screw可配置项
public class ScrewProperties {
/**数据库脚本版本*/
private String version ;
/**标题*/
private String title ;
/**数据库脚本说明*/
private String desc ;
/**机构*/
private String org ;
/**机构网址*/
private String orgUrl ;
/**是否启用*/
private boolean enabled = false ;
private boolean autoGen = false ;
/**全局配置*/
private ScrewConfig config = new ScrewConfig() ;
/**忽略表设置*/
private TableConfig tables = new TableConfig() ;
public static class TableConfig {
/**指定生成的表*/
private List<String> designatedTables = new ArrayList<>() ;
/**指定生成表的前缀*/
private List<String> designatedTablePrefixs = new ArrayList<>() ;
/**指定生成表的后缀*/
private List<String> designatedTableSuffixs = new ArrayList<>() ;
/**忽略表*/
private List<String> ignoreTables = new ArrayList<>() ;
/**忽略表前缀*/
private List<String> ignoreTablePrefixs = new ArrayList<>() ;
/**忽略表后缀*/
private List<String> ignoreTableSuffixs = new ArrayList<>() ;
}
public static class ScrewConfig {
/**文档输出目录*/
private String fileOutputDir ;
/**生成完成是否打开目录*/
private boolean openOutputDir = true ;
/**文档类型*/
private EngineFileType fileType = EngineFileType.HTML;
/**文档生成模版类型*/
private EngineTemplateType produceType = EngineTemplateType.freemarker ;
/**文档名称*/
private String fileName = "数据库设计文档" ;
}
}
生成文档组件
@Component
public class DatabaseDocComponent {
private final DataSource dataSource ;
private final ScrewProperties screwProperties ;
public DatabaseDocComponent(DataSource dataSource, ScrewProperties screwProperties) {
this.dataSource = dataSource ;
this.screwProperties = screwProperties ;
}
public void genDocument() {
//生成配置
EngineConfig engineConfig = EngineConfig.builder()
// 生成文件路径
.fileOutputDir(screwProperties.getConfig().getFileOutputDir())
// 打开目录
.openOutputDir(screwProperties.getConfig().isOpenOutputDir())
// 文件类型
.fileType(screwProperties.getConfig().getFileType())
// 生成模板实现
.produceType(screwProperties.getConfig().getProduceType())
// 自定义文件名称
.fileName(screwProperties.getConfig().getFileName()).build();
ProcessConfig processConfig = ProcessConfig.builder()
//指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时,将生成指定表,其余表不生成、并跳过忽略表配置
//根据名称指定表生成
.designatedTableName(screwProperties.getTables().getDesignatedTables())
//根据表前缀生成
.designatedTablePrefix(screwProperties.getTables().getDesignatedTablePrefixs())
//根据表后缀生成
.designatedTableSuffix(screwProperties.getTables().getDesignatedTableSuffixs())
//忽略表名
.ignoreTableName(screwProperties.getTables().getIgnoreTables())
//忽略表前缀
.ignoreTablePrefix(screwProperties.getTables().getIgnoreTablePrefixs())
//忽略表后缀
.ignoreTableSuffix(screwProperties.getTables().getIgnoreTableSuffixs()).build();
//配置
Configuration config = Configuration.builder()
//版本
.version(screwProperties.getVersion())
.title(screwProperties.getTitle())
//描述
.description(screwProperties.getDesc())
.organization(screwProperties.getOrg())
.organizationUrl(screwProperties.getOrgUrl())
//数据源
.dataSource(dataSource)
//生成配置
.engineConfig(engineConfig)
//生成配置
.produceConfig(processConfig)
.build() ;
//执行生成
new DocumentationExecute(config).execute() ;
}
}
3.3 测试文档生成
@SpringBootTest
public class ScrewTest {
@Resource
private DatabaseDocComponent doc ;
@Test
public void testGenDoc() {
doc.genDocument() ;
}
}
在你指定的位置生成了文档;
图片
图片