本文详解如何使用 gorm 的结构体标签（struct tag）正确声明跨多个字段的联合唯一索引，避免常见误用（如单字段独立唯一），并确保迁移时生成符合预期的数据库约束。
本文详解如何使用 gorm 的结构体标签（struct tag）正确声明跨多个字段的联合唯一索引，避免常见误用（如单字段独立唯一），并确保迁移时生成符合预期的数据库约束。
在 GORM 中，实现多列（复合）唯一索引的关键在于：所有参与该唯一约束的字段必须共享同一个索引名，并均标注 unique 选项。GORM 会自动识别同名索引标签，将它们合并为一个联合索引（Composite Index），而非为每个字段创建独立的唯一索引。
以下是一个标准、可工作的示例：
type Something struct {
gorm.Model
First string `gorm:"index:idx_something_first_second,unique"`
Second string `gorm:"index:idx_something_first_second,unique"`
Third string `gorm:"not null"` // 其他普通字段
}✅ 正确行为：
- 迁移时（如调用 db.AutoMigrate(&Something{})），GORM 将创建一个名为 idx_something_first_second 的联合唯一索引，覆盖 first 和 second 两列（顺序依结构体字段声明顺序而定）；
- 数据库层面保证 (First, Second) 组合值全局唯一，允许单字段重复（例如 "A"/"X" 和 "A"/"Y" 合法，但 "A"/"X" 出现两次则报错）。
⚠️ 常见误区与注意事项：
- ❌ 错误写法：sql:"unique_index:..." —— 这是旧版 GORM v1 的标签语法，GORM v2 已完全弃用 sql 标签，必须使用 gorm 标签；
- ❌ 错误写法：为各字段指定不同索引名（如 index:idx_a,unique 和 index:idx_b,unique）—— 这将创建两个独立的单列唯一索引，不是联合唯一；
- ✅ 推荐命名：索引名应具备语义性（如 idx_user_email_provider），便于后续维护与调试；
- ✅ 可选增强：如需控制列顺序或添加排序方向，可扩展为 gorm:"index:idx_name,unique,sort:asc"（部分驱动支持）；
- ? 生产提示：联合唯一索引属于数据库约束，迁移前建议在测试环境验证行为；若需修改已有表索引，应结合 db.Migrator().DropIndex() 与 AutoMigrate() 安全演进。
总结：GORM v2 中定义多列唯一索引，核心是「同名 + unique + gorm 标签」三要素缺一不可。合理运用该机制，可精准建模业务中常见的复合唯一规则（如“用户邮箱+平台类型”、“订单号+子项序号”等），兼顾数据完整性与查询性能。
