如何避免 Schema 与文档脱节？聊聊结合 Flyway 迁移与 CI 自动导出数据字典的工程化实践

聊一个后端老生常谈但总容易翻车的问题：数据字典和 Schema 漂移治理。

最近在把几个 Spring Boot 3.2 的服务往 GraalVM Native Image 上迁，顺手做了一轮基础设施和依赖的梳理，结果发现几张核心表的字段注释、枚举值定义，和团队 Wiki 里的设计文档完全对不上。

目前我们团队的主流做法还是偏传统的两套轨：

1. DDL 变更：靠 Flyway（走规范的 V{version}__{desc}.sql）或者 Liquibase 做版本受控，CI 阶段跑 validate 校验 checksum。这部分能保证各环境一致性，但无法约束文档的同步更新。
2. 字典/文档导出：试过在本地跑 screw 这种工具逆向 DB 生成 HTML/Markdown 贴到知识库，但现实情况往往是：迭代节奏一快，谁改了表结构，谁就忘了重新触发导出，两周后文档继续失效。

想问问大家团队现在都是怎么把「DDL 变更」与「开发文档 / 字典更新」做强绑定的？

大家更倾向于：

• Code-First：以 Java Entity（如 JPA / MyBatis-Plus）为唯一事实来源，靠注解自动推导并推送给接口/文档平台？（遇到 Native Image 这种对反射敏感的场景是否有额外成本？）
• DB-First：以 SQL / Flyway 迁移脚本为源头，直接在 CI/CD 流程里挂钩子逆向刷新文档系统？
• 还是干脆直接上 Bytebase 这类专门的 Database CI/CD 平台做全流程管控？

大家在实际落地过程中，有没有踩过哪些意料之外的坑？