
本文详解 GORM 中 UUID 插入 MySQL BINARY(16) 字段失败(Error 1406)的根本原因:模型字段类型误用导致 UUID 被序列化为 36 字节字符串而非 16 字节二进制,提供完整可运行的修复方案与最佳实践。
本文详解 gorm 中 uuid 插入 mysql `binary(16)` 字段失败(error 1406)的根本原因:模型字段类型误用导致 uuid 被序列化为 36 字节字符串而非 16 字节二进制,提供完整可运行的修复方案与最佳实践。
在使用 GORM 将 UUID 存储到 MySQL 的 BINARY(16) 列时,常见错误是将结构体字段定义为 uuid.UUID 类型(如 github.com/satori/go.uuid.UUID),这会导致 GORM 在底层将其当作字符串处理——即使你调用 MarshalBinary(),GORM 仍可能因字段类型不匹配而将 UUID 的标准字符串表示(如 "16ac369b-e57f-471b-96f6-1068ead0bf98",共 36 字符)以字节形式写入 BINARY(16),从而触发 (Error 1406: Data too long for column 'user_id' at row 1)。
根本原因在于:GORM 的序列化行为由 Go 结构体字段类型决定,而非你手动传入的 []byte 值。若 UserID 字段声明为 uuid.UUID,GORM 会优先调用其 String() 方法(返回 36 字节字符串),而非尊重你通过 scope.SetColumn 设置的二进制切片。
✅ 正确做法是:将模型字段直接定义为 []byte,并确保 BeforeCreate 钩子生成并设置 16 字节的原始二进制数据:
import (
"github.com/jinzhu/gorm"
"github.com/satori/go.uuid"
)
type User struct {
ID uint `gorm:"primary_key"`
CreatedAt time.Time
UpdatedAt time.Time
DeletedAt *time.Time `sql:"index"`
UserID []byte `gorm:"column:user_id;type:binary(16);not null;unique_index"` // ✅ 关键:[]byte 类型
Username string `gorm:"size:255;not null;unique_index"`
Password string `gorm:"size:255"`
FirstName string `gorm:"size:255"`
LastName string `gorm:"size:255"`
Email string `gorm:"size:255"`
AddressID string `gorm:"size:255"`
}
func (u *User) BeforeCreate(scope *gorm.Scope) error {
// 检查是否已存在 userID(nil 切片表示未设置)
if len(u.UserID) == 0 {
uuidV4, err := uuid.NewV4()
if err != nil {
return err
}
binaryUUID, err := uuidV4.MarshalBinary()
if err != nil {
return err
}
scope.SetColumn("UserID", binaryUUID) // 注意:字段名需与结构体字段名一致(非数据库列名)
}
return nil
}⚠️ 注意事项:
-
scope.SetColumn("UserID", ...)中的"UserID"是 Go 结构体字段名(首字母大写),不是数据库列名user_id; - 使用
[]byte字段后,GORM 会原样映射为BINARY(16),无需额外扫描/转换; - 若需从数据库读取后还原为
uuid.UUID实例,可在业务层调用uuid.FromBytes(u.UserID); - 推荐升级至现代 UUID 库(如
github.com/google/uuid),它更轻量且与encoding/binary兼容性更好;
? 扩展建议:为提升可维护性,可封装 UUID 生成逻辑为结构体方法或自定义 GORM 数据类型(实现 Scanner / Valuer 接口),但对多数 CRUD 场景,上述 []byte + BeforeCreate 方案已足够简洁、高效且零歧义。
最终验证:插入后执行 SELECT HEX(user_id) FROM users LIMIT 1;,应返回 32 位十六进制字符串(如 16AC369BE57F471B96F61068EAD0BF98),长度严格为 32,对应 16 字节,彻底规避 Data too long 错误。

















