Screw生成数据库文档的3大坑与避坑指南

别再手写数据库文档了！Screw生成神器踩坑实录，一次讲透配置与原理

“又让写数据库文档？表都上百个了，字段密密麻麻……”
你是不是也经历过这种时刻：项目上线前，领导一句轻飘飘的“把库表文档整理一下”，瞬间让你头皮发麻？手敲Markdown？用PowerDesigner导出？还是截图贴Excel？

更离谱的是——改了字段忘了同步文档，线上排查问题对着过时文档抓瞎。这不叫技术债，这叫“文档陷阱”。

直到我遇见 Screw —— 轻量、无侵入、支持多格式（HTML/Word/Markdown）的数据库文档生成工具。本以为是“一键生成，天下太平”，结果第一次运行就翻车：中文乱码、索引缺失、外键没显示……

今天，“北风朝向”带你从零到一，深入Screw的核心机制，剖析三大常见坑点，附带可落地的Spring Boot集成方案和定制化技巧。让你不仅会用，还能用得稳、用得深。

---

为什么是 Screw？对比市面上的“文档工具”

在动手之前，先说清楚：我们为什么选 Screw，而不是 MyBatis-Plus 的文档模块，或者 Swagger 配合 JApiDocs？

工具	优点	缺点
Swagger + JApiDocs	接口即文档，前后端友好	只覆盖API，不解决DB文档
PowerDesigner	功能强大，可视化建模	商业软件，难以自动化
Liquibase / Flyway	版本化SQL管理	输出非结构化文档
Screw ✅	简单、轻量、可集成CI/CD、支持主流ORM	社区小，文档少，易踩坑

🔍 关键洞察：Screw 的核心价值在于——它直接读取 数据库元数据（Metadata），而非依赖代码注解或SQL脚本。这意味着只要库存在，文档就能精准生成，杜绝“代码与库不同步”的经典难题。

---

原理剖析：Screw 是怎么“看穿”你的数据库的？

Screw 的本质是一个基于 JDBC 元数据查询的文档引擎。它通过 DatabaseMetaData 接口获取表结构、字段、主键、索引、外键等信息，再通过模板引擎（Freemarker）渲染成 HTML、Word 或 Markdown。

其调用流程如下：

📌 重点来了：正因为 Screw 完全依赖 JDBC 元数据，所以：

• ❗ 如果驱动不支持某些元数据（如MySQL 5.x驱动对getExportedKeys支持弱），外键可能查不出来。
• ❗ 如果连接URL没加useInformationSchema=true，索引信息可能为空。
• ❗ 如果字符集不对，中文注释变成“??? ??”

下面这三个坑，90%的人都踩过。

---

三大真实踩坑场景 & 解决方案

❌ 坑1：中文字段注释乱码 or 不显示

你兴冲冲跑完程序，打开生成的HTML，发现所有中文注释都是“???”或者干脆空白。

错误配置示例：

DataSourceConfig dataSourceConfig = new DataSourceConfig()
    .setUrl("jdbc:mysql://localhost:3306/mydb")
    .setUsername("root")
    .setPassword("123456");

👉 问题出在哪？缺少字符集和信息模式参数！

MySQL 的 information_schema 表存储了列的 COLUMN_COMMENT，但默认连接可能不会正确解析utf8mb4编码。

✅ 正确做法：

DataSourceConfig dataSourceConfig = new DataSourceConfig()
    .setUrl("jdbc:mysql://localhost:3306/mydb?" +
            "useUnicode=true&" +
            "characterEncoding=utf8&" +
            "useInformationSchema=true&" +  // 关键：启用 information_schema 查询
            "nullCatalogMeansCurrent=true") // 让 schema 查找更准确
    .setUsername("root")
    .setPassword("123456")
    .setDriver("com.mysql.cj.jdbc.Driver");

📌 补充说明：useInformationSchema=true 是 Screw 能正确读取索引、外键的关键开关。别小看它，很多“索引丢失”问题都源于此。

---

❌ 坑2：外键关系没显示出来

你在ER图里设计得好好的外键关联，结果生成文档时，user.order_id → order.id 根本不显示。

原因分析：MySQL 默认使用 MyISAM 引擎时不支持外键；即使用了 InnoDB，如果建表语句没显式加 FOREIGN KEY 约束，元数据里也查不到。

但更大的可能是——JDBC 驱动未启用外键元数据查询。

✅ 正确解决方案：

确保两点：

1. 表使用 InnoDB 且有外键约束；
2. URL 中开启 useInformationSchema=true（上文已提）；
3. 使用较新版本的 MySQL Connector/J（建议 8.0+）。

验证外键是否存在（SQL）：

SELECT 
    CONSTRAINT_NAME, 
    COLUMN_NAME, 
    REFERENCED_TABLE_NAME, 
    REFERENCED_COLUMN_NAME 
FROM 
    INFORMATION_SCHEMA.KEY_COLUMN_USAGE 
WHERE 
    TABLE_SCHEMA = 'mydb' 
    AND TABLE_NAME = 'user' 
    AND REFERENCED_TABLE_NAME IS NOT NULL;

若此SQL能查出数据，但Screw仍不显示——基本确定是驱动或配置问题。

---

❌ 坑3：索引信息为空 or 不完整

你记得给 email 字段加了唯一索引，但文档里“索引”一栏空空如也。

典型错误代码：忘了设置 useInformationSchema=true，导致 getindexinfo() 返回空。

✅ 正确完整配置示例（Spring Boot 集成）：

@Bean
public void generateDataDoc() {
    // 数据源配置
    DataSourceConfig dataSourceConfig = new DataSourceConfig()
        .setUrl("jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=UTF-8&useInformationSchema=true&nullCatalogMeansCurrent=true")
        .setUsername("root")
        .setPassword("123456")
        .setDriver("com.mysql.cj.jdbc.Driver");

    // 文档配置
    DocumentConfig documentConfig = DocumentConfig.builder()
        .version("1.0.0")
        .description("用户中心系统数据库文档")
        .build();

    // 生成配置
    EngineConfig engineConfig = EngineConfig.builder()
        .fileType(EngineFileType.HTML)          // 支持 HTML, WORD, MD
        .produceType(EngineTemplateType.freemarker) // 模板引擎
        .filePath("D:/docs")                    // 输出路径
        .build();

    // 执行生成
    new DocumentationExecute(dataSourceConfig, engineConfig, documentConfig).execute();
}

💡 提示：EngineFileType.WORD 生成 .docx，适合交付；HTML 便于本地查看；MD 可嵌入 Wiki。

---

进阶玩法：自定义模板，打造团队专属文档风格

Screw 默认模板偏简陋。如何让它输出符合你们团队审美的文档？

答案：Freemarker 自定义模板。

步骤如下：

1. 在 resources 下新建目录：templates/screw
2. 复制官方 freemarker template 到本地
3. 修改样式、添加LOGO、调整表格结构

然后在代码中指定模板路径：

EngineConfig engineConfig = EngineConfig.builder()
    .fileType(EngineFileType.HTML)
    .produceType(EngineTemplateType.freemarker)
    .filePath("D:/docs")
    .customFile("src/main/resources/templates/screw/custom.html.ftl") // 自定义模板
    .build();

你可以加入公司标题、版本号水印、甚至自动插入Git提交记录，实现真正的“自动化交付文档”。

---

最佳实践总结：Screw 使用避坑指南

实践项	推荐配置
🔧 JDBC URL	必须包含 useInformationSchema=true&useUnicode=true&characterEncoding=UTF-8
🚗 驱动版本	MySQL 8.0+，PostgreSQL 42+，Oracle ojdbc8+
📁 输出格式	内部协作用 HTML，交付用 Word，集成Wiki用 Markdown
🛠️ 模板定制	复制默认模板后修改，避免直接改jar包
🔄 自动化集成	结合 Maven Plugin 或 CI/CD 脚本，在打包后自动生成
🧪 验证手段	生成前先用 SQL 查 INFORMATION_SCHEMA 确认元数据完整

📌 高阶建议：将 Screw 集成进 Maven 生命周期，例如绑定到 post-integration-test 阶段，每次测试完成后自动更新文档，真正实现“文档即代码”。

Maven 插件配置片段：

<plugin>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>1.0.8</version>
    <executions>
        <execution>
            <phase>post-integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <dataSource>
            <url>jdbc:mysql://...</url>
            <username>root</username>
            <password>123456</password>
        </dataSource>
        <outputDir>${project.basedir}/docs</outputDir>
        <fileType>HTML</fileType>
        <processes>
            <process>TABLE</process>
        </processes>
    </configuration>
</plugin>

---

写在最后：让数据库文档成为你的“信任资产”

数据库不是黑盒，文档也不该是应付差事的产物。
Screw 的意义，不只是省了几小时手工劳动，而是建立起“数据库状态可追溯、可验证、可交付”的工程闭环。

当你下次面对新同事问“这张表谁设计的？字段啥意思？”时，你可以淡定地甩出一个链接：“看文档，最新版，刚CI自动更新的。”

这才是现代开发应有的体面。

而你要做的，只是——别再手写了，让 Screw 上场。