3. 数据库迁移文件的结构设计

数据库迁移文件是版本协同与代码审查的核心载体。一个清晰、一致的文件结构能够显著降低多人协作时的冲突概率，并让审查者快速理解每次变更的范围与意图。本节将定义迁移文件的命名规范、目录组织方式以及文件内部的标准模板。

3.1 迁移文件命名规范

命名规范需要同时满足三个目标：全局唯一、自然排序、语义可读。推荐采用 Flyway 风格的版本号前缀 + 描述性后缀的组合模式。

3.2 目录结构设计

推荐采用分层目录结构，将迁移文件、配置、回滚脚本和工具类脚本分离，便于 Git 管理和 CI/CD 集成。

project-root/
├── migrations/
│   ├── versions/                  # 核心迁移文件目录
│   │   ├── V1.0.0__init.sql
│   │   ├── V1.0.1__add_user_table.sql
│   │   ├── V1.1.0__create_orders.sql
│   │   └── V1.1.1__add_order_index.sql
│   ├── undo/                      # 回滚脚本目录（与 versions 一一对应）
│   │   ├── U1.0.1__add_user_table.sql
│   │   └── U1.1.0__create_orders.sql
│   ├── repeatable/                # 可重复执行脚本
│   │   ├── R__view_active_users.sql
│   │   └── R__function_calc_total.sql
│   ├── seed/                      # 种子数据脚本
│   │   └── seed_initial_data.sql
│   └── config/                    # 迁移工具配置
│       ├── flyway.conf
│       └── migration_policy.yml
└── .gitignore

3.3 迁移文件内部结构模板

每个迁移文件应遵循统一的内部结构，包含元信息注释、变更内容、回滚指引和校验检查。以下是一个标准模板：

-- ============================================================
-- Migration: V1.0.1__add_user_table
-- Author:    Zhang Wei
-- Date:      2025-03-21
-- JIRA:      PROJ-1234
-- Description: 创建用户基础表，包含用户名、邮箱和注册时间。
-- ============================================================

-- 1. 前置检查：确保表不存在
DO $$
BEGIN
    IF EXISTS (SELECT 1 FROM information_schema.tables
               WHERE table_name = 'users') THEN
        RAISE EXCEPTION 'Table users already exists';
    END IF;
END $$;

-- 2. 执行变更
CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    username    VARCHAR(64)  NOT NULL UNIQUE,
    email       VARCHAR(255) NOT NULL UNIQUE,
    created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
);

-- 3. 创建索引
CREATE INDEX idx_users_email ON users (email);

-- 4. 添加注释
COMMENT ON TABLE users IS '用户基础信息表';
COMMENT ON COLUMN users.username IS '用户名，唯一标识';
COMMENT ON COLUMN users.email IS '电子邮箱，用于登录和通知';

-- 5. 后置校验：验证表结构
DO $$
BEGIN
    ASSERT (SELECT COUNT(*) = 4 FROM information_schema.columns
            WHERE table_name = 'users'), 'Column count mismatch';
END $$;

-- ============================================================
-- Rollback: U1.0.1__add_user_table.sql
-- DROP TABLE IF EXISTS users CASCADE;
-- ============================================================

3.4 迁移文件结构关系图

下图展示了迁移文件命名、目录结构与内部模板之间的整体关系，帮助团队建立统一的认知模型。

3.5 分支策略与目录的协同

在 Git 工作流中，不同分支的迁移文件应遵循以下目录协同规则，避免版本号冲突和合并困难：

• 主分支（main/master）：只包含已发布的正式版本号文件，如 V1.0.0__、V1.1.0__。
• 功能分支（feature/*）：使用时间戳命名，如 V20250321_1430__，确保分支间不冲突。
• 合并前：在功能分支上重新编号，将时间戳改为目标版本号，并确保与主分支的版本号连续。
• 回滚脚本：始终与正向迁移文件在同一分支提交，禁止跨分支引用回滚脚本。