GORM不支持PHP风格BackedEnum，需用string/int常量+Scan/Value接口实现双向映射；禁用gorm:"type:ENUM"标签，推荐varchar字段+枚举常量+校验方法+显式更新。
GORM 本身不原生支持 PHP 风格的 BackedEnum，它面向的是 Go 生态；你看到的 type AgentStatus string + const 模式，是 Go 中模拟枚举的惯用写法，并非语言级枚举。真正要让 GORM 正确映射“复杂 ENUM”，关键不在“枚举类型本身”，而在如何把 Go 的字符串/整数常量与数据库的 ENUM 字段双向对齐，且避免类型擦除和 NULL 处理出错。
Go 中的“ENUM”本质是命名常量，不是类型
GORM 不会识别 enum 关键字（Go 语言直到 1.23 仍无原生枚举），所以所谓“ENUM 映射”，实际是开发者用 string 或 int 类型 + const 块 + 自定义 Scan/Value 方法来模拟。例如：
type AgentStatus string
const (
ActiveAgentStatus AgentStatus = "ACTIVE"
InactiveAgentStatus AgentStatus = "INACTIVE"
MaintenanceAgentStatus AgentStatus = "MAINTENANCE"
)
func (s *AgentStatus) Scan(value interface{}) error {
if value == nil {
*s = ""
return nil
}
switch v := value.(type) {
case string:
*s = AgentStatus(v)
case []byte:
*s = AgentStatus(string(v))
default:
return fmt.Errorf("cannot scan %T into AgentStatus", value)
}
return nil
}
func (s AgentStatus) Value() (driver.Value, error) {
if s == "" {
return nil, nil // 允许 NULL
}
return string(s), nil
}
- 必须实现
driver.Valuer和sql.Scanner接口，否则 GORM 会把值当普通string处理，丢失语义约束 - 注意
nil处理：数据库字段允许 NULL 时，Scan要能接收nil，Value要能返回nil - 不要依赖
gorm:"type:ENUM(...)"自动生成建表语句——GORM 的ENUM标签在 PostgreSQL 中无效，在 MySQL 中虽可生成，但迁移工具（如AutoMigrate）不会校验值集合变更，极易导致线上数据不一致
GORM 的 ENUM 标签只在 MySQL 有效，且有严重局限
如果你硬要用 gorm:"type:ENUM('ACTIVE','INACTIVE','MAINTENANCE')"，仅限 MySQL 场景，且必须清楚以下限制：
- 字段类型被固定为 MySQL
ENUM，无法跨数据库迁移（PostgreSQL 会报错，SQLite 忽略） -
AutoMigrate不会更新已有表的 ENUM 值列表，新增case后，旧表字段不会自动扩展，插入新值直接失败 - GORM 读取时仍返回
string，不自动转为你的AgentStatus类型，除非你额外封装Scan/Value - 使用
WHERE status = ?查询时，传入ActiveAgentStatus常量是安全的（底层仍是 string），但若传入任意字符串（如"active"），数据库可能静默截断或报错，GORM 不做校验
推荐做法：用字符串字段 + 枚举常量 + 自定义方法封装
放弃数据库层 ENUM，改用 varchar（或 text）字段 + Go 层强约束，更可控、可测试、可演进：
- 数据库字段声明为
status varchar(20) NOT NULL DEFAULT 'INACTIVE'，不依赖 DB 特性 - 在结构体中保留
Status AgentStatus字段，并通过Scan/Value方法确保进出一致性 - 添加校验方法：
func (s AgentStatus) IsValid() bool { switch s { case ActiveAgentStatus, InactiveAgentStatus, MaintenanceAgentStatus: return true; default: return false } } - API 输入时立刻校验：
if !input.Status.IsValid() { return errors.New("invalid status") }，别等到写入数据库才失败 - 需要枚举列表时，用
[]AgentStatus{ActiveAgentStatus, InactiveAgentStatus, MaintenanceAgentStatus}，而非反射或硬编码字符串
注意 GORM v2 的 AfterFind 不适合做枚举转换
有人试图在 AfterFind 回调里把 string 字段转成枚举类型，这是危险的：
-
AfterFind在每次查询后触发，但 GORM 可能复用 struct 实例（尤其在切片中），导致状态污染 - 如果字段为 NULL，
AfterFind里无法区分是数据库 NULL 还是零值，容易把""错当成有效枚举 - 它绕过了
Scan接口，破坏了 GORM 的标准数据绑定流程，后续调用Save时可能因类型不匹配报错 - 真正该做转换的地方只有两个：
Scan（从 DB 到 struct）和Value（从 struct 到 DB）
最易被忽略的一点：GORM 的 Update 操作默认只更新非零值，而 AgentStatus("") 是零值，会导致 status 字段被跳过更新——必须显式用 db.Select("status").Updates(&agent) 或在 Update 前确保字段已赋值。
