直接使用 datatypes.json 类型配合 gin 索引是性能与可维护性最佳平衡方案：需导入 gorm.io/datatypes，字段加 gorm:"type:jsonb" 标签，查询用 jsonquery，索引须手动建 gin 或表达式索引。
直接用 datatypes.JSON 类型 + GIN 索引，别手写 Value/Scan，也别用 string 或 []byte 做中间层 —— 这是性能和可维护性最平衡的路径。
用 datatypes.JSON 定义结构体字段
这是 GORM 官方为 PostgreSQL JSONB 提供的开箱即用类型，封装了序列化/反序列化、空值处理、SQL 绑定等细节，避免自己踩 driver.Value 接口的坑。
- 必须导入
gorm.io/datatypes，否则编译报错undefined: datatypes - 字段标签要显式写
gorm:"type:jsonb"，GORM 不会自动推断成jsonb（默认可能是text） - 如果字段允许为空，加
gorm:"default:null"；若设默认值，用gorm:"default:'{}'"或gorm:"default:'[]'" - 不要混用
datatypes.JSON和自定义JSONB类型，会导致Scan时类型不匹配 panic
示例：
import "gorm.io/datatypes"
type User struct {
ID uint `gorm:"primaryKey"`
Name string `gorm:"not null"`
Config datatypes.JSON `gorm:"type:jsonb;default:'{}'"`
}
插入和更新 JSONB 数据要走结构体赋值
不能把原始 JSON 字符串直接塞进 Config 字段，GORM 不会自动解析；也不能先 json.Marshal 成 []byte 再赋值 —— datatypes.JSON 内部已处理好。
- 插入时直接传 Go 结构体或 map：
user.Config = datatypes.JSON{`{"theme":"dark","lang":"zh"}`}（字符串）或user.Config = datatypes.JSON(map[string]interface{}{"theme": "dark"}) - 更新单个键推荐用原生 SQL：
db.Exec("UPDATE users SET config = jsonb_set(config, '{theme}', '\"light\"') WHERE id = ?", id)，GORM 的链式更新不支持嵌套路径修改 - 批量更新整个字段用
Save或Updates即可，例如db.Model(&u).Updates(map[string]interface{}{"config": newConf})
查询 JSONB 必须配合 datatypes.JSONQuery
直接写 Where("config->>'theme' = ?", "dark") 虽然能跑，但无法利用索引，且语法易错（比如漏掉单引号、混淆 -> 和 ->>）。GORM 提供的 JSONQuery 是类型安全的封装，生成的 SQL 更可靠。
-
datatypes.JSONQuery("config").Equals("dark", "theme")→ 对应config->>'theme' = 'dark' -
datatypes.JSONQuery("config").Contains("admin", "roles")→ 对应config @> '{"roles": ["admin"]}'（要求 roles 是数组） - 嵌套路径用点号分隔：
datatypes.JSONQuery("config").Equals("beijing", "address.city") - 注意：这些方法只在 WHERE 条件中生效，SELECT 中取子字段仍需原生 SQL 或
SELECT ... config->>'theme'
GIN 索引不是可选项，而是必选项
没建 GIN 索引时，哪怕只查 10 万行数据，config @> '{"theme":"dark"}' 也可能秒变全表扫描。PostgreSQL 的 GIN 索引对 JSONB 的路径匹配有专门优化，代价极小，收益极大。
- 建索引语句：
CREATE INDEX idx_users_config_gin ON users USING GIN (config) - 如果只高频查某个固定路径（如
config->>'theme'），可用表达式索引：CREATE INDEX idx_users_theme ON users ((config->>'theme'))，比 GIN 更轻量 - GORM 迁移不支持自动建 GIN 索引，必须手写 SQL 执行，或在部署脚本里单独处理
- 验证是否命中索引：用
EXPLAIN ANALYZE看执行计划里有没有Bitmap Heap Scan+Bitmap Index Scan
真正容易被忽略的是索引粒度 —— GIN 索引建在整列上看似“够用”，但当 JSONB 内容庞大（比如存了完整用户画像）、且只查少数几个键时，表达式索引的性能优势会非常明显，别图省事跳过这步。
