4. Flyway 迁移脚本命名规范
Flyway 通过脚本文件名来识别迁移类型、执行顺序和版本依赖。命名规范直接决定了版本管理的可读性、团队协作的效率和回滚策略的可行性。本章从版本号命名规则、可重复迁移命名、撤销迁移命名三个维度进行详细拆解。
4.1 版本号命名规则
Flyway 的版本化迁移（Versioned Migration）是增量式数据库变更的标准方式。其文件名由四个部分组成：前缀、版本号、分隔符、描述。
| 组成部分 | 说明 | 示例 |
|---|---|---|
| 前缀 | 标识迁移类型，版本化迁移固定为 V（大写） |
V |
| 版本号 | 数字或点分数字序列，表示版本顺序 | 1、2.1、20250401 |
| 分隔符 | 版本号与描述之间的固定分隔符，通常为双下划线 __ |
__ |
| 描述 | 简短、语义化的变更说明，单词间用单下划线 _ 连接 |
create_user_table |
完整示例：
含义：版本 2.1，操作为“向 users 表添加 email 列”。
V2.1__add_email_column_to_users.sql含义：版本 2.1，操作为“向 users 表添加 email 列”。
4.2 版本号命名规则详解
版本号是 Flyway 排序和执行的核心依据。规则如下：
- 唯一性：每个版本号在全局必须唯一，重复版本号会导致迁移失败。
- 顺序性：Flyway 按版本号的数值或点分数值升序执行。点分版本按每段数值逐段比较，例如
1.9<1.10。 - 可读性：推荐使用语义化版本，如
1.0、1.1、2.0，或基于日期的版本如20250401。 - 避免跳跃：虽然 Flyway 允许版本跳跃，但建议保持连续，便于代码审查和回滚定位。
最佳实践：团队约定版本号格式为
主版本.次版本（如 1.0、1.1），每次提交新迁移时递增次版本号。避免使用 V001、V002 等纯数字前缀，因为点分版本在合并分支时冲突更少。
4.3 可重复迁移命名
可重复迁移（Repeatable Migration）用于管理视图、函数、存储过程等需要反复更新的对象。其命名规则与版本化迁移不同：
- 前缀：固定为
R（大写）。 - 无版本号：可重复迁移不包含版本号，Flyway 通过文件内容的
checksum判断是否需要重新执行。 - 分隔符与描述：同样使用
__分隔，描述语义化。
示例：
含义：可重复迁移，创建或替换用户视图。每次文件内容变更后，Flyway 会自动重新执行。
R__create_user_view.sql含义：可重复迁移，创建或替换用户视图。每次文件内容变更后，Flyway 会自动重新执行。
| 迁移类型 | 前缀 | 版本号 | 执行策略 |
|---|---|---|---|
| 版本化迁移 | V |
必须（如 1.0） |
按版本顺序执行一次 |
| 可重复迁移 | R |
无 | 每次 checksum 变化时重新执行 |
注意：可重复迁移总是在所有待执行的版本化迁移之后执行。如果可重复迁移依赖于某个版本化迁移的结果，请确保版本化迁移先被应用。
4.4 撤销迁移命名
撤销迁移（Undo Migration）用于回滚已应用的版本化迁移。Flyway 通过文件名前缀 U 来识别撤销脚本。
- 前缀：固定为
U（大写）。 - 版本号：必须与待撤销的版本化迁移的版本号完全一致。
- 分隔符与描述：与版本化迁移相同，使用
__分隔，描述建议包含“undo”或“revert”字样。
示例：
含义：撤销版本 2.1 的迁移，即移除 email 列。
U2.1__undo_add_email_column.sql含义：撤销版本 2.1 的迁移，即移除 email 列。
撤销迁移的执行需要显式调用 flyway undo 命令，且只能按版本号逆序逐条撤销。例如，当前已应用版本 1.0、1.1、2.0，执行 flyway undo 会先撤销 2.0，再撤销 1.1，最后撤销 1.0。
4.5 命名规范避坑指南
常见错误：
- 使用小写前缀
v、r、u—— Flyway 严格区分大小写，必须大写。 - 版本号中包含空格或特殊字符，如
V 1.0或V1.0-beta。 - 分隔符使用单下划线
_而非双下划线__，导致解析失败。 - 可重复迁移中误加版本号，如
R1.0__view.sql，会被 Flyway 忽略版本号部分。 - 撤销迁移版本号与原始迁移不匹配，导致回滚时找不到对应脚本。
团队规范建议：
- 在项目 README 或 CONTRIBUTING 文档中明确命名规则示例。
- 使用
flyway validate命令在 CI 中自动检查命名合规性。 - 对于大型项目，建议在版本号中加入模块标识，如
V1.0.USER__create_table.sql，便于按模块分类。