太方便！Spring Boot整合Screw：高效生成數據庫文檔

作者：Springboot實戰(zhàn)案例錦集 2024-08-13 10:36:25

開發(fā) 前端

文檔提供了一個清晰的數據庫數據模型視圖，讓項目團隊成員（如開發(fā)者、測試人員、運維人員等）都能理解數據如何存儲、字段的含義、數據之間的關系等。

環(huán)境：SpringBoot3.2.5 + Screw1.0.5

1. 簡介

任何一個項目對于維護一份數據庫表結構文檔是至關重要的，總結起來有以下原因：

清晰的數據模型：
文檔提供了一個清晰的數據庫數據模型視圖，讓項目團隊成員（如開發(fā)者、測試人員、運維人員等）都能理解數據如何存儲、字段的含義、數據之間的關系等。

便于溝通和協(xié)作：

文檔是團隊成員之間溝通數據庫結構的重要工具。當需要討論數據模型或進行數據庫變更時，文檔可以作為參考和討論的起點。

支持變更管理：

當數據庫結構需要變更時（如添加新字段、修改字段類型、刪除字段等），文檔可以記錄這些變更，并解釋變更的原因和影響。這有助于團隊成員理解并跟蹤數據庫結構的變化。

便于新成員快速上手：

對于新加入項目的成員，一份詳細的數據庫表結構文檔可以幫助他們快速了解項目的數據模型，減少學習成本。

提高可維護性：

一份維護良好的數據庫表結構文檔可以提高數據庫的可維護性。當出現問題或需要修復時，文檔可以幫助開發(fā)者快速定位問題所在，并找到解決方案。

在編寫數據庫表結構時，需要投入相當的時間，并且存在遺漏或錯誤的風險。而Screw是一款強大的工具，通過簡單的配置，它就能夠自動生成多種數據格式的數據庫表結構文檔，從而節(jié)省時間并確保文檔的準確性和完整性。

2. Screw簡介

2.1 Screw特點

簡潔、輕量、設計良好
多數據庫支持
多種格式文檔
靈活擴展
支持自定義模板

2.2 支持的數據庫

MySQL、MariaDB、TIDB、Oracle、SqlServer、PostgreSQL、Cache DB（2016）

2.3 支持的文檔

html

圖片

具體表

圖片

word

圖片

markdown

圖片

具體表

圖片

3. 實戰(zhàn)案例

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() ;
    //執(zhí)行生成
    new DocumentationExecute(config).execute() ;
  }
}

3.3 測試文檔生成

@SpringBootTest
public class ScrewTest {
  @Resource
  private DatabaseDocComponent doc ;
  @Test
  public void testGenDoc() {
    doc.genDocument() ;
  }
}

在你指定的位置生成了文檔；

圖片

責任編輯：武曉燕來源： Spring全家桶實戰(zhàn)案例源碼