SpringBoot 整合 Screw 自动生成数据库设计文档实战

温以宁

发布时间：2026-10-15| 6人浏览过

原创

使用 Screw 工具包集成到 SpringBoot 项目中，可快速生成 Word、Markdown 或 HTML 格式的数据库设计文档。通过配置数据源和生成参数，支持自动排除指定表，极大简化文档维护工作。

Screw 工具简介

Screw 是一个基于 Java 的数据库文档生成工具，主要特点包括：

多格式输出：支持生成 Word (.docx)、Markdown (.md) 和 HTML 文件。
灵活配置：支持 FreeMarker 和 Velocity 两种模板引擎，可自定义文档样式。
数据源兼容：原生支持 HikariCP 数据源；使用 Druid 时需注意版本兼容性以避免类型转换错误。
精准控制：支持按表名、表前缀/后缀进行过滤，只生成需要的表结构文档。

一、环境准备与依赖引入

首先在 SpringBoot 项目的 pom.xml 中添加 Screw 的核心依赖。推荐使用较新的稳定版本，此处以 1.0.5 为例：

<!-- 数据库设计文档生成工具 -->
<dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>1.0.5</version>
</dependency>

注意：如果你的项目使用了其他连接池（如 Druid），请确保驱动类名称正确配置，避免启动报错。

二、代码实现步骤

创建一个独立的 Java 类（例如 DatabaseDesignDocUtil）用于执行文档生成任务。以下示例基于 PostgreSQL 数据库，若使用 MySQL 需调整驱动和连接 URL。

第1步：配置数据库连接

使用 HikariConfig 建立数据源连接，关键参数设置如下：

HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("org.postgresql.Driver");
hikariConfig.setJdbcUrl("jdbc:postgresql://39.164.52.80:5432/work_face");
hikariConfig.setUsername("postgres");
hikariConfig.setPassword("POSTGRES");
// 开启获取 tables remarks 信息，确保注释能被读取
hikariConfig.addDataSourceProperty("useInformationSchema", "true");
hikariConfig.setMinimumIdle(2);
hikariConfig.setMaximumPoolSize(5);
DataSource dataSource = new HikariDataSource(hikariConfig);

第2步：配置文档生成规则

通过 EngineConfig 指定输出路径、文件格式及模板类型：

EngineConfig engineConfig = EngineConfig.builder()
        // 生成文件存放路径
        .fileOutputDir("C:\\Users\\tarzan\\Desktop\\doc")
        // 生成完成后自动打开目录
        .openOutputDir(true)
        // 文件类型：WORD, MD, HTML
        .fileType(EngineFileType.WORD)
        // 模板类型：freemarker, velocity
        .produceType(EngineTemplateType.freemarker)
        // 自定义文件名
        .fileName("智能工作面数据库设计文档").build();

第3步：设置表过滤逻辑（可选）

如果不想生成所有表，可以通过 ProcessConfig 忽略特定表：

List<String> ignoreTableName = new ArrayList<>();
ignoreTableName.add("test_user");
ArrayList<String> ignorePrefix = new ArrayList<>();
ignorePrefix.add("test_");
ProcessConfig processConfig = ProcessConfig.builder()
        // 忽略指定表名
        .ignoreTableName(ignoreTableName)
        // 忽略指定前缀的表
        .ignoreTablePrefix(ignorePrefix)
        // 忽略指定后缀的表
        .ignoreTableSuffix(new ArrayList<>())
        .build();

第4步：执行生成

将上述配置组装并执行：

Configuration config = Configuration.builder()
        .version("1.0.0")
        .description("数据库设计文档生成")
        .dataSource(dataSource)
        .engineConfig(engineConfig)
        .produceConfig(processConfig)
        .build();

new DocumentationExecute(config).execute();

三、运行与验证

运行代码：在 IDEA 等编辑器中运行 main 方法。
查看日志：控制台输出执行进度信息，无异常即表示成功。
检查成果：前往指定的 fileOutputDir 目录，即可找到生成的 Word 文档。文档内包含表名、字段、类型、注释等详细信息。

补充：手动导出 MySQL 表结构方案

若无需自动化工具，仅针对 MySQL 数据库，也可通过 Navicat 查询 INFORMATION_SCHEMA.COLUMNS 视图来手动获取字段信息。SQL 如下：

SELECT
    TABLE_NAME AS '表名',
    COLUMN_NAME AS '字段名称',
    COLUMN_TYPE AS '字段类型',
    IF(IS_NULLABLE = 'YES', '是', '否') AS '是否可为空',
    IF(COLUMN_KEY = 'PRI', '是', '否') AS '是否主键',
    COLUMN_COMMENT AS '字段注释'
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = '你的数据库名';

具体操作步骤：