GORM 将 time.Time 存为字符串并非 bug，而是因底层驱动（如 mysql）未启用 parseTime=true 时，GORM 依赖 driver.Valuer/sql.Scanner 自动转换，但驱动将时间作为 []byte 或字符串返回；正确做法是自定义类型并完整实现 driver.Valuer、sql.Scanner、gorm.Marshaler 和 gorm.Unmarshaler 四个接口。
为什么 GORM 会把 time.Time 存成字符串？
这不是 bug，是 GORM 默认启用了 driver.Valuer 和 sql.Scanner 接口自动转换逻辑，但底层驱动（比如 mysql 或 postgres）对 time.Time 的处理不一致。例如用 github.com/go-sql-driver/mysql 时，若没显式配置 parseTime=true，GORM 读出来的 time.Time 字段可能被当成 []byte 或字符串，写入时又可能触发默认的 JSON 序列化逻辑。
自定义类型转换的核心，就是让 GORM 明确知道：这个 Go 类型 → 对应数据库里存什么、怎么存；从数据库读出来 → 怎么还原成 Go 值。
- 必须实现
driver.Valuer接口（控制写入） - 必须实现
sql.Scanner接口（控制读取） - 推荐额外实现
gorm.Marshaler和gorm.Unmarshaler（避免 GORM 内部 fallback 到 JSON）
怎么写一个带时区的 LocalTime 类型？
常见需求：所有时间字段统一按本地时区（如 Asia/Shanghai）存为 UTC 时间戳，但业务层操作时仍用本地语义。不能只靠 time.Local，因为 time.Local 是运行时全局设置，不可靠。
type LocalTime struct {
time.Time
}
func (lt LocalTime) Value() (driver.Value, error) {
// 强制转为上海时区再存 UTC 时间戳
sh := lt.In(time.FixedZone("CST", 8*60*60))
return sh.UTC(), nil
}
func (lt *LocalTime) Scan(value interface{}) error {
if value == nil {
lt.Time = time.Time{}
return nil
}
t, ok := value.(time.Time)
if !ok {
return fmt.Errorf("cannot scan %T into LocalTime", value)
}
// 从数据库读出的是 UTC，转回上海时区供业务使用
lt.Time = t.In(time.FixedZone("CST", 8*60*60))
return nil
}
// 避免 GORM 自动走 JSON 编解码
func (lt LocalTime) MarshalJSON() ([]byte, error) {
return lt.Time.MarshalJSON()
}
func (lt *LocalTime) UnmarshalJSON(data []byte) error {
return lt.Time.UnmarshalJSON(data)
}
注意：Scan 方法接收的是 *LocalTime 指针，否则无法修改原值；Value 返回的是 time.Time（UTC），确保数据库字段类型是 TIMESTAMP 或 TIMESTAMPTZ。
立即学习“go语言免费学习笔记（深入）”；
gorm.Model 里用自定义类型报 unsupported type 怎么办？
错误信息通常是：failed to initialize model: unsupported type xxx。根本原因是 GORM 在注册模型时尝试反射检查字段类型，而你的类型没实现完整接口，或嵌套太深（比如 map[string]CustomType）。
- 确认实现了全部四个接口：
driver.Valuer、sql.Scanner、gorm.Marshaler、gorm.Unmarshaler - 字段不能是未导出（小写开头）类型，GORM 反射不到
- 不要在结构体字段上直接用
type MyTime time.Time这种别名 —— 它不会继承原类型的接口实现，必须显式实现 - 如果用
gorm.ColumnType手动指定数据库类型（如columnType.Type = "timestamptz"），需配合RegisterModel或AutoMigrate前调用db.Callback().Create().Before("gorm:create").Register(...)，但通常没必要
JSON 字段里嵌套自定义类型会失效？
会。只要字段类型是 json.RawMessage、map[string]interface{} 或任意被 GORM 当作「非原生类型」处理的字段，GORM 就跳过自定义接口调用，直接走 json.Marshal/Unmarshal。此时 MarshalJSON 被调用，但 Value 和 Scan 完全不生效。
解决办法只有两个：
- 改用原生字段：把 JSON 结构拆成独立 struct 字段，每个字段用自定义类型
- 手动控制序列化：在业务层先调用自定义类型的
Value()得到中间值，再塞进 map/json，入库前不依赖 GORM 的自动转换
最易忽略的一点：GORM v2 中 sql.Scanner 的 Scan 方法签名是 func(src interface{}) error，不是 func(src interface{}) (interface{}, error) —— 后者是旧版写法，会导致静默失败。
