fountain migro 数据库迁移模块:三轮代码审查与 DDL 生成缺陷修复全记录
fountain migro 数据库迁移模块:三轮代码审查与 DDL 生成缺陷修复全记录
fountain 的 ORM 模块 f_orm 内置了名为 migro 的数据库迁移子模块:它以 PO 类上的 @DatabaseSchema / @ColumnSchema / @IndexSchema 注解为「期望结构」,与数据库中「实际结构」比对,生成 CREATE / DROP / ALTER / 索引变更等 DDL,并可通过 dbmigro 子命令落盘或直接执行。本文以仓库中的审查记录 优化方案 为主体,完整复盘 f_orm/src/migro/*.cj 经历的三轮代码审查:从 P0–P4 分级体系的运用,到驱动名冲突、方言语法错误、SQL 注入面(引号转义)、守卫与取值不一致等 13 项缺陷的发现与修复,以及配套的单元测试覆盖策略,为编写多数据库方言 DDL 生成器提供一份可复用的审查清单。
一、migro 模块速览:被审查的对象长什么样
理解审查结论前,先明确 migro 的代码组织(源码位于 f_orm/src/migro):
- SchemaFinder.cj:核心接口,定义了
listTables、findTableSchema、findIndexes、generateCreateSql、generateDropTableSql、generateAlterSql、generateIndexSql七个能力,即「读现状 + 生成差异 DDL」; - MysqlSchema.cj:MySQL/MariaDB 方言实现。
AbstractMysqlSchemaFinder封装通用逻辑,MysqlSchemaFinder(driverName = 'mysql')与MariaDBSchemaFinder(driverName = 'mariadb')两个@Bean子类仅覆盖驱动名; - PostgresSchema.cj:PostgreSQL/OpenGauss 方言实现,结构同上,
PostgresSchemaFinder('postgres')与OpenGaussSchemaFinder('opengauss'); - SchemaFinderMediator.cj:调度器。构造时通过
lookupList<SchemaFinder>()按driverName建立查找表,generate(cmdargs)完成「按驱动分组 → 逐表比对 → 生成 SQL → 孤儿表清理 → 按-m模式输出/执行」的完整流程; - SubCommand.cj:
dbmigro子命令入口,exec直接委托给SchemaFinderMediator().generate(args); - migro_test.cj:DDL 生成方法的单元测试,无需真实数据库连接即可验证 SQL 输出。
generate 的关键流程可从 SchemaFinderMediator.cj#L28-L102 读出:TableMetas.tableMetas() 按 driver 分组后,每表先查库中列——库中无表则 generateCreateSql,有表则 generateAlterSql,随后 findIndexes + generateIndexSql;再对「库中存在但定义中不存在」的表生成 drop table(孤儿表清理,L59-L75);所有 SQL 先打印到标准输出,最后按 -m / --mode 参数决定动作(省略/dry 仅打印、file 写入 ./migro.sql、auto 逐条经 ORM.executor(driver) 执行、interactive 交互确认执行)。
二、审查机制:P0–P4 分级 + 按时间追加
优化方案 的开头声明了它的组织方式:
每次审查后追加,保留 P0–P4 分级,按时间顺序排列
即这份文档不是静态设计稿,而是可增长的审查日志:每完成一轮审查,就追加一节带日期与覆盖范围的记录。文档中共记录了同一天的三轮审查:
| 轮次 | 覆盖范围 | 性质 |
|---|---|---|
| 2026-05-05 初版审查 | f_orm/src/migro/*.cj |
全量问题发现,11 项(P1×4、P2×1、P3×2、P4×3)+ 测试补充 |
| 2026-05-05 二次审查 | 同上(修复验证) | 验证 P0–P3 全部修复,并追加发现 1 处新缺陷 |
| 2026-05-05 三次审查 | PostgresSchema.cj 专项 |
PostgreSQL 方言深审,追加 5 项(P1×2、P2×1、P3×2) |
分级语义从修复动作可反推:P1 是「会生成错误 SQL 或直接不可用」的功能性缺陷,P2 是结构性坏味道,P3 是边角数据正确性问题,P4 是 cosmetic(外观性)问题。三轮结束后文档给出的最终统计为:
0 P0, 0 P1, 0 P2, 0 P3, 3 P4 (cosmetic)
且「12 个测试用例编译通过」。下文逐项对照当前源码,说明每个发现如何落地为代码修复。
三、初版审查:11 项发现的逐项复盘
3.1 [P1] MariaDBSchemaFinder.driverName = 'mysql' 与 MysqlSchemaFinder 冲突
原文记录:两个 @Bean finder 使用相同 driverName,后者覆盖前者;修复为 'mariadb'。
风险本质:SchemaFinderMediator 的构造逻辑是 for(f in lookupList<SchemaFinder>()){ finders<a href="https://link.gitcode.com/i/9e20481560fe4cb90b54bb86acb34d3b" target="_blank">f.driverName] = f }(见 [SchemaFinderMediator.cj#L23-L27)——ConcurrentHashMap 按驱动名索引,若 MariaDBSchemaFinder 也声明 'mysql',后注册者会静默覆盖先注册者,MariaDB 用户将拿到错误的(或不可预期的)finder 实现,且无任何报错。
当前源码佐证:MysqlSchema.cj#L172-L179 中 MariaDBSchemaFinder.driverName 已返回 'mariadb';测试用例 testMariaDBDriverName 专门固化了这一约束:
@TestCase
public func testMariaDBDriverName(): Unit {
let finder = MariaDBSchemaFinder()
@Assert("mariadb", finder.driverName)
}
3.2 [P1] generateDropTableSql 从未被调用
原文记录:接口定义了、两套实现都写了,但 mediator 不生成 DROP TABLE;修复为新增 SchemaFinder.listTables() 接口 + 两套实现 + mediator 中生成 DROP TABLE。
问题脉络:migro 的语义是「让数据库向代码定义收敛」。接口里定义了 generateDropTableSql,但调度器只处理「定义里有、库里没有」(建表)与「两边都有」(改表)两种情况,漏掉了「库里有、定义里没有」的孤儿表——drop table 写了却是死代码。
修复落地:
- SchemaFinder.cj#L23 新增
func listTables(database: String): Iterator<String>; - MySQL 侧实现查询
information_schema.tables(MysqlSchema.cj#L59-L68):
public func listTables(database: String): Iterator<String> {
resource(ORM.executor(driverName)){exe =>
exe.setSql('''
select table_name
from information_schema.tables
where table_schema = ${exe.arg(database)}''')
.iterator<MysqlTableSchemaPO>()
.map{po => po.tableNameFromDb}
}
}
- mediator 在生成主 DDL 后追加孤儿表清理:收集定义中的表名(转小写),
listTables结果中不在集合内的表逐条generateDropTableSql(SchemaFinderMediator.cj#L60-L75)。注意drop table语句与主 DDL 合并进同一列表,因此同样会随file/auto/interactive模式写入或执行——这是审查后明确的行为,使用auto模式时需意识到迁移会执行删表。
3.3 [P1] PostgreSQL ALTER COLUMN SET/DROP NOT NULL 缺列名
原文记录:alter table t set not null 不指定列名,而 PostgreSQL 语法要求 ALTER TABLE t ALTER COLUMN col SET NOT NULL。
当前源码佐证:PostgresSchema.cj 中所有可空性变更均已带列名,例如非重命名路径(L186-L190):
if(column.nullable){
sqls.add('alter table ${tableName} alter column ${c.columnName} drop not null;')
}else{
sqls.add('alter table ${tableName} alter column ${c.columnName} set not null;')
}
对应的回归测试 testPostgresAlterNotNull、testPostgresAlterRenameColumn(断言包含 alter column full_name set not null)见 migro_test.cj#L181-L192。
3.4 [P1] PostgreSQL ALTER 缺失类型变更
原文记录:比较 column != c 时只生成了 nullable/default 的 ALTER,漏掉 ALTER COLUMN ... TYPE;修复为增加 alter column ${column.columnName} type ${column.typeName}。
当前源码佐证:非重命名路径 PostgresSchema.cj#L177-L180:
if(column != c){
if(column.typeName != c.typeName || column.oldColumnName != ''){
sqls.add('alter table ${tableName} alter column ${column.columnName} type ${column.typeName};')
}
// ... default / nullable 变更
}
而 ColumnMeta 的相等性判定(TableMeta.cj#L86-L92)只比较 columnName / typeName / nullable / default / extra,所以「类型变了但其它没变」时 column != c 成立且会命中类型变更分支;类型没变但 nullable/default 变了则跳过类型分支、只发后两类 ALTER——这个「按维度拆分语句」的设计正是三次审查后 column.typeName != c.typeName 显式守卫存在的原因。
3.5 [P3] 重命名时 default/extra 用了旧列的值
原文记录:MySQL CHANGE 语句中 default/extra 取自 column(旧列),typeName/nullable 却取自 c(新列),新旧混用导致重命名+改属性同时发生时生成错误 DDL;修复为统一使用新列 c。
当前源码佐证:MysqlSchema.cj#L124-L130 重命名分支中,change 语句的全部属性均来自新列 c:
sqls.add('alter table ${tableName} change ${c.oldColumnName} ${c.columnName} ${c.typeName} ${if(c.nullable){''}else{'not null'}} ${if(let Some(d) <- c.default){"default '${esc(d)}'"}else{''}} ${c.extra};')
回归测试 testMysqlAlterChangeColumn 用 colWithOldName("email_addr", "varchar(200)", false, "", None, "email") 构造「重命名 + 改类型 + 改可空」的复合场景,断言输出包含 change email email_addr、varchar(200)、not null(migro_test.cj#L112-L122)。
3.6 [P3] 默认值引号未转义(MySQL + Postgres 共 10 处)
原文记录:"default '${d}'" 中若默认值本身含单引号,生成的 SQL 语法直接报错;修复为引入 esc(val) 辅助函数把 ' 替换为 '';同时修复了 Postgres CREATE TABLE 中 m.default 未调用 getOrThrow() 而输出字面 Some(value) 的问题。
当前源码佐证:两套实现各有一个私有静态转义函数(MysqlSchema.cj#L97-L99、PostgresSchema.cj#L124-L126):
private static func esc(val: String): String {
val.replace("'", "''")
}
所有输出默认值的位置都经过 esc(...),如 Postgres 建表附加的 SET DEFAULT 语句(PostgresSchema.cj#L140):
list.iterator().filter{m => m.default.isSome()}.map{m => "ALTER TABLE ${tableName} ALTER ${m.columnName} SET DEFAULT '${esc(m.default.getOrThrow())}';"}
注意这里 esc(m.default.getOrThrow()) 正是原文提到的「未调 getOrThrow() 会输出 Some(value)」问题的修复形态。值得一提的是,这套 esc 只防 SQL 语法破损(引号闭合),并非参数化绑定——DDL 语句本身不走 arg(...) 占位符(information_schema 查询侧则统一使用 exe.arg(...) 参数绑定),这一点在审查文档中未展开,读者自行扩展方言时应保持警惕。
3.7 [P2] 重复的 HashMap 构造模式
原文记录:fold(HashMap<...>()){m, i => m[i.name] = i; m} 这一「把迭代器折叠为按名索引 Map」的模式在两个文件共 4 处重复;修复为提取到抽象基类。
当前源码佐证:两个抽象类各自提取了静态辅助方法,如 MysqlSchema.cj#L53-L58:
private static func indexColumns(itr: Iterator<ColumnMeta>): HashMap<String, ColumnMeta> {
itr.fold(HashMap<String, ColumnMeta>()){m, c => m[c.columnName] = c; m}
}
private static func indexIndexes(itr: Iterator<IndexMeta>): HashMap<String, IndexMeta> {
itr.fold(HashMap<String, IndexMeta>()){m, i => m[i.name] = i; m}
}
generateAlterSql / generateIndexSql 均通过 indexColumns(current) / indexIndexes(new.iterator()) 建立比对索引——这是 DDL 差异算法的核心数据结构:把「期望」和「现状」都变成 Map,再分别遍历差集与交集。
3.8 三个 P4(cosmetic)遗留项及其现状
初版审查还记录了三个外观性问题,标记为「待修复」。对照当前源码,三者的现状分别是:
SchemaFinder.cj残留注释块:原文指 SchemaFinder.cj#L21-L38 存在三个被注释的字段定义块。当前源码中该注释块已清理,接口区(SchemaFinder.cj#L21-L30)只剩七个方法声明;listTables使用 PO 中的extra字段:listTables复用MysqlTableSchemaPO,其中tableNameFromDb字段(映射table_name,MysqlSchema.cj#L38-L39)仅服务于该轻量查询,PO 因此「膨胀」了字段。从源码结构看,这一项尚未处理,listTables仍走完整 PO 映射;MigroCommandstruct 注册:SubCommand.cj#L20-L24 中public struct MigroCommand <: SubCommand在static init里把自身值实例注册进SubCommandMediator,原文担心 struct 的值拷贝语义可能带来问题,建议考虑改为 class。从源码结构看,该项也保持原样(仍是 struct +static init自注册)。
这说明 P4 的「cosmetic」定性是务实的:不影响正确性的问题允许跨版本缓慢消化,但必须留痕在审查文档中。
四、二次审查:修复验证中发现「守卫与取值不一致」
二次审查的结论是「所有 P0–P3 问题已修复」,但验证过程本身又抓出一处新缺陷,这是「修复验证轮」价值的典型体现:
PostgresSchema.cj:182 guard/value 不匹配:
c.default.isSome()守卫 +column.default.getOrThrow()取值不一致。若旧列有默认值而新列无,SET DEFAULT分支取None.getOrThrow()→ 抛异常。已修正守卫为column.default.isSome()。
问题机理:条件判断用旧列 c 的 default 是否为 Some,取值却用新列 column 的 default。当「旧列有默认值、新列没有」时,守卫通过(旧值非空)但取值方是 None,getOrThrow() 直接抛异常——迁移命令在合法变更场景下崩溃。修复原则一句话:判空对象与取值对象必须是同一个。
对照当前源码,非重命名路径(PostgresSchema.cj#L181-L185)已统一为新列 column:
if(column.default.isSome()){
sqls.add("alter table ${tableName} alter ${c.columnName} set default '${esc(column.default.getOrThrow())}';")
}else{
sqls.add("alter table ${tableName} alter ${c.columnName} drop default;")
}
守卫与取值同源,且 None 分支正确降级为 drop default。
五、三次审查:PostgreSQL 专项深审
前两轮是全量扫描,第三轮把火力集中在 PostgresSchema.cj 的方言正确性上,追加了 5 项发现(引号均指原文记录):
| 等级 | 行号 | 问题 | 修复 |
|---|---|---|---|
| P1 | 186 | 非重命名路径 nullable 用旧列值 c.nullable |
改为 column.nullable |
| P1 | 209,213 | alter table ... drop index 是 MySQL 语法 |
改为 drop index(PostgreSQL 正确语法) |
| P2 | 76-122 | findTableSchema/findIndexes 缺 schema 过滤 |
待处理(低风险,仅 public schema) |
| P3 | 127-141 | CREATE TABLE 用 ALTER 设 DEFAULT 而非内联 | 可选优化 |
| P3 | 162 | alter col vs alter column col 风格不统一 |
可选优化 |
逐项对照当前源码:
- nullable 取值来源(P1,已修复):非重命名路径现以新列判定可空性(PostgresSchema.cj#L186-L190):
if(column.nullable){ ...drop not null... }else{ ...set not null... }。与重命名路径(L166-L170 使用c.nullable,c即新列)保持一致——整个文件的可空性判定全部锚定在「新定义」一侧; - 索引删除语法(P1,已修复):PostgreSQL 的删索引是独立的
DROP INDEX idx,不能挂在ALTER TABLE下。当前generateIndexSql已修正(PostgresSchema.cj#L208-L218):
for(i in currentIndexes.values() where !newIndexMap.contains(i.name)){
sqls.add('drop index ${i.name};')
}
for(i in newIndexMap.values()){
if(let Some(x) <- currentIndexes.get(i.name) && i != x){
sqls.add('drop index ${i.name};')
sqls.add('${i.def};')
}else if(!currentIndexes.contains(i.name)){
sqls.add('${i.def};')
}
}
与 MySQL 侧的 alter table ${tableName} drop index ${i.name};(MysqlSchema.cj#L146-L148)形成鲜明的方言对照。Postgres 重建索引走 ${i.def}——即 IndexMeta.def 保存的 pg_indexes.indexdef 原文(含 USING btree 等细节),保证重建结果与库中原索引逐字节一致,测试 testPostgresIndexDef 直接断言输出包含 CREATE INDEX idx_name ON users USING btree (name);
3. schema 过滤(P2,待处理):listTables 显式限定 table_schema = 'public'(PostgresSchema.cj#L82),但 findTableSchema(L98-L102,仅 table_catalog + table_name)与 findIndexes(L107-L112,pg_indexes 仅按 tablename 过滤)没有同等的 schema 约束。从源码结构看,该项确实尚未处理,原文的「待处理(低风险,仅 public schema)」结论与现状一致——若数据库里不同 schema 存在同名表,information_schema.columns 查询可能命中错误 schema 的列;
4. DEFAULT 内联(P3,可选优化):Postgres 建表时默认值不走内联 default '...',而是先建表再逐列 ALTER TABLE ... SET DEFAULT(PostgresSchema.cj#L130-L142),所以 generateCreateSql 返回的迭代器不止一条 SQL。原文将其列为「可选优化」而非缺陷——功能正确,只是语句数多一条;
5. alter col 风格(P3,可选优化):当前实现中 default 变更统一写作 alter ${column} set/drop default(PostgreSQL 允许省略 column 关键字),可空性变更写作 alter column ${column} set/drop not null(该语法必须带 column 关键字),两类语句关键字长短不一。原文标记为风格不统一,属可选优化,未强制收敛。
六、测试覆盖:DDL 生成器如何做到「无需数据库即可验证」
审查文档「已添加测试」一节记录:migro_test.cj 提供 12 个测试用例,覆盖 MySQL/Postgres DDL 生成全部 4 个方法(CREATE/DROP/ALTER/INDEX)。当前 migro_test.cj 中实际有 15 个 @TestCase 方法(随三轮审查的修复而增长),其设计思路值得借鉴:
- 直接构造
ColumnMeta/IndexMeta输入,断言 SQL 文本输出,绕开数据库依赖。测试类注释写得很直白:These tests verify SQL output without requiring a database connection; - 辅助构造器阶梯:
col→colWithExtra→colWithDefault→colWithOldName逐层叠加属性,使每个用例精确命中一种差异维度(纯新增、纯删除、重命名、改类型、改默认值); - 每个修复点都有对应断言:
testMariaDBDriverName锁死驱动名(3.1 节)、testMysqlAlterChangeColumn锁死重命名用新列属性(3.5 节)、testPostgresDropIndex断言startsWith("drop index")而非alter table ... drop index(五次审查第 2 项)、testPostgresAlterRenameColumn依次断言rename column→alter column ... type→set not null三句顺序(3.4/5.1 节)。
对「生成 SQL 字符串」这类纯函数逻辑,这种「输入元数据 → 输出文本断言」的测试形态就是最合适的回归网:审查发现的每一处 P1/P3 缺陷,最终都变成了一行 @Assert。
七、总结:一份可复用的 DDL 生成器审查清单
把三轮审查的发现按「成因」重新归类,可以得到一份审查多数据库方言 DDL 生成器时的检查清单:
- 驱动/方言路由类:多个 finder 的
driverName是否唯一(3.1 节);调度器按名建索引时重复名会静默覆盖; - 死代码类:接口定义了的方法是否真的被调度器调用(3.2 节);
generateDropTableSql从「写了没人调」到补上listTables闭环; - 方言语法类:逐条语句核对目标数据库的官方语法,尤其「同一语义在不同方言下写法完全不同」的场景——
ALTER COLUMN ... SET NOT NULL(必须带列名)、DROP INDEX(不能挂在ALTER TABLE下)(3.3、3.4、五.2 节); - 新旧数据混用类:diff 算法中「期望列」与「现状列」两个对象极易混用,审查要逐字段确认属性取值来源(default/extra 用新列,3.5 节);
- Option 语义类:守卫判断的对象必须与
getOrThrow()取值的对象一致,否则合法变更场景直接抛异常(四节); - 字符串安全类:拼进 SQL 文本的默认值要做引号转义(3.6 节);
- 结构重复类:折叠建 Map 等模式重复出现时提取为基类辅助方法(3.7 节);
- 遗留项显式留痕:P4 与「待处理」项不修可以,但必须记录在文档里(三.8 节、五.3 节)。
回到文档本身:优化方案 的价值不仅在于记录了这些缺陷,更在于示范了「审查日志式」的工程实践——每次审查追加一节、保留分级、标注「✅ 已提交」与「待处理」、最终给出量化统计(0 P0, 0 P1, 0 P2, 0 P3, 3 P4)。结合 f_orm/src/migro 下六个源文件与 15 个测试用例,这套记录让任何后续维护者都能在几分钟内重建该模块的质量上下文:什么修过、为什么修、还剩什么、风险多高。