GORM实战：如何根据主键策略选择.Save()与.Create()

关注

原创最新推荐文章于 2026-11-13 14:13:01 发布 154 阅读 AI 写同款· GEO 优化 ›

Gorm Save更新踩坑记录｜Gorm Save主键冲突｜Duplicate entry ‘xxxx‘ for key ‘PRIMARY 在我最近使用Gorm进行字段更新的过程中，我遇到了一个问题。当我尝试更新status字段时，即使该字段的值没有发生变化，Gorm还是提示我“Duplicate entry 'xxxx' for key 'PRIMARY'”。阅读详情

1. 从一次线上事故说起：为什么选错方法会出大问题

几年前，我在一个用户管理系统中踩过一个坑，至今记忆犹新。当时有个需求是同步外部系统的用户数据到我们自己的数据库，逻辑很简单：如果用户ID存在就更新信息，不存在就创建新记录。我心想，这不就是典型的“保存”操作吗？于是很自然地用了 Save() 方法。

代码大概长这样：

func SyncUser(user User) error {
    return db.Save(&user).Error
}

看起来没问题对吧？但上线后没多久，监控就报警了——数据库出现了大量主键冲突的错误。我查了半天才发现，问题出在有些用户的ID虽然是数字，但在外部系统里是字符串类型，同步过来后GORM认为这些ID是零值（因为Go里int的零值是0），于是每次都执行插入操作，自然就冲突了。

这就是我今天想跟你聊的核心问题：在GORM里，.Save()和.Create()看起来都能“保存”数据，但它们的底层逻辑完全不同，用错了轻则报错，重则数据混乱。特别是当你的表主键策略比较复杂时，更需要理解这两个方法的脾气。

简单来说，.Create()是个直肠子，它只干一件事：插入新记录。如果你给的数据主键不为零，它会认为你想插入一个已存在的记录，直接报错。而.Save()是个聪明人，它会先看看主键是否存在，存在就更新，不存在就插入。但正是这个“聪明”，有时候会带来意想不到的麻烦。

2. 深入骨髓：.Create() 的纯粹插入哲学

2.1 当主键为零值时：标准的插入操作

让我们先彻底搞懂 .Create()。这个方法的设计哲学很纯粹：我就是来创建新记录的，别让我干别的。

最典型的场景就是自增主键。假设我们有个用户表：

type User struct {
    ID   uint   `gorm:"primaryKey;autoIncrement"`
    Name string
    Age  int
}

// 场景1：标准插入
user := User{Name: "张三", Age: 25}
result := db.Create(&user)
// 生成的SQL：INSERT INTO users (name, age) VALUES ('张三', 25)
// user.ID 会被自动填充为数据库生成的自增ID

这里的关键点在于，ID字段是零值（0），GORM看到后就知道：“哦，这是个新用户，我要生成新ID”。插入成功后，user.ID会被自动赋值为数据库返回的自增ID。

我建议你在实际开发中养成一个习惯：每次.Create()之后，都检查一下生成的主键值。这不仅能确认插入成功，还能在需要关联操作时拿到正确的ID。

if err := db.Create(&user).Error; err != nil {
    log.Printf("插入失败: %v", err)
    return err
}
log.Printf("新用户创建成功，ID: %d", user.ID)

2.2 当主键非零时：为什么.Create()会报错

现在来看一个容易出错的场景。有时候我们从外部系统拿到数据，里面已经包含了ID：

// 场景2：带ID的插入尝试
user := User{ID: 100, Name: "李四", Age: 30}
err := db.Create(&user).Error
// 这里会报错！错误信息类似：
// Error 1062: Duplicate entry '100' for key 'PRIMARY'

为什么？因为.Create()看到ID字段不是零值（0），它就认为你想插入一个ID为100的记录。如果数据库里已经存在ID=100的用户，就会触发主键冲突；即使不存在，GORM也会严格按照你给的ID去插入，而不是使用自增。

这里有个重要细节：GORM判断“主键是否存在”的标准是“是否为零值”。对于数值类型是0，对于字符串是""，对于指针是nil。所以如果你用了*uint作为ID类型，那么nil时GORM会认为是新记录。

2.3 批量插入的陷阱与技巧

批量插入是.Create()的强项，但也有一些坑需要注意：

// 正确的批量插入
users := []User{
    {Name: "王五", Age: 28},
    {Name: "赵六", Age: 32},
    {Name: "孙七", Age: 45},
}

// 方法1：直接Create切片
result := db.Create(&users)
fmt.Printf("插入了%d条记录", result.RowsAffected)

// 方法2：分批插入（大数据量时推荐）
batchSize := 100
result = db.CreateInBatches(&users, batchSize)

但这里有个性能陷阱：如果你一次性插入几万条记录，可能会遇到数据库连接超时或者内存问题。我建议超过1000条就考虑分批，并且最好在事务中操作：

err := db.Transaction(func(tx *gorm.DB) error {
    // 在事务中批量插入
    if err := tx.CreateInBatches(&users, 1000).Error; err != nil {
        return err // 自动回滚
    }
    return nil // 自动提交
})

另外，批量插入时钩子函数（Hooks） 的行为也需要注意。BeforeCreate和AfterCreate会对每个记录分别调用，如果钩子里有复杂逻辑，批量插入的性能优势可能会被抵消。

3. 双重人格：.Save() 的智能与危险

3.1 Save() 的核心逻辑：先更新，后插入的保障机制

如果说.Create()是单纯的，那么.Save()就是复杂的。它的行为可以概括为：尽一切可能让数据保存成功。

官方文档说得很清楚：Save()是一个upsert（更新或插入）操作。但它的具体实现比听起来更微妙：

检查主键：首先检查传入结构体的主键字段
主键存在 → 尝试更新（更新所有字段）
更新影响行数=0 → 回退到插入
主键不存在 → 直接插入

这个逻辑在源码中体现得很清楚。我读过GORM的源码，Save()方法的核心判断大致是这样的：

// 伪代码，展示Save的逻辑
func Save(value interface{}) error {
    // 检查主键是否为零值
    if 主键是零值 {
        return Create(value) // 直接插入
    }
    
    // 尝试更新所有字段
    result := UpdateAllFields(value)
    
    // 如果更新没有影响任何行
    if result.RowsAffected == 0 {
        // 回退到插入
        return CreateWithOnDuplicateKeyUpdate(value)
    }
    
    return nil
}

这种“先更新，失败再插入”的策略，本意是好的，但在某些场景下会出问题。

3.2 主键策略如何影响.Save()的行为

3.2.1 自增主键的典型场景

对于最常见的自增主键，.Save()的行为比较直观：

// 场景1：新记录（ID=0）
user := User{Name: "张三", Age: 25}  // ID默认为0
db.Save(&user)
// SQL: INSERT INTO users (name, age) VALUES ('张三', 25)

// 场景2：更新现有记录
user := User{ID: 1, Name: "张三", Age: 26}
db.Save(&user)
// SQL: UPDATE users SET name='张三', age=26 WHERE id=1

但这里有个隐藏的坑：如果更新操作没有修改任何值（比如所有字段都和数据库里一样），RowsAffected可能是0，这时.Save()会尝试插入，导致主键冲突！

3.2.2 非自增主键的注意事项

当主键不是自增，而是业务ID时，情况更复杂：

type Product struct {
    Code string `gorm:"primaryKey"`  // 商品编码作为主键
    Name string
    Price float64
}

// 假设数据库里没有 CODE="P001" 的商品
product := Product{Code: "P001", Name: "手机", Price: 2999.00}
db.Save(&product)
// 第一次执行：INSERT INTO products (code, name, price) VALUES ('P001', '手机', 2999.00)

// 第二次执行同样的Save
product.Price = 2799.00
db.Save(&product)
// 这次会执行：UPDATE products SET name='手机', price=2799.00 WHERE code='P001'

3.2.3 复合主键的特殊处理

复合主键的场景下，.Save()的行为又有所不同：

type UserRole struct {
    UserID uint `gorm:"primaryKey"`
    RoleID uint `gorm:"primaryKey"`
    // 复合主键：UserID + RoleID
}

// 必须所有主键字段都非零，Save()才会尝试更新
userRole := UserRole{UserID: 1, RoleID: 2}
db.Save(&userRole)
// 如果(1,2)存在则更新，否则插入

3.3 那些年我踩过的.Save()的坑

3.3.1 零值字段被意外更新

这是.Save()最危险的行为之一：它会更新所有字段，包括零值。

type Article struct {
    ID        uint
    Title     string
    Content   string
    ViewCount int  // 浏览数
}

// 假设数据库里有一条记录：
// ID: 1, Title: "旧标题", Content: "旧内容", ViewCount: 100

article := Article{ID: 1, Title: "新标题"}
db.Save(&article)

// 生成的SQL可能是：
// UPDATE articles SET title='新标题', content='', view_count=0 WHERE id=1
// 注意：Content和ViewCount被更新为零值了！

解决方案：如果你只想更新部分字段，应该用Updates()而不是Save()：

// 只更新Title字段
db.Model(&Article{}).Where("id = ?", 1).Update("title", "新标题")

// 或者更新多个字段，但跳过零值
db.Model(&article).Updates(map[string]interface{}{
    "title": "新标题",
    // 不指定content和view_count，它们不会被更新
})

3.3.2 并发下的竞态条件

在高并发场景下，.Save()可能引发竞态条件：

// 两个goroutine同时执行
go func() {
    user := User{ID: 1, Name: "张三"}
    db.Save(&user)  // 可能同时执行插入，导致冲突
}()

go func() {
    user := User{ID: 1, Name: "李四"}
    db.Save(&user)  // 同上
}()

解决方案：使用更明确的Create或Update，或者使用数据库的乐观锁/悲观锁。

3.3.3 与Where()条件联用的迷惑行为

.Save()和.Where()一起用时，行为可能不符合直觉：

user := User{ID: 1, Name: "张三", Age: 30}
db.Where("age > ?", 20).Save(&user)
// 生成的SQL：UPDATE users SET name='张三', age=30 WHERE age > 20 AND id=1
// 注意：WHERE条件被加上了id=1！

这是因为.Save()总是会包含主键条件，即使你显式指定了其他WHERE条件。

4. 实战决策指南：什么情况下该用哪个？

4.1 决策流程图：一眼看懂如何选择

面对具体场景时，你可以参考下面这个决策流程：

开始
  ↓
需要保存数据
  ↓
┌─────────────────┐
│ 数据是否来自数据库查询？ │
└─────────┬───────┘
          │
          ├─ 是 → 使用 Updates() 或 Save()（明确要更新所有字段时）
          │
          └─ 否 → 主键是否确定存在？
                     │
                     ├─ 是 → 使用 Updates()（推荐）或 Save()
                     │
                     └─ 否 → 是否允许覆盖已存在记录？
                                │
                                ├─ 是 → 使用 Save() 或 Upsert
                                │
                                └─ 否 → 使用 Create()

4.2 典型场景对比分析

让我们通过几个真实场景来感受如何选择：

场景一：用户注册（明确是新记录）

// 明确知道是新用户，用Create最安全
func Register(username, password string) error {
    user := User{
        Username: username,
        Password: hashPassword(password),
        CreatedAt: time.Now(),
    }
    
    // 明确使用Create，避免意外覆盖
    if err := db.Create(&user).Error; err != nil {
        // 处理错误，可能是用户名重复等
        return fmt.Errorf("注册失败: %w", err)
    }
    
    // 注册成功，可以拿到新的UserID
    log.Printf("新用户注册成功: ID=%d, Username=%s", user.ID, user.Username)
    return nil
}

场景二：用户更新个人信息（部分更新）

// 只更新部分字段，用Updates而不是Save
func UpdateUserProfile(userID uint, updates map[string]interface{}) error {
    // 使用Updates只更新指定的字段
    result := db.Model(&User{}).
        Where("id = ?", userID).
        Updates(updates)
    
    if result.Error != nil {
        return result.Error
    }
    
    // 检查是否真的更新了记录
    if result.RowsAffected == 0 {
        return fmt.Errorf("用户不存在或数据未变更")
    }
    
    return nil
}

// 调用示例
err := UpdateUserProfile(1, map[string]interface{}{
    "nickname": "新昵称",
    "avatar":   "new_avatar.jpg",
    // 不更新其他字段
})

场景三：同步外部数据（可能需要更新或插入）

// 同步商品信息，外部系统可能推送新商品或更新已有商品
func SyncProduct(externalProduct ExternalProduct) error {
    product := Product{
        Code:  externalProduct.Code,  // 业务主键
        Name:  externalProduct.Name,
        Price: externalProduct.Price,
    }
    
    // 这里用Save是合适的，因为我们希望：
    // 1. 新商品 → 插入
    // 2. 已有商品 → 更新
    // 但要注意零值问题！
    
    // 更好的做法：使用Clauses处理冲突
    err := db.Clauses(clause.OnConflict{
        Columns:   []clause.Column{{Name: "code"}},  // 冲突列
        DoUpdates: clause.AssignmentColumns([]string{"name", "price"}),  // 更新哪些列
    }).Create(&product).Error
    
    return err
}

4.3 性能考量：为什么有时候要避免.Save()

.Save()的便利性是有代价的：

额外的检查开销：每次都要检查主键、尝试更新、可能回退到插入
全字段更新：即使你只想改一个字段，它也会更新所有字段
网络往返：如果更新行数为0，它还会尝试插入，意味着可能多一次数据库交互

在性能敏感的场景下，我建议：

// 高性能场景：明确知道是插入还是更新

// 情况1：明确插入
func BatchInsertUsers(users []User) error {
    // 使用CreateInBatches，明确是插入
    return db.CreateInBatches(users, 1000).Error
}

// 情况2：明确更新
func UpdateUserStatus(userID uint, status string) error {
    // 使用Update，只更新一个字段
    return db.Model(&User{}).
        Where("id = ?", userID).
        Update("status", status).Error
}

// 情况3：需要upsert但关心性能
func UpsertProduct(product Product) error {
    // 使用原生upsert，一次数据库交互
    return db.Clauses(clause.OnConflict{
        Columns:   []clause.Column{{Name: "code"}},
        UpdateAll: true,
    }).Create(&product).Error
}

5. 高级话题：自定义主键与复杂场景

5.1 非ID主键字段的配置

GORM默认寻找名为ID或Id的字段作为主键。如果你的主键字段名不同，需要显式标记：

// 使用Email作为主键
type Admin struct {
    Email    string `gorm:"primaryKey;size:100"`
    Name     string
    Role     string
}

// 或者使用自定义结构体标签
type Customer struct {
    CustNo   string `gorm:"column:customer_no;primaryKey"`
    Name     string
    // ...
}

// 对于这种非ID主键，Save()的行为：
admin := Admin{Email: "admin@example.com", Name: "管理员"}
db.Save(&admin)
// 会检查Email是否已存在，存在则更新，否则插入

5.2 使用Upsert替代Save的可行性

在某些场景下，使用clause.OnConflict实现Upsert比.Save()更可控：

// 方法1：使用OnConflict实现upsert
func UpsertUser(user User) error {
    return db.Clauses(clause.OnConflict{
        Columns:   []clause.Column{{Name: "id"}},  // 冲突依据
        DoUpdates: clause.AssignmentColumns([]string{"name", "email", "updated_at"}),  // 更新哪些列
    }).Create(&user).Error
}

// 方法2：更新所有非主键字段
func UpsertAllFields(user User) error {
    return db.Clauses(clause.OnConflict{
        Columns:   []clause.Column{{Name: "id"}},
        UpdateAll: true,  // 更新所有非主键字段
    }).Create(&user).Error
}

// 方法3：自定义更新逻辑
func UpsertWithCustomUpdate(user User) error {
    return db.Clauses(clause.OnConflict{
        Columns: []clause.Column{{Name: "id"}},
        DoUpdates: clause.Assignments(map[string]interface{}{
            "login_count": gorm.Expr("login_count + 1"),
            "last_login":  time.Now(),
        }),
    }).Create(&user).Error
}

Upsert的优点：

更明确的冲突处理逻辑
可以控制更新哪些字段
通常性能更好（一次数据库交互）

5.3 事务中的Save与Create行为

在事务中，.Save()和.Create()的行为需要特别注意：

err := db.Transaction(func(tx *gorm.DB) error {
    // 在事务中创建用户
    user := User{Name: "事务用户"}
    if err := tx.Create(&user).Error; err != nil {
        return err  // 回滚
    }
    
    // 同时创建用户配置
    config := UserConfig{
        UserID: user.ID,  // 使用刚创建的UserID
        Theme:  "dark",
    }
    
    // 这里用Create，因为明确是新记录
    if err := tx.Create(&config).Error; err != nil {
        return err  // 回滚，包括前面的用户创建
    }
    
    return nil  // 提交事务
})

在事务中使用.Save()要特别小心，因为它的“更新或插入”逻辑可能导致意外的数据覆盖。如果事务需要回滚，但.Save()已经更新了某些记录，这些更新是无法撤销的（除非使用更高级的保存点）。

6. 最佳实践与性能优化

6.1 根据主键策略制定方法选择规范

基于不同的主键策略，我建议这样选择：

自增主键场景：

新记录：总是用Create()，让数据库生成ID
更新记录：用Updates()指定要更新的字段
只有确定需要upsert时才用Save()

UUID或业务主键场景：

新记录：用Create()，但确保主键已正确设置
更新记录：用Updates()或Save()（如果确定要全字段更新）
考虑使用：clause.OnConflict实现更可控的upsert

无主键或复合主键场景：

尽量避免使用Save()，因为行为可能不符合预期
明确使用Create()或Update()

6.2 监控与调试：如何知道Save和Create实际做了什么

在实际项目中，了解GORM实际执行的SQL很重要：

// 方法1：启用Debug模式
db.Debug().Save(&user)
// 输出：执行的SQL语句

// 方法2：使用Logger记录所有SQL
newLogger := logger.New(
    log.New(os.Stdout, "\r\n", log.LstdFlags),
    logger.Config{
        SlowThreshold: time.Second,
        LogLevel:      logger.Info,
        Colorful:      true,
    },
)

db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
    Logger: newLogger,
})

// 方法3：在特定会话中调试
db.Session(&gorm.Session{DryRun: true}).Save(&user)
// DryRun模式只生成SQL不执行，用于调试

6.3 常见错误模式与避坑指南

根据我的经验，这些错误最常见：

错误：用Save更新部分字段

// 反例
user := User{ID: 1, Name: "新名字"}
db.Save(&user)  // 会把其他字段设为零值！

// 正例
db.Model(&User{}).Where("id = ?", 1).Update("name", "新名字")

错误：在循环中频繁Save

// 反例：N+1问题
for _, user := range users {
    db.Save(&user)  // 每次循环都执行一次数据库操作
}

// 正例：批量操作
db.CreateInBatches(users, 100)  // 或批量更新

错误：忽略Save的返回值

// 反例
db.Save(&user)  // 不检查错误和影响行数

// 正例
result := db.Save(&user)
if result.Error != nil {
    return result.Error
}
if result.RowsAffected == 0 {
    log.Println("没有记录被更新，可能执行了插入")
}

错误：混合使用Model和Save

// 反例：未定义行为
db.Model(&User{}).Where("age > ?", 18).Save(&user)

// 正例：分开操作
// 查询
db.Model(&User{}).Where("age > ?", 18).First(&user)
// 更新
db.Save(&user)

6.4 性能优化技巧

批量操作优先：总是考虑批量插入/更新而不是循环单条操作
明确指定字段：使用Select和Omit减少不必要的数据传输
避免全字段更新：除非必要，否则不用Save()的全字段更新
合理使用索引：确保Save()和Create()操作的条件字段有索引
连接池配置：调整GORM和数据库的连接池参数

// 性能优化示例
sqlDB, err := db.DB()
if err != nil {
    log.Fatal(err)
}

// 配置连接池
sqlDB.SetMaxIdleConns(10)           // 最大空闲连接
sqlDB.SetMaxOpenConns(100)          // 最大打开连接
sqlDB.SetConnMaxLifetime(time.Hour) // 连接最大生命周期

// 批量插入优化
func BatchInsertOptimized(users []User) error {
    return db.Session(&gorm.Session{
        CreateBatchSize: 1000,      // 每批1000条
        SkipHooks:       true,      // 跳过钩子提升性能
    }).Create(&users).Error
}

在实际项目中，我通常会给团队制定这样的规范：默认使用Create()和Updates()，只有明确需要upsert逻辑时才考虑Save()，并且要加上详细的注释说明为什么用Save()而不是其他方法。这样既能保证代码清晰，又能避免意外的数据问题。

记住，GORM的.Save()和.Create()不是可以随意互换的——它们有着根本不同的语义和行为。理解这些差异，根据你的具体场景和主键策略做出明智选择，才能写出既正确又高效的数据库操作代码。