如何在 GORM 中将嵌入结构体以 JSON 形式存储为单字段

本文介绍如何让 gorm 将 go 嵌入结构体（如 geopoint）序列化为 json 字符串并存入数据库单列，避免默认的关联建表行为，适用于地理坐标、配置对象等场景。

在使用 GORM 定义模型时，若直接嵌入一个结构体（如 GeoPoint），GORM 默认会将其识别为关联关系或嵌入字段，并尝试生成对应子表或展开为多个列——这往往不符合实际需求。例如，你希望将 Lat 和 Lon 作为一个逻辑整体以 JSON 格式（如 {"Lat":39.9042,"Lon":116.4074}）存入数据库的单一 point TEXT 或 JSON 类型字段中，而非拆成两列或新建表。

实现该目标的核心思路是：让嵌入结构体实现 GORM 的 Scanner 和 Valuer 接口，从而接管其数据库读写逻辑，完成自动 JSON 序列化与反序列化。

以下是一个完整、可直接复用的实践示例：

import (
    "database/sql/driver"
    "encoding/json"
    "gorm.io/gorm"
)

// GeoPoint 表示经纬度坐标点
type GeoPoint struct {
    Lat float64 `json:"lat"`
    Lon float64 `json:"lon"
`
}

// PointJSON 是用于 GORM 存储的包装类型，实现 Scanner & Valuer
type PointJSON struct {
    *GeoPoint
}

// Scan 实现 sql.Scanner 接口：从数据库读取 []byte 并反序列化为 GeoPoint
func (p *PointJSON) Scan(src interface{}) error {
    if src == nil {
        p.GeoPoint = nil
        return nil
    }
    b, ok := src.([]byte)
    if !ok {
        return fmt.Errorf("cannot scan %T into PointJSON", src)
    }
    var gp GeoPoint
    if err := json.Unmarshal(b, &gp); err != nil {
        return err
    }
    p.GeoPoint = &gp
    return nil
}

// Value 实现 driver.Valuer 接口：将 GeoPoint 序列化为 JSON 字符串写入数据库
func (p PointJSON) Value() (driver.Value, error) {
    if p.GeoPoint == nil {
        return nil, nil
    }
    return json.Marshal(p.GeoPoint)
}

// A 是主模型，其中 point 以 JSON 形式存储于单列
type A struct {
    ID    uint      `gorm:"primaryKey"`
    Name  string    `gorm:"size:100"`
    Point PointJSON `gorm:"column:point;type:json"` // 推荐使用 type:json（MySQL 5.7+/PostgreSQL），兼容性更好；若需兼容旧版 MySQL，可用 type:longtext
}

✅ 关键说明：

• PointJSON 是对 *GeoPoint 的封装类型，避免直接在 GeoPoint 上实现接口（防止污染原始结构体语义）。
• gorm:"column:point;type:json" 显式指定列名和数据库类型，type:json 可触发 GORM 对 JSON 字段的优化支持（如 PostgreSQL 的 JSONB、MySQL 的 JSON 类型）。
• 若数据库不支持原生 JSON 类型（如 SQLite 或旧版 MySQL），可将 type:json 替换为 type:longtext，效果一致。
• Scan 和 Value 方法必须同时实现，缺一不可；且注意处理 nil 值，确保空值可安全读写。

⚠️ 注意事项：

• 此方案不支持对 Lat/Lon 字段进行 SQL 层面的查询过滤（如 WHERE point->'$.lat' > 30），如需高效地理查询，建议单独拆分为 lat 和 lon 两列，并添加索引。
• 若使用 type:json，请确保数据库版本支持 JSON 类型，并在迁移时启用对应驱动能力（如 mysql.ParseTime=true&loc=Local 配合 json.RawMessage 等高级用法可进一步定制）。
• 所有嵌入结构体（如 Child、Address、Metadata）均可按此模式封装，统一复用 XXXJSON 模式。

通过该方法，你既能保持 Go 代码中清晰的结构化表达，又能在数据库层面实现扁平化、可维护的单字段存储，是 GORM 中处理“逻辑嵌入、物理扁平”场景的标准实践。