代码生成治理、数据库迁移与团队协作规范实战

src/main/java/
  demo/jooq/
    config/
    controller/
    service/
    repository/
    model/
    dto/
    tx/
    datasource/
    audit/
    security/

src/main/resources/
  db/
    migration/
      V1__init.sql
      V2__add_system_admin_audit_fields.sql
      V3__add_user_profile.sql
      V4__add_indexes.sql

target/generated-sources/jooq/
  demo/jooq/gen/
    Tables.java
    Keys.java
    Indexes.java
    tables/
    tables/records/
    tables/pojos/

这里的关键点是：

迁移脚本单独放在 db/migration
jOOQ 生成代码单独放在 generated-sources
业务代码不要和生成代码混在一起

5.1 为什么生成代码一定要单独目录

因为生成代码和业务代码本质上不是一类内容。

业务代码

是团队手写、可维护、可设计的逻辑。

生成代码

是数据库 schema 的编译期映射，应该尽量视为“产物”。

把两者分开有几个好处：

避免误改生成代码
IDE 更容易标记为 Generated Sources
包边界更清晰
代码审查时更容易聚焦真正手写的变更

六、Codegen 配置治理：不要越配越乱

到了团队阶段，pom.xml 里的 jOOQ 插件配置如果不治理，通常会逐渐失控。

6.1 推荐统一版本变量

例如：

<properties>
  <jooq.version>3.18.6</jooq.version>
  <postgresql.version>42.2.24</postgresql.version>
</properties>

这样：

运行时 jOOQ 版本
codegen 插件版本
JDBC 驱动版本

更容易统一管理。

6.2 推荐固定生成目录与包名

例如：

<target>
  <packageName>demo.jooq.gen</packageName>
  <directory>${project.build.directory}/generated-sources/jooq</directory>
</target>

不要一会儿放：

src/main/java
一会儿放 gen
一会儿又换包名

否则团队协作很难稳定。

6.3 推荐显式控制生成范围

大库里不要默认全生成。

例如：

<includes>system_admin|system_role|system_admin_role|user_profile|user_score_log</includes>

或者排除掉无关表：

<excludes>flyway_schema_history|tmp_.*|bak_.*</excludes>

这样做有两个好处：

生成结果更干净
团队不会因为整个数据库里无关表变化而频繁生成大量 diff

6.4 为什么不建议“能扫到的全扫”

如果项目所在数据库里还有：

旧系统表
运维表
临时表
历史归档表
测试表

而 codegen 全扫，会带来很多问题：

生成量大
编译慢
diff 噪音多
真正业务表变更淹没在大量无关改动里

所以团队协作里，codegen 生成范围应当尽量收敛。

七、生成代码要不要提交 Git

这是团队里最常见、也最容易争论的问题之一。

其实没有放之四海而皆准的唯一答案，但可以讲清楚取舍。

7.1 方案一：提交生成代码到 Git

也就是把：

target/generated-sources/jooq

或者拷贝后的生成目录纳入版本控制。

优点

拉代码后不一定非要立刻本地生成
CI 编译更直观
数据库未连接时也能编译
code review 时能直接看到 schema 映射变化

缺点

diff 可能很多
合并冲突概率更高
仓库会变大
需要大家遵守“不手改生成代码”

7.2 方案二：不提交生成代码

只提交：

迁移脚本
codegen 配置
手写业务代码

然后要求：

本地或 CI 必须先生成再编译

优点

仓库更干净
不会有大量生成类 diff
合并冲突更少

缺点

构建依赖数据库 schema 状态
本地环境要求更高
生成失败会导致编译失败
CI 需要更完整的数据库准备流程

7.3 什么时候更适合提交

如果团队处于这些阶段，通常更适合先提交生成代码：

团队还不大
CI 还不够完善
数据库环境准备流程还不稳定
想降低新同学接手门槛
希望 code review 直接看到生成类变化

7.4 什么时候更适合不提交

如果团队已经具备这些条件，则可以考虑不提交：

CI 流程成熟
测试数据库自动准备完善
迁移 + 生成 + 编译流程高度自动化
团队对 codegen 与迁移的协作约束很强

7.5 我的建议

对大多数正在建设中的团队，我更推荐：

前期可以提交生成代码，等 CI 与迁移流程成熟后，再评估是否切换为不提交。

原因很现实：

先稳定协作，再追求仓库洁癖
先让流程可靠，再减少产物提交

八、数据库迁移、Codegen、业务代码的协作流程

这一部分最重要，因为它直接决定团队协作是否顺畅。

推荐一个非常清晰的流程。

8.1 标准变更流程

假设你要给 system_admin 表加一个新字段 email。

推荐流程是：

第一步：写迁移脚本

例如：

-- V5__add_system_admin_email.sql
ALTER TABLE system_admin
ADD COLUMN email VARCHAR(128);

第二步：执行迁移

让本地开发库更新到最新 schema。

第三步：执行 jOOQ Codegen

重新生成：

SYSTEM_ADMIN.EMAIL
Record / POJO 中的新字段

第四步：修改业务代码

例如 Repository、DTO、接口逻辑。

第五步：补测试

验证：

迁移后 schema 正确
生成代码正确
新业务逻辑正确

第六步：提交代码

一起提交：

迁移脚本
生成代码（如果团队选择提交）
业务代码
测试代码

这套流程应该成为团队共识。

8.2 为什么不推荐“先写业务代码，再补迁移”

因为这样通常会导致：

本地编译依赖你自己手改数据库
其他人拉代码无法运行
CI 环境缺 schema
生成类与业务代码不匹配

所以正确顺序永远应该是：

schema 先变，生成再跟，业务最后。

九、Code Review 应该审什么

多人协作时，数据库变更类 PR 不能只看业务代码。

对于这类变更，建议 review 至少看下面 4 类内容。

9.1 迁移脚本是否正确

关注：

DDL 是否可执行
是否考虑了默认值、非空、回填
索引是否合理
是否影响线上老数据

9.2 生成代码变化是否符合预期

如果提交生成代码，则要看：

是否只改到了预期表
是否出现了无关大范围变更
字段类型映射是否正确
是否误把无关 schema 一起生成了

9.3 业务代码是否跟上了 schema 变化

例如：

新增字段是否真正使用了
删除字段后是否还有旧引用
DTO / Repository / Service 是否同步调整

9.4 测试是否覆盖到关键路径

尤其关注：

迁移后的查询是否还正常
新索引、新约束相关逻辑是否测试
逻辑删除、乐观锁、数据权限是否被意外影响

十、多人同时改表时怎么减少冲突

这是团队协作里非常现实的问题。

10.1 冲突主要有哪几类

1. 迁移脚本冲突

两个人都加了下一版脚本，编号或命名冲突。

2. 生成代码冲突

两个人都生成了同一批类，合并时冲突。

3. 业务代码冲突

表字段变化导致同一 Repository、DTO 被多人同时修改。

10.2 如何降低迁移脚本冲突

推荐：

使用严格版本命名规则
每个变更一个独立脚本
脚本名称表达清楚意图

例如：

V10__add_system_admin_email.sql
V11__add_user_profile_gin_index.sql
V12__create_v_admin_role_view.sql

不要用：

V10__fix.sql
V11__update.sql

这种名字，因为后期几乎无法理解。

10.3 如何降低生成代码冲突

如果团队选择提交生成代码，建议：

1. 收敛生成范围

避免每次生成整个大库。

2. 保持 codegen 配置稳定

不要今天改包名，明天改输出目录。

3. 迁移脚本和生成代码一起提交

避免别人先拿到业务代码，后拿到生成类。

4. Code Review 时重点看“是否出现无关生成 diff”

如果改一个字段，结果生成了一大堆不相关变化，说明流程或配置可能有问题。

十一、多环境一致性：开发、测试、生产怎么保持同步

多人协作里最怕的就是：

开发库是新的
测试库是旧的
生产库又是另一版

所以迁移体系真正的目标不是“会跑脚本”，而是：

让所有环境尽量通过同一套迁移顺序演进。

11.1 开发环境

推荐：

本地启动前先执行迁移
codegen 基于迁移后的最新开发库生成

这样能保证本地看到的 schema 和脚本是一致的。

11.2 测试环境

推荐：

测试运行前自动迁移到最新版本
集成测试基于迁移后的测试库执行

这样测试才能真正验证“当前代码 + 当前 schema”。

11.3 生产环境

推荐：

发布前先评审迁移脚本
发布过程先迁移数据库，再发布应用
若迁移包含高风险变更，提前评估兼容窗口

尤其要注意：

应用发布顺序必须和 schema 兼容性设计一致。

例如：

先加字段，再发新代码，通常更安全
先删字段，再发旧代码，通常很危险

十二、向后兼容与灰度发布：数据库变更不能太激进

这是数据库协作里最容易忽略的点。

12.1 推荐的兼容性思路

如果要改一张线上表，优先采用“两步或三步变更”：

场景：字段替换

假设要把 login_name 替换为 username。

不推荐直接：

删旧字段
加新字段
业务代码一次性切换

更推荐：

第一步

加新字段 username，旧字段先保留。

第二步

代码同时兼容旧字段和新字段，逐步迁移数据。

第三步

确认全部切换完成后，再删旧字段。

这种渐进式变更，才适合线上系统。

12.2 为什么数据库变更要比 Java 代码更保守

因为 Java 代码可以快速回滚，但数据库结构和数据本身往往更难回退。

所以经验上：

数据库迁移要偏保守、偏兼容，应用代码可以偏敏捷。

十三、CI/CD 中应该如何接入

只要团队已经有 CI，就非常建议把迁移和 codegen 纳入流水线约束。

13.1 最基本的 CI 检查项

至少建议包含：

1. 迁移脚本可执行

在测试数据库上执行迁移不报错。

2. Codegen 可正常执行

基于迁移后的 schema 成功生成代码。

3. 业务代码可编译

Repository / Service / 测试通过编译。

4. 测试通过

尤其是数据库相关集成测试。

13.2 如果团队提交生成代码

那 CI 还可以进一步校验：

当前迁移 + 当前 codegen 配置重新生成后的结果，是否与仓库提交一致。

如果不一致，说明有人：

改了 schema 没重新生成
改了生成代码却没同步提交
环境差异导致生成结果不稳定

这类检查非常实用。

十四、团队协作规范：建议明确写进 README 或开发手册

到了团队阶段，不要把这些规则停留在“大家口头知道”。

更推荐显式写进：

README
开发手册
架构规范文档
PR 模板

14.1 至少应明确这些规则

1. 任何表结构变化必须通过迁移脚本

不能只改本地库，不提脚本。

2. schema 变更后必须重新执行 codegen

否则业务代码和生成类不一致。

3. 迁移脚本、生成代码、业务代码应尽量同一个 PR 提交

避免分散提交导致别人中间态无法使用。

4. 不允许手改生成代码

生成代码应视为产物。

5. 生成范围、包名、输出目录不得随意变更

这类修改应当视为架构级调整，而不是普通开发行为。

6. 数据库高风险变更必须评审

例如：

删除字段
修改类型
加非空约束
大表建索引
重命名字段/表

这些都不能“想改就改”。

十五、一个推荐的 Maven 工作流

为了让团队有固定动作，可以约定一个简单工作流。

15.1 开发时

修改 schema

先新增迁移脚本。

更新本地数据库

执行迁移。

生成代码

执行：

mvn -DskipTests generate-sources

开发业务代码

使用新的 Tables / Record / POJO。

15.2 只编译不重新生成时

如果团队支持跳过 jOOQ 生成，可约定：

mvn clean install -DskipTests -Djooq.codegen.skip=true

这适合：

当前没改 schema
只想快速编译业务代码

但必须注意：

一旦 schema 改了，就不能偷懒跳过生成。

十六、几个最容易踩的坑

16.1 开发库 schema 已变，但迁移脚本没提交

这是最常见的坑之一。

表现是：

你本地一切正常
别人拉代码就报错
CI 无法重现你的环境

这说明你修改了数据库，但没有把变更纳入正式迁移流程。

16.2 迁移脚本提交了，但没重新生成代码

表现是：

数据库能升级
但业务代码仍引用旧字段
或者新字段在 Tables 中根本没有

这说明 schema 和 codegen 没同步。

16.3 生成范围过大导致无关 diff 爆炸

表现是：

改一张表
PR 里几十上百个生成类都变了

这通常说明：

codegen 配置没收敛
生成范围太宽
环境里存在无关 schema 干扰

16.4 在生产上做破坏性变更但代码没做好兼容

例如：

先删字段
应用还没发布新版本

这种顺序很容易直接导致线上异常。

16.5 团队没人真正对 schema 负责

如果数据库变更人人都能随便改，又没人把控：

表设计质量
索引策略
字段命名
迁移兼容性

那再好的 jOOQ 体系也会越来越乱。

所以一定要有明确的数据库变更评审意识。

十七、推荐的一套团队协作闭环

如果把这一篇压缩成一套最实用的闭环，我建议是：

1. 先写迁移脚本

2. 本地执行迁移

3. 重新执行 codegen

4. 修改业务代码

5. 补测试

6. 一起提交 PR

7. CI 执行迁移 + 生成 + 编译 + 测试

8. 发布前评审高风险数据库变更

这 8 步如果团队长期执行，数据库协作会稳定很多。

十八、本篇总结

这一篇把 tio-boot + jOOQ 从“运行时能力”继续推进到了“团队协作与工程治理能力”。

通过本文，我们完成了：

明确数据库迁移、jOOQ 代码生成、业务代码三者的职责边界
理解为什么团队阶段必须引入迁移工具
设计清晰的目录结构与 codegen 输出边界
分析生成代码是否提交 Git 的取舍
建立 schema 变更 → codegen → 业务代码的标准协作流程
明确 Code Review、CI/CD、多环境一致性的关键检查点
理解数据库向后兼容与灰度发布的重要性
形成一套可写入开发手册的团队协作规范

一句话总结：

jOOQ Codegen 真正的价值，不只是“少写字符串 SQL”，而是让数据库 schema 变化能够被团队以编译期可见、流程可控的方式协作起来。

到这里，整个 tio-boot + jOOQ 系列已经从：

基础整合
SQL 表达能力
PostgreSQL 高级能力
企业治理能力
测试与排障能力
多数据源架构能力

继续扩展到了：

数据库迁移治理
codegen 治理
团队协作规范

这已经形成了一套比较完整、可长期演进的现代 Java 数据访问体系。