GORM之primary_key标签详解

在 GORM 中，`gorm:"primaryKey"`（新版推荐写法，旧版 `primary_key` 已弃用）是控制数据库主键映射的核心结构体标签，它打破了默认仅识别 `ID` 字段的限制，支持任意命名、任意类型（如 string/UUID）甚至多字段复合主键，深度影响 SQL 生成、自动迁移和 CRUD 行为；本文深入解析其工作原理、典型用法与关键注意事项，帮助 Go 开发者精准掌控模型与数据库之间的主键契约，兼顾约定简洁性与配置灵活性。

在 GORM 中，`gorm:"primary_key"` 是一个结构体字段标签，用于显式声明该字段为数据库表的主键；若未指定，GORM 默认使用名为 `ID` 的 `uint` 或 `int` 类型字段作为主键，但通过该标签可灵活覆盖默认行为，支持自定义主键名称、类型及复合主键场景。

GORM 通过解析结构体字段的 gorm 标签（如 gorm:"primary_key"）来构建模型元数据。当 GORM 遇到该标签时，会将对应字段标记为逻辑主键，并将其加入 modelStruct.PrimaryFields 列表，从而影响后续的 SQL 生成行为——例如 INSERT 语句是否包含该字段、UPDATE 是否将其作为 WHERE 条件、以及自动迁移（AutoMigrate）时是否为其添加 PRIMARY KEY 约束。

例如，以下结构体明确将 UUID 字段设为主键：

type User struct {
    UUID      string `gorm:"primaryKey;type:char(36)"`
    Name      string
    CreatedAt time.Time
}

此时 GORM 不再默认查找 ID 字段，而是使用 UUID 作为主键，并在迁移时生成类似 PRIMARY KEY (uuid) 的 DDL 语句。

⚠️ 注意事项：

• gorm:"primary_key" 在新版 GORM（v2，即 gorm.io/gorm）中已被弃用，推荐统一使用 gorm:"primaryKey"（全小写，下划线风格已移除）；
• 若需复合主键，可对多个字段同时添加 primaryKey 标签（GORM v2 支持），例如：

  type OrderItem struct {
      OrderID  uint `gorm:"primaryKey"`
      ProductID uint `gorm:"primaryKey"`
      Quantity int
  }

• 标签解析发生在模型初始化阶段（reflect.StructField.Tag.Get("gorm")），因此必须确保字段导出（首字母大写）且标签格式正确；
• 即使字段类型非整数（如 string、uuid.UUID），只要标注 primaryKey，GORM 仍会将其视为主键并适配对应数据库类型。

总之，gorm:"primary_key"（或现代写法 gorm:"primaryKey"）是 GORM 实现“约定优于配置”的关键机制之一——它让开发者既能享受默认约定的简洁性，又能通过声明式标签精准控制数据库映射细节。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~