PostgreSQL 的 JSONB、数组、GIN 索引、UPSERT 和时区敏感类型在 Gin + GORM 或 database/sql 中需手动处理：JSONB 字段须用 json.RawMessage 加 type:jsonb 标签；GIN 索引需显式创建并配合 @> 等操作符使用；timestamptz 要在 DSN 中指定 TimeZone 并统一转 UTC；UPSERT 应优先用原生 ON CONFLICT 避免竞态。
PostgreSQL 的 JSONB、数组、GIN 索引、UPSERT 和时区敏感类型，在 Gin + GORM 或 database/sql 场景下不是开箱即用的——你得手动处理类型映射、驱动行为差异和 SQL 写法，否则会遇到 sql: Scan error on column index 2: unsupported Scan, storing driver.Value into type *map[string]interface{} 这类错误。
JSONB 字段在 GORM 中正确读写的坑
GORM 默认把 PostgreSQL 的 jsonb 字段当普通字符串扫，不自动反序列化。直接用 map[string]interface{} 或结构体字段接收会 panic。
- 必须给字段加
type:jsonb标签，且 Go 类型要用json.RawMessage或自定义类型（实现Scanner/Valuer接口） - 别用
map[string]interface{}直接接收：它无法保证键序，且 GORM 不支持深层嵌套自动绑定 - 如果用
pgx驱动替代lib/pq，json.RawMessage可直接 Scan，但 GORM v1.25+ 才原生支持pgx，v2 尚未 GA - 示例写法：
type Product struct { ID uint `gorm:"primaryKey"` Name string `gorm:"type:varchar(255)"` Specs json.RawMessage `gorm:"type:jsonb;not null"` }
GIN 索引对数组查询的实际效果
PostgreSQL 的 GIN 索引能加速 @>（包含）、&&（重叠）等数组操作，但 Gin 框架本身不感知索引——它只负责转发请求，真正起作用的是你在 SQL 或 GORM Where 中写的条件是否命中索引。
- 建表时要显式加索引：
CREATE INDEX idx_tags ON products USING GIN (tags); - GORM 查询必须用原生操作符，比如：
db.Where("tags @> ARRAY[?]::text[]", "feature_x").Find(&products) - 别写
db.Where("? = ANY(tags)", "feature_x")：它走顺序扫描，GIN 索引无效 -
database/sql场景下，参数占位符不能放在数组字面量里（如ARRAY[$1]），得拼成ARRAY[$1, $2]或用pq.Array()包装切片
时区敏感字段（timestamptz）在 Gin 请求中的处理
PostgreSQL 的 timestamptz 存的是 UTC 时间，但 Go 的 time.Time 默认按本地时区解析。若连接串没设 TimeZone，SELECT 出来的时间可能偏移数小时。
立即学习“go语言免费学习笔记（深入）”；
- DSN 中必须显式指定：
TimeZone=Asia/Shanghai（或UTC），否则lib/pq用time.Local解析 - Gin 接收前端传来的 ISO 时间字符串（如
"2026-08-11T14:30:00+08:00"）时，time.Parse默认生成带本地时区的time.Time，存入timestamptz前需统一转为 UTC：t.In(time.UTC) - 别依赖
time.Now()直接入库：它返回本地时间，入库后会被lib/pq按 DSN 中TimeZone转换，结果不可控 - 验证方法：查出时间后打印
t.Location().String()，应为Asia/Shanghai或UTC，而非Local
UPSERT（ON CONFLICT）在 GORM 中的兼容写法
GORM 的 FirstOrCreate 不等于 PostgreSQL 的 ON CONFLICT：前者是先 SELECT 再 INSERT，有竞态；后者是原子操作。高并发场景必须用原生 UPSERT。
- GORM v2 支持
Clauses(clause.OnConflict{...})，但只对Create生效，且冲突字段必须是唯一索引/主键列 - 更稳的方式是用
db.Exec执行原生 SQL：INSERT INTO users (id, name) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name - 注意
EXCLUDED是 PostgreSQL 关键字，不是变量名；GORM 的clause.Excluded在复杂场景下容易生成错 SQL - 如果用
pgx驱动，可直接传[]interface{}参数，无需担心lib/pq对ON CONFLICT的旧版语法限制
真正麻烦的不是语法，而是类型转换发生在哪一层：数据库驱动、GORM 中间层、还是你自己的 Scan 逻辑。少一层隐式转换，就少一个半夜排查的 bug。
