GORMDB迁移契约领域建模与架构设计 - 第4节

4.1 AutoMigrate 基本用法

AutoMigrate 是 GORM 提供的自动迁移工具，能够根据 Go 结构体定义自动创建、更新数据库表结构，是开发阶段最常用的数据库同步手段。其核心方法为 AutoMigrate，接收一个或多个模型结构体指针作为参数。

4.1.1 基础调用方式

import (
    "gorm.io/gorm"
    "gorm.io/driver/sqlite"
)

type User struct {
    gorm.Model
    Name  string
    Email string
}

func main() {
    db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
    if err != nil {
        panic("数据库连接失败")
    }

    // 自动迁移：创建或更新 User 表
    err = db.AutoMigrate(&User{})
    if err != nil {
        panic("迁移失败: " + err.Error())
    }
}

4.1.2 多模型批量迁移

AutoMigrate 支持同时传入多个模型，按顺序依次处理每个模型对应的表结构：

db.AutoMigrate(&User{}, &Order{}, &Product{})

批量迁移时，GORM 会按照传入顺序逐个创建或更新表。如果某个模型迁移失败，后续模型将不再执行，并返回第一个错误。

4.2 自动建表与字段变更

4.2.1 自动建表规则

当模型对应的表不存在时，AutoMigrate 会根据结构体定义创建新表。下表展示了 Go 类型与数据库列类型的默认映射关系：

4.2.2 字段变更行为

当表已存在时，AutoMigrate 仅执行以下变更：

• 新增字段：模型中有但表中没有的字段，自动添加新列。
• 修改索引：根据 tag 中的 uniqueIndex、index 等创建或更新索引。
• 修改约束：非空约束（not null）、默认值（default）等会尝试更新。
• 忽略操作：不会删除字段、不会修改字段类型、不会重命名列。

4.2.3 字段标签对迁移的影响

GORM 标签可以精确控制迁移生成的列属性：

type Product struct {
    gorm.Model
    Code  string  `gorm:"size:50;not null;uniqueIndex"`
    Price float64 `gorm:"type:decimal(10,2);default:0.00"`
    Stock int     `gorm:"default:0;comment:库存数量"`
    Desc  string  `gorm:"type:text"`
}

常用标签说明：

4.3 AutoMigrate 执行流程

下图展示了 AutoMigrate 从模型解析到表结构同步的完整执行链路：

4.4 迁移日志与错误处理

4.4.1 启用迁移日志

GORM 默认的 Logger 会输出 SQL 语句，但 AutoMigrate 执行的 DDL 默认不会打印详细日志。可以通过配置 Logger 的 LogMode 和 IgnoreRecordNotFoundError 来控制输出：

db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{
    Logger: logger.Default.LogMode(logger.Info),
})

设置 LogMode(logger.Info) 后，AutoMigrate 执行的每条 CREATE TABLE、ALTER TABLE 等 DDL 语句都会在控制台输出，便于调试和审计。

4.4.2 自定义迁移日志

如果需要将迁移日志写入文件或自定义格式，可以实现 logger.Interface：

import (
    "log"
    "os"
    "gorm.io/gorm/logger"
)

func main() {
    file, _ := os.OpenFile("migrate.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
    customLogger := logger.New(
        log.New(file, "\r\n", log.LstdFlags),
        logger.Config{
            SlowThreshold:             200 * time.Millisecond,
            LogLevel:                  logger.Info,
            IgnoreRecordNotFoundError: true,
            Colorful:                  false,
        },
    )

    db, _ := gorm.Open(sqlite.Open("test.db"), &gorm.Config{
        Logger: customLogger,
    })
    db.AutoMigrate(&User{})
}

4.4.3 错误处理策略

AutoMigrate 返回的 error 包含详细的失败原因。常见的错误类型及处理建议如下：

4.4.4 错误处理代码示例

err := db.AutoMigrate(&User{}, &Order{})
if err != nil {
    // 记录详细错误
    log.Printf("迁移失败: %v", err)

    // 判断错误类型
    if strings.Contains(err.Error(), "already exists") {
        log.Println("表已存在，尝试手动同步字段")
        // 使用 Migrator 接口进行精细控制
        migrator := db.Migrator()
        if !migrator.HasColumn(&User{}, "age") {
            migrator.AddColumn(&User{}, "age")
        }
    } else {
        log.Fatalf("无法恢复的迁移错误: %v", err)
    }
}

4.5 迁移前后的状态对比

下图展示了 AutoMigrate 执行前后数据库表结构的变化对比：

4.6 迁移安全注意事项

• 开发环境使用：AutoMigrate 主要适用于开发和测试环境，生产环境建议使用版本化迁移工具。
• 备份先行：在生产环境执行 AutoMigrate 前，务必对数据库进行完整备份。
• 事务保护：GORM 的 AutoMigrate 默认不在事务中执行，如果需要在事务中迁移，可以手动开启事务：

tx := db.Begin()
if err := tx.AutoMigrate(&User{}); err != nil {
    tx.Rollback()
    return err
}
tx.Commit()

• 大表迁移：对于数据量大的表，ALTER TABLE 可能耗时较长，建议在业务低峰期执行。
• 版本锁定：在团队协作中，建议将 GORM 版本锁定，避免不同版本间的迁移行为差异。