Bun 是 SQL 构建器 + 运行时映射器，非 ORM：不生成 SQL、不维护状态、无懒加载；需手动写查询逻辑，显式调用 Scan/Exec，结构体须标注 pk/array 标签，JSONB 用 json.RawMessage，事务需正确传递 tx 实例，分页推荐游标而非 OFFSET/LIMIT。
为什么 Bun 不是“ORM”而是“SQL 构建器 + 运行时映射器”
Bun 的定位常被误读为 ORM，但它实际不生成 SQL、不维护对象状态、也不做懒加载或关联预加载的自动推导。它更像一个带结构体映射能力的 bun.DB + QueryBuilder 组合。这意味着你得自己写 SELECT、JOIN、WHERE 逻辑，Bun 只负责把结果塞进 struct，或把 struct 翻译成参数化 SQL。
常见错误现象：db.NewSelect().Model(&users).Where("age > ?", 18) 看似简单，但如果你忘了加 .Scan(ctx)，它根本不会执行；或者用 db.Model(&u).Set("name = ?", "x").WherePK() 更新时漏了主键字段标签，就会更新全表。
- 所有查询必须显式调用
.Scan()、.Exec()或.Count()才真正触发数据库操作 -
Model()的参数必须是指针（&user），否则Scan()无法写入 - Bun 不自动识别
ID字段为主键——必须用sql:",pk"标签声明 - 嵌套 struct 关联需手动
.Relation("Profile")，且被关联 struct 必须有外键字段（如ProfileID int）并打上对应标签
怎么让 Bun 正确映射 PostgreSQL 的 JSONB 和数组字段
PostgreSQL 的 jsonb 和 text[] 在 Go 中没有默认对应类型，Bun 不会自动转换。直接用 string 接 jsonb 会导致扫描失败，报错类似 can't scan into dest: cannot assign <nil> to *string</nil>（尤其当字段允许 NULL 时）。
使用场景：API 响应元数据存为 jsonb，权限列表存在 text[] 中。
立即学习“go语言免费学习笔记（深入）”；
-
jsonb字段推荐用json.RawMessage类型，避免提前解析开销；若需结构化访问，定义具体 struct 并实现driver.Valuer+sql.Scanner -
text[]对应[]string，但必须加pg:",array"标签（Bun 用的是 pg 驱动，不是 database/sql 原生数组支持） - 别用
interface{}接 jsonb——Bun 无法推断目标类型，会 panic - NULL 值处理：字段类型用指针（如
*json.RawMessage或*[]string），否则 NULL 扫描时报错
事务里用 Bun 更新失败却没报错？检查 Context 和 ErrGroup 配合方式
Bun 的 db.InTx() 返回新 DB 实例，所有操作必须用这个实例，而不是原始 db。更隐蔽的问题是：在 errgroup.Group 里并发调用 tx.Model().Update()，如果某个 goroutine 拿到的 tx 是闭包外的变量，可能实际用的是同一个 tx 实例，而 Bun 的事务内部不是 goroutine-safe 的——会导致竞态或静默失败。
- 事务内所有 DB 操作必须用传入回调函数里的
tx，不能复用外部db - 不要在
errgroup.Go()回调里直接捕获tx变量；要么显式传参，要么用func(tx *bun.DB) error包一层 - 事务中任何一步出错（比如约束冲突），Bun 不自动 rollback——必须靠
return err触发InTx()的回滚逻辑 - 注意 context 超时：若
InTx()传入的 ctx 已 cancel，后续tx.Model().Insert()会立即返回context canceled，但不会提示“事务已失效”
用 Bun 做分页时 OFFSET LIMIT 性能差？改用游标分页 + WHERE
Bun 默认分页靠 .Offset().Limit()，在千万级表上 OFFSET 1000000 会拖垮查询。这不是 Bun 的问题，而是 PostgreSQL 自身限制。但很多人卡在“Bun 没提供游标分页 DSL”，就硬扛着用 offset。
实际上 Bun 完全支持手写游标逻辑：用上一页最后一条记录的排序字段（如 id 或 created_at）构造 WHERE id > ? 条件，再配 LIMIT。
- 不要依赖
bun.Paginator——它只是封装 offset/limit，不解决底层性能问题 - 游标字段必须有索引（
CREATE INDEX ON users (created_at, id)），且排序方向一致（ORDER BY created_at DESC, id DESC） - 游标值要用上一页最后一条的原始值（不是字符串拼接后的），避免类型转换误差
- 首次请求无游标时，用
WHERE 1=1占位，保持 SQL 结构统一，别动态拼 SQL
复杂点在于游标需要业务语义对齐：比如按时间分页时，同一秒可能有多条记录，必须用第二排序字段（如 id）打破平局，否则漏数据或重复。这点容易被忽略，一上线就出错。
