mworm

mworm - High-Performance PostgreSQL ORM for Go

mworm 是一个专为 PostgreSQL 深度打造的高性能 Go 语言 ORM 库，基于 sqlx 与 pgx 封装。

它彻底摒弃了多方言兼容的历史包袱，全面释放 PostgreSQL 的核心杀手级特性：

• 🚀 一等公民级 RETURNING：支持链式 .Returning("id").Scan(&id) 与 .Returning("*").One(&model)，单次往返完成写入并直接回填自增主键与默认字段；
• ⚡ 原生 JSONB 运算套件：提供包含 (@>)、被包含 (<@)、键存在检测 (jsonb_exists)、路径查询提取 (#>>) 等原生支持，无缝适配 GIN 倒排索引；
• 📦 PostgreSQL 原生数组 (Array) 运算：支持数组包含 (@>)、数组相交/重叠 (&&)、元素包含 (? = ANY(column)) 以及单参数高性能替代 IN (column = ANY(?))；
• 🔍 原生大小写不敏感匹配 (ILIKE)：支持 ILike("name", "%茅台%") 与结构体自动提取，杜绝 LOWER() 破坏 B-Tree 索引；
• 🛡️ PostgreSQL 标识符规范：统一进行标识符双引号规范保护，消除保留字冲突；
• 🔄 高性能 BulkInsert 与原子分批 (Chunk)：原生 $1, $2... 占位符风格，支持自动事务分批与 Context 超时秒级取消短路；
• 📥 原生 Binary COPY 批量导入 (CopyFrom)：基于 pgx 的 COPY ... FROM STDIN BINARY 协议，不生成 INSERT 语句与占位符，适合行情、K 线等大批量追加写入；可挂载到现有事务中随事务提交或回滚；
• 🔒 防呆 WherePK 安全防线：更新/删除时主键空值强行阻断，杜绝全表误更新与误删除；
• 🧱 全表操作拦截：无 WHERE 的 UPDATE/DELETE 默认拒绝执行（ErrFullTableOperation），需显式 AllowFullTable()；
• 🔐 行级锁与事务选项：ForUpdate() / ForUpdate("SKIP LOCKED") 与 TransactionWithOptions 支持隔离级别/只读事务。

v0.5.0 变更说明（自 v0.4.x 升级必读）

新增能力

能力	说明
CopyFrom(slice) / client.CopyFrom(slice)	PostgreSQL 原生 Binary COPY 批量导入，支持 Table（含 schema.table）、Fields、ExcludeFields、Tx、WithContext 链式配置；仅追加写入，不支持冲突更新
AllowFullTable()	显式放行无条件 UPDATE/DELETE
ForUpdate(mode...)	追加 FOR UPDATE，mode 仅允许 NOWAIT / SKIP LOCKED
TransactionWithOptions(ctx, opts, fn)	托管事务支持 sql.TxOptions（隔离级别、只读），全局与 Client 均提供
RawSQL(sql, args...) / client.RawSQL(sql, args...)	原生查询支持参数绑定，? 与 $N 均可
SetExpression(tag, expr, args...)	表达式更新支持 $N 参数，如原子扣减 SetExpression("points", "points - $1", n)
db:"updated_at,at"	带 at 标记的列在每次 UPDATE 时自动写入 now()
IN(tag, slice)	切片参数自动展开；空 IN 生成恒假条件 1=0，空 NOT IN 自动忽略
uint 系列字段	查询结果支持绑定到 uint/uint8/.../uint64（负数或溢出返回错误）
WhereIf(cond, cgs...)	根据布尔条件流式动态追加条件，true 时生效，false 时忽略，消除多分支样板代码
Pluck(field, dest)	单列轻量切片提取（&[]string/&[]int64等），强制限定投影列，杜绝大宽表 SELECT * 开销
嵌套事务与 SAVEPOINT	托管事务检测到活跃 context 时自动转为 PostgreSQL 原生保存点，支持局部异常安全回滚
Context 事务自动传播	通过 WithTx(ctx, tx) 注入后，下游 .WithContext(ctx) 自动继承事务，无需显式 .Tx(tx)
编译期强类型 Fluent Builder	采用 Typestate 状态机模式，SELECT/INSERT/UPDATE/DELETE 分别返回独立强类型构建器（*SelectBuilder, *InsertBuilder, *UpdateBuilder, *DeleteBuilder）。IDE 仅展示当前动词合法方法，编译期直接阻断跨操作错配

行为变更（可能影响存量代码）

1. 无 WHERE 的 UPDATE/DELETE 返回 ErrFullTableOperation，需改为 AllowFullTable() 显式放行。
2. Upsert(...) 自动模式只更新本次 INSERT 实际写入的列，不再用零值覆盖未写入的列；显式 DoUpdate(...) 行为不变。
3. SetField / Having / Raw / Exists / SubQuery 全部改为参数化绑定（此前部分为字面量拼接），FullSQL() 中会看到 ? 占位符。
4. Many 为覆盖语义：执行前清空目标切片（结果为空时得到非 nil 空切片）；行绑定失败直接返回错误，不再静默跳过。
5. OnSlowQuery 回调与慢查询日志收到的是参数化 SQL（不含参数值，避免敏感数据落日志）；仅调试模式会内插参数值。
6. Count/Sum/... 在带 JOIN / GROUP BY / DISTINCT 时自动包裹子查询计数，Paginate 联表分页计数结果正确。
7. PAGE / Paginate 的 page < 1 自动按第 1 页处理。
8. WherePK() 逐个校验主键值：复合主键任一值为空即返回 ErrFullTableOperation（此前会静默丢弃空主键，生成残缺 WHERE 误操作多行），SELECT 同样生效。
9. UPDATE/DELETE 中显式传值的条件（如 Eq("deviceToken", token)）值为空时返回 ErrFullTableOperation，含 AndGroup/OrGroup 嵌套内；SELECT 仍保持空值自动忽略的搜索语义。
10. SQLParams.TxExec/TxMustExec 遇到构建期错误时直接返回错误或 panic，绝不执行残缺 SQL；占位符改用 tx.Rebind，不再依赖全局 SqlxDB。
11. 时间戳映射到 string 字段：仅零点整输出日期（DATE 列行为不变），其余一律输出 2006-01-02 15:04:05（此前分钟或小时为 0 的时刻，如 15:00:00，会被截断为仅日期）。
12. 编译期强类型构建器与动词物理隔离：mworm.SELECT、mworm.INSERT、mworm.UPDATE、mworm.DELETE 不再返回同一单体 *OrmModel，而是返回裁剪好专属合法方法集的强类型构建器（*SelectBuilder、*InsertBuilder、*UpdateBuilder、*DeleteBuilder）。在 INSERT 敲 . 物理不可见 Where/Limit，在 SELECT 敲 . 物理不可见 SetField/Exec 等；强行错配调用时，Go 编译器直接阻断。需要直接访问底层 *OrmModel 时可通过 .Model() 无感提取。

安装

go get github.com/ccxdd/mworm

快速开始

1. 初始化连接

在使用 mworm 之前，需要先绑定 sqlx.DB 对象（推荐使用官方高性能 pgx 驱动）：

import (
    "github.com/ccxdd/mworm"
    "github.com/jmoiron/sqlx"
    _ "github.com/jackc/pgx/v5/stdlib"
    "log"
)

func initDB() {
    // 连接 PostgreSQL 数据库
    db, err := sqlx.Connect("pgx", "postgres://user:password@localhost:5432/dbname?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    
    // 绑定到 mworm 全局实例（亦可使用 mworm.New(db) 创建独立实例）
    err = mworm.BindDB(db)
    if err != nil {
        log.Fatal(err)
    }
}

2. 定义模型与 Tag 规范

在 mworm 中，模型定义必须同时提供 db 和 json tag。

核心规范：调用时使用 json tag 还是 db tag？

• db tag：仅用于映射数据库底层的物理列名（以及标识主键 pk、排除更新 eu 等）。
• json tag：除了用于 JSON 序列化，在调用 mworm 的所有链式查询、条件构造器（如 mworm.Eq、mworm.And、mworm.Or 等）、排序（Asc、Desc）、字段设置（SetField、SetExpression）时，传入的字段名参数必须使用 json tag，绝对不能使用 db tag。

mworm 底层会自动解析并将传入的 json tag 转换为对应的 db tag 以生成正确的 SQL 语句。

单主键模型：

type User struct {
    ID        int64     `json:"id" db:"id,pk"`          // pk 标识主键
    Name      string    `json:"name" db:"name"`
    Age       int       `json:"age" db:"age"`
}

复合主键模型： mworm 完美支持多字段复合主键，在 WherePK、Upsert 等操作中会自动识别所有标记为 pk 的字段。

type Favorite struct {
    UserId   int64  `json:"userId" db:"user_id,pk"`     // 查询条件传参需用 json tag: "userId"
    Code     string `json:"code" db:"code,pk"`          // 多个 pk 标记构成的复合主键
    Name     string `json:"name" db:"name"`
}

func (f Favorite) TableName() string {
    return "favorite"
}

常用功能

1. CRUD 操作

插入 (Insert)

user := User{Name: "Tom", Age: 18}
// 基础插入
err := mworm.INSERT(user).Exec()

// PostgreSQL 链式 RETURNING: 获取单列或自增 ID
var id int64
err := mworm.INSERT(user).Returning("id").Scan(&id)

// PostgreSQL 链式 RETURNING: 单次往返直接回填完整实体结构体
var createdUser User
err := mworm.INSERT(user).Returning("*").One(&createdUser)

原生 COPY 批量导入 (CopyFrom) 与批量插入 (BulkInsert)

mworm 提供两种批量写入方式，按是否需要冲突处理选择：

1. CopyFrom（大批量纯追加写入）：基于 PostgreSQL 原生 COPY ... FROM STDIN BINARY 二进制协议，不生成 INSERT 语句与参数占位符，整批复用同一个行缓冲切片。适合分时、K 线、资金流等大批量追加写入。支持挂载现有事务（随事务提交/回滚）与 Context 超时取消；
2. BulkInsert（需要 Upsert / OnConflict 时）：生成单条 INSERT INTO ... VALUES (...), (...)，支持 .Upsert()、.DoNothing()、.OnConflict().DoUpdate() 与 .Chunk(size) 自动分批。

// 1. CopyFrom 原生 COPY 批量导入
ticks := []StockTick{
    {Code: "600519", Price: 1800.5, Volume: 100, Time: time.Now()},
    // ... 数万行分时数据
}

// 基础导入（排除自增主键 id），返回写入行数
n, err := mworm.CopyFrom(ticks).
    ExcludeFields("id").
    Exec()

// 显式指定目标表（支持 schema.table）与白名单列（json tag，未知字段会返回错误）
n, err = mworm.CopyFrom(ticks).
    Table("market.stock_ticks_202610").
    Fields("code", "price", "volume", "time").
    Exec()

// 事务中执行：与事务内其他 SQL 共用同一连接，随事务提交或回滚
err = mworm.Transaction(ctx, func(tx *sqlx.Tx) error {
    _, err := mworm.CopyFrom(ticks).
        Tx(tx).
        ExcludeFields("id").
        Exec()
    return err
})

// 2. BulkInsert 批量插入（支持 Upsert 冲突更新）
users := []User{
    {ID: 1, Name: "Alice", Age: 20},
    {ID: 2, Name: "Bob", Age: 25},
}
// 遇到主键冲突时自动更新非主键字段
err = mworm.BulkInsert(users).
    Upsert("id").
    Chunk(500). // 超过 500 行自动原子分批执行
    Exec()

CopyFrom 使用约束

• 仅支持纯追加写入，遇到唯一键冲突会整批失败；需要冲突更新请使用 BulkInsert().Upsert()。
• 带 ei 标记的字段不会写入；结构体指针切片中含 nil 元素时返回错误，不会写入任何数据。
• 传入已提交或已回滚的事务时返回 sql.ErrTxDone。
• 事务模式通过读取 database/sql 内部字段获取底层 pgx 连接：同一事务在 CopyFrom 执行期间不要在其他 goroutine 中并发使用。

查询 (Select)

// 单条查询 (注意: 传入的字段名使用 json tag "id")
var user User
err := mworm.SELECT(User{}).
    Where(mworm.Eq("id", 1)).
    One(&user)

// 多条查询 (注意: 传入的字段名使用 json tag "age")
var users []User
err := mworm.SELECT(User{}).
    Where(mworm.Gt("age", 18)).
    Asc("age").
    Limit(10).
    Many(&users)

// 单列切片快速提取 (Pluck) - 强制限定投影列，杜绝 SELECT * 大宽表开销
var codes []string
err = mworm.SELECT(StockInfo{}).
    Where(mworm.Eq("industry", "白酒")).
    Pluck("code", &codes)

更新 (Update)

// 更新整个结构体（非空字段）
user.Name = "Jerry"
err := mworm.UPDATE(user).
    Where(mworm.Eq("id", 1)).
    Exec()

// 使用 WherePK() 自动根据主键更新 (支持单/复合主键)
// 1. 自动根据结构体中的 pk 字段生成 WHERE 条件
// 2. 自动在 SET 子句中排除主键字段，防止主键被修改
err := mworm.UPDATE(fav).WherePK().Exec()

// 更新指定字段 (注意: 传入的字段名使用 json tag "name", "status")
err := mworm.UPDATE(User{}).
    SetField("name", "Jerry").
    SetField("status", 2).
    Where(mworm.Eq("id", 1)).
    Exec()

// 使用自定义表达式更新 (SetExpression) (注意: 传入的字段名使用 json tag "age", "data")
err := mworm.UPDATE(User{}).
    SetExpression("age", "age + 1").
    SetExpression("data", "jsonb_set(data, '{last_active}', '\"2026-04-01\"')").
    Where(mworm.Eq("id", 1)).
    Exec()

// 表达式带参数 + 条件更新 = 原子扣减（余额不足时 0 行受影响，返回 ErrNoRowsAffected）
err := mworm.UPDATE(Account{}).
    SetExpression("points", "points - $1", 38).
    Where(mworm.Eq("id", uid), mworm.Gte("points", 38)).
    Exec()

// 更新空值或零值 (AllowEmpty) (默认情况下，结构体空值字段在 UPDATE 时会被忽略)
// 传入需要允许更新空值的字段的 json tag
err := mworm.UPDATE(User{Name: ""}).
    AllowEmpty("name").
    Where(mworm.Eq("id", 1)).
    Exec()

// 带 at 标记的列（如 `db:"updated_at,at"`）每次 UPDATE 自动写入 now()，无需手动赋值

删除 (Delete)

// 使用指定条件删除 (注意: 传入的字段名使用 json tag "id")
err := mworm.DELETE(User{}).
    Where(mworm.Eq("id", 1)).
    Exec()

// 使用主键删除
err := mworm.DELETE(fav).WherePK().Exec()

// 无 WHERE 的 UPDATE/DELETE 默认被拦截（ErrFullTableOperation），确需全表操作须显式放行
err := mworm.DELETE(TmpLog{}).AllowFullTable().Exec()

2. 条件构造

mworm 提供了丰富的条件构造器，支持链式调用。所有条件构造器的第一个字段名参数均需使用 json tag。

// 基础条件
mworm.And("name", "age")      // name = ? AND age = ? (使用 json tag "name", "age")
mworm.Eq("status", 1)         // status = 1 (使用 json tag "status")
mworm.Gt("age", 18)           // age > 18 (使用 json tag "age")
mworm.Lt("age", 60)           // age < 60
mworm.IN("status", 1, 2, 3)   // status IN (1, 2, 3)
mworm.NotIN("status", 4, 5)   // status NOT IN (4, 5)
mworm.Between("age", 18, 60)  // age BETWEEN 18 AND 60
mworm.Like("name")            // name LIKE '%value%'
mworm.ILike("name")           // name ILIKE '%value%' (PostgreSQL 忽略大小写)
mworm.NEqILike("name")        // name NOT ILIKE '%value%' (PostgreSQL 忽略大小写)

// 自动忽略空值 (非常适合搜索表单)
// 如果 name 或 age 为空值/零值，则该条件自动被忽略
mworm.AndAuto("name", "age")

// 组合条件
orm := mworm.SELECT(User{}).Where(
    mworm.AndAuto("name"),
    mworm.Gte("age", 18),
    mworm.NotIN("status", 0, -1),
    mworm.Between("createdAt", "2024-01-01", "2024-12-31"), // 使用 json tag "createdAt"
)

// 流式动态条件 (WhereIf) - true 时追加条件，false 时直接忽略
orm = mworm.SELECT(User{}).
    Where(mworm.Eq("status", 1)).
    WhereIf(keyword != "", mworm.ILike("name", "%"+keyword+"%")).
    WhereIf(minAge > 0, mworm.Gte("age", minAge))

OR/AND 嵌套分组

// (status=1 OR status=2) AND age>=18
mworm.SELECT(User{}).Where(
    mworm.OrGroup(mworm.Eq("status", 1), mworm.Eq("status", 2)),
    mworm.Gte("age", 18),
)
// → WHERE (status=? OR status=?) AND age>=?

// (age>=18 AND age<=60)
mworm.SELECT(User{}).Where(
    mworm.AndGroup(mworm.Gte("age", 18), mworm.Lte("age", 60)),
)
// → WHERE (age>=? AND age<=?)

EXISTS / NOT EXISTS

// EXISTS 子查询
mworm.SELECT(User{}).Where(
    mworm.Exists("SELECT 1 FROM orders WHERE orders.user_id = users.id"),
)

// NOT EXISTS 带参数
mworm.SELECT(User{}).Where(
    mworm.NotExists("SELECT 1 FROM blacklist WHERE user_id = users.id AND status = $1", "blocked"),
)

子查询 (SubQuery)

// WHERE id IN (子查询) (注意: 传入的字段名使用 json tag "id")
mworm.SELECT(User{}).Where(
    mworm.SubQuery("id", "IN", "SELECT user_id FROM orders WHERE amount > $1", 100),
)
// → WHERE id IN (SELECT user_id FROM orders WHERE amount > ?)

3. 聚合查询

// 计数
count, err := mworm.SELECT(User{}).Where(mworm.Gt("age", 18)).Count("*")

// 求和 (使用 json tag "score")
sum, err := mworm.SELECT(User{}).Where(mworm.Gt("age", 0)).Sum("score")

// 平均值 (使用 json tag "age")
avg, err := mworm.SELECT(User{}).Avg("age")

// 最小值 (使用 json tag "score")
min, err := mworm.SELECT(User{}).Min("score")

// 最大值 (使用 json tag "score")
max, err := mworm.SELECT(User{}).Max("score")

4. 分页查询

mworm.PAGE 提供高效的分页查询。

// page: 当前页码, pageSize: 每页数量
// excludeTags: 不需要返回的字段 json tag 数组
result, err := mworm.PAGE(User{}, 1, 10, []string{"password"}, 
    mworm.AndAuto("name"), // 搜索条件
    mworm.Desc("createdAt"), // 排序 (使用 json tag "createdAt")
)

if err != nil {
    log.Fatal(err)
}
fmt.Printf("Total: %d, List: %v\n", result.Total, result.List)

5. Upsert (ON CONFLICT)

PostgreSQL 的 INSERT ON CONFLICT 支持。

// 冲突时更新指定字段 (使用 json tag "name", "age")
err := mworm.INSERT(user).OnConflict("id").DoUpdate("name", "age").Exec()
// → INSERT INTO users (...) VALUES (...) ON CONFLICT (id) DO UPDATE SET name=EXCLUDED.name, age=EXCLUDED.age

// 极致简化的 Upsert (自动推断需要更新的字段，冲突字段使用 json tag "id")
// 仅更新本次 INSERT 实际写入的列，未写入（零值被忽略）的列保持数据库原值
err := mworm.INSERT(user).Upsert("id").Exec()

// 冲突时忽略
err := mworm.INSERT(user).OnConflict("id").DoNothing().Exec()
// → INSERT INTO users (...) VALUES (...) ON CONFLICT (id) DO NOTHING

6. 批量插入（BulkInsert）

BulkInsert 将同类型 slice 的 N 行数据合并为一条 SQL 发送给数据库，相比在循环中逐条调用 INSERT，数据库往返从 N 次降为 1 次，写入耗时从秒级降至毫秒级。

基础用法

// 准备 slice，元素类型须实现 ORMInterface（即有 TableName() 方法）
rows := []MoneyFlowMin{
    {TradeDate: "20260814", TradeMin: "0930", ThemeSymbol: "A", MainNetAmount: 100},
    {TradeDate: "20260814", TradeMin: "0930", ThemeSymbol: "B", MainNetAmount: -50},
    // ... 数百行
}

// 纯 INSERT（有冲突会报错）
err := mworm.BulkInsert(rows).Exec()

// Upsert：冲突时自动更新非冲突列（推荐）
// 冲突字段使用 json tag
err := mworm.BulkInsert(rows).
    Upsert("tradedate", "trademin", "theme_symbol").
    Exec()

// 冲突时忽略（不报错，不更新）
err := mworm.BulkInsert(rows).
    DoNothing("tradedate", "trademin", "theme_symbol").
    Exec()

// 手动指定冲突列和需要更新的列
err := mworm.BulkInsert(rows).
    OnConflict("tradedate", "trademin", "theme_symbol").
    DoUpdate("main_net_amount", "main_buy_amount").
    Exec()

排除某些列

// 排除 updated_at 列不写入（使用 json tag）
err := mworm.BulkInsert(rows).
    ExcludeFields("updatedAt").
    Upsert("id").
    Exec()

自动分批 (Chunking)

当批量写入数据量极大（如数千至上万行金融时序数据）时，单条 SQL 绑定参数可能超过数据库限制（如 PostgreSQL 的 65,535 参数上限）。可通过 .Chunk(size) 指定单批写入行数，mworm 会在事务中自动按批次执行，确保全量成功或全量回滚：

// 每批 1000 行分批写入，自动在同一事务中原子执行
err := mworm.BulkInsert(largeMinuteBars).
    Chunk(1000).
    OnConflict("code", "date", "time").
    DoNothing().
    Exec()

与 Batch / BatchArray 的区别

	Batch / BatchArray	BulkInsert
SQL 语句数量	N 条（每行一条 INSERT）	1 条
事务	1 个事务	1 个事务（内部自动管理）
数据库往返	N 次	1 次
适用场景	多种不同 ORM 操作混合（INSERT + UPDATE 等）	同类型 slice 批量写入
错误粒度	可逐行处理	全批成功或全批回滚

注意事项

零值字段行为：BulkInsert 对所有行全列写入（含零值），与单行 INSERT 会跳过零值字段的行为不同。
若某列可能为零且不希望写入，请用 ExcludeFields("jsonTag") 显式排除。

生成的 SQL 示例（3 行，9 列）：

INSERT INTO moneyflow_min
  (tradedate, trademin, theme_symbol, theme_name, level, p_symbol,
   main_net_amount, main_buy_amount, main_sell_amount)
VALUES
  ($1, $2, $3, $4, $5, $6, $7, $8, $9),
  ($10, $11, $12, $13, $14, $15, $16, $17, $18),
  ($19, $20, $21, $22, $23, $24, $25, $26, $27)
ON CONFLICT (tradedate, trademin, theme_symbol) DO UPDATE SET
  theme_name = EXCLUDED.theme_name,
  main_net_amount = EXCLUDED.main_net_amount,
  ...

6. JOIN 查询

mworm.SELECT(User{}).
    Join(mworm.LeftJoin("orders", "o").
        On(mworm.JoinOn("t.id = o.user_id")).
        Select("order_no", "amount")).
    Where(mworm.Eq("t.is_active", true)).
    Many(&results)

7. 高级特性

批量操作与事务

// 批量执行多个操作
err := mworm.Batch(
    mworm.INSERT(User{Name: "A"}),
    mworm.INSERT(User{Name: "B"}),
)

// 事务支持
err := mworm.BatchFunc(func(tx *sqlx.Tx) error {
    // 在此处使用 tx 执行原生 sqlx 操作
    return nil
})

原生 SQL

// 执行原生 SQL（$N 或 ? 占位符均可）
mworm.ExecRawSQL("UPDATE users SET status = $1 WHERE id = $2", 1, 100)

// 原生 SQL 查询映射（支持参数绑定）
var users []User
mworm.RawSQL("SELECT * FROM users WHERE age > $1 AND status = $2", 18, 1).Many(&users)

JSONB 支持 (PostgreSQL)

// 将查询结果聚合为 JSONB List
jsonStr, err := mworm.SELECT(User{}).JsonbListString()

// 将查询结果聚合为 JSONB Map
jsonMap, err := mworm.SELECT(User{}).JsonbMapString("id", "name")

// 复杂 JSONB & 数组查询条件 (使用 json tag "data", "tags")
mworm.SELECT(User{}).Where(
    mworm.JsonbContains("data", `{"role": "admin"}`), // data @> ?
    mworm.JsonbHasKey("data", "last_login"),          // data ? ?
    mworm.ArrayAny("tags", "golang"),                 // tags = ANY(?)
    mworm.ArrayOverlap("tags", []string{"a", "b"}),    // tags && ARRAY[...]
)

// 通用 PostgreSQL 运算符
mworm.PgOp("tags", "@>", `{"go"}`)

// 结构体与切片字段原生自动序列化入库：
// 当模型中包含未实现 driver.Valuer 的嵌套 struct/切片时（对应数据库 JSON/JSONB 列），
// INSERT、UPDATE 及 BulkInsert 时会自动通过 sonic 序列化为规范 JSON 文本传递给底层驱动，无需手动序列化。
type Profile struct {
    Age  int    `json:"age"`
    City string `json:"city"`
}
type UserInfo struct {
    ID      int64   `json:"id" db:"id,pk"`
    Profile Profile `json:"profile" db:"profile"` // 自动存为 JSONB
}
mworm.INSERT(UserInfo{ID: 1, Profile: Profile{Age: 18, City: "Shanghai"}}).Exec()

CTE (Common Table Expressions)

// 使用 WITH 子句构建 CTE
orm := mworm.SELECT(User{}).
    Where(mworm.Eq("status", 1)).
    With("active_users") // 定义 CTE 表名

// 生成: WITH active_users AS (SELECT * FROM users WHERE status=1) SELECT * FROM active_users
result := orm.FullSQL()

GROUP BY 分组

var result []struct {
    Name  string `json:"name" db:"name"`
    Count int    `json:"count" db:"count"`
}
mworm.SELECT(User{}).
    GroupBy(mworm.Fields("name"), mworm.Raw(`count(*)`)).
    Having("count(name) > $1", 1).
    Many(&result)

动态表名 (Table)

当模型没有定义 TableName() 方法，或者表名需要动态变化时（如分表场景）：

// 显式指定表名进行查询
var users []User
err := mworm.Table("users_2026").
    Select(User{}).
    Where(mworm.Gt("age", 18)).
    Many(&users)

条件分支 (If)

用于在链式调用中根据业务逻辑条件动态拼接查询条件，避免打断链式调用：

// 根据 limitVar 的值动态决定是否添加 Limit 限制
err := mworm.SELECT(User{}).
    Where(mworm.Eq("status", 1)).
    If(func(o *mworm.OrmModel) {
        if limitVar > 0 {
            o.Limit(limitVar)
        }
    }).
    Many(&users)

JSONB 直接映射反序列化 (JsonbMap / JsonbList)

直接将 JSONB 聚合查询结果反序列化映射为 Go 结构体/切片，底层集成高性能 sonic 库：

// JsonbMap: 将聚合结果直接映射为 map
var idMap = make(map[string]string)
err := mworm.SELECT(User{}).JsonbMap(&idMap, "nickname", "phone")

// JsonbList: 将列表直接反序列化为切片
var userList []User
err := mworm.SELECT(User{}).JsonbList(&userList)

调试

开启调试模式，打印生成的 SQL 语句：

mworm.SELECT(User{}).Log(true).Many(&users)
// 或者全局开启
mworm.DebugMode = true

字段常量生成器

使用字段常量替代字符串，提供编译期检查和 IDE 自动补全。生成的常量映射的即是字段的 json tag。

使用示例

假设你的项目结构如下：

myproject/
├── go.mod           # require github.com/ccxdd/mworm
├── models/
│   ├── user.go      # 包含 User 结构体
│   └── order.go     # 包含 Order 结构体
└── main.go

运行生成器：

cd /path/to/myproject

// 方式1：直接运行（推荐，无需安装）
go run github.com/ccxdd/mworm/cmd/fieldgen -dir=models/ -r

// 方式2：全局安装后使用
go install github.com/ccxdd/mworm/cmd/fieldgen@latest
fieldgen -dir=models/ -r

或在模型文件中添加 go generate 指令：

//go:generate go run github.com/ccxdd/mworm/cmd/fieldgen -src=$GOFILE

type User struct {
    // ...
}

然后运行 go generate ./... 即可自动生成。

生成结果：

models/
├── user.go
├── user_fields.go      ← 自动生成
├── order.go
└── order_fields.go     ← 自动生成

生成代码示例

// user_fields.go（自动生成）
var UserF = struct {
    ID        string
    Name      string
    CreatedAt string
}{
    ID:        "id",            // 映射 json tag "id"
    Name:      "name",          // 映射 json tag "name"
    CreatedAt: "createdAt",     // 映射 json tag "createdAt"
}

使用效果

import "myproject/models"

// 之前（容易拼错）
mworm.SELECT(user).Where(mworm.And("createdAt", "name"))

// 之后（类型安全，IDE 自动补全，且保证使用的是 json tag）
mworm.SELECT(user).Where(mworm.And(models.UserF.CreatedAt, models.UserF.Name))

注意：只为实现了 TableName() 方法的结构体生成字段常量。

API 速查表

功能	API	示例
插入	INSERT(entity).Exec()	INSERT(user).Exec()
批量插入	BulkInsert(slice).Exec()	BulkInsert(rows).Upsert("id").Exec()
COPY 批量导入	CopyFrom(slice).Exec()	CopyFrom(ticks).ExcludeFields("id").Exec()
查询单条	SELECT(entity).Where(...).One(&dest)	SELECT(User{}).Where(Eq("id",1)).One(&u)
查询多条	SELECT(entity).Where(...).Many(&dest)	SELECT(User{}).Where(Gt("age",18)).Many(&users)
更新	UPDATE(entity).Where(...).Exec()	UPDATE(user).WherePK().Exec()
删除	DELETE(entity).Where(...).Exec()	DELETE(user).WherePK().Exec()
主键条件	WherePK()	自动构建单/复合主键 WHERE 条件，且在 UPDATE 时自动排除主键字段
等于	Eq(tag, value)	Eq("status", 1) (必须使用 json tag)
不等于	NEq(tag, value)	NEq("status", 0) (必须使用 json tag)
大于/大于等于	Gt(tag, value) / Gte(tag, value)	Gt("age", 18) (必须使用 json tag)
小于/小于等于	Lt(tag, value) / Lte(tag, value)	Lt("age", 60) (必须使用 json tag)
IN	IN(tag, values...)	IN("id", 1, 2, 3) (必须使用 json tag)
NOT IN	NotIN(tag, values...)	NotIN("status", 4, 5) (必须使用 json tag)
BETWEEN	Between(tag, min, max)	Between("age", 18, 60) (必须使用 json tag)
LIKE	Like(tag...)	Like("name") (必须使用 json tag)
ILIKE	ILike(tag...)	ILike("name") (必须使用 json tag)
IS NULL	Null(tag...)	Null("email") (必须使用 json tag)
IS NOT NULL	NEqNull(tag...)	NEqNull("email") (必须使用 json tag)
OR 分组	OrGroup(cgs...)	OrGroup(Eq("a",1), Eq("b",2))
AND 分组	AndGroup(cgs...)	AndGroup(Gte("a",1), Lte("b",10))
EXISTS	Exists(sql, args...)	Exists("SELECT 1 FROM ...")
NOT EXISTS	NotExists(sql, args...)	NotExists("SELECT 1 FROM ...")
子查询	SubQuery(tag, symbol, sql, args...)	SubQuery("id", "IN", "SELECT ...") (必须使用 json tag)
JSONB 包含	JsonbContains(tag, value)	JsonbContains("data", "{\"a\":1}") (必须使用 json tag)
数组匹配	ArrayAny(tag, value)	ArrayAny("tags", "go") (必须使用 json tag)
聚合-计数	Count(column)	Count("*")
聚合-求和	Sum(column)	Sum("score") (必须使用 json tag)
聚合-平均	Avg(column)	Avg("age") (必须使用 json tag)
聚合-最小	Min(column)	Min("score") (必须使用 json tag)
聚合-最大	Max(column)	Max("score") (必须使用 json tag)
Upsert (全自动)	Upsert(conflictTags...)	INSERT(u).Upsert("id") (必须使用 json tag)
Upsert (手动)	OnConflict(tags...).DoUpdate(tags...)	INSERT(u).OnConflict("id").DoUpdate("name") (必须使用 json tag)
更新表达式	SetExpression(tag, expr)	SetExpression("age", "age + 1") (必须使用 json tag)
更新空值	AllowEmpty(tags...)	AllowEmpty("name") (必须使用 json tag)
动态表名	Table(tableName)	Table("users_2026")
条件分支	If(func(o *OrmModel))	.If(func(o *mworm.OrmModel){ o.Limit(10) })
JSONB 映射(Map)	JsonbMap(&dest, keys...)	SELECT(User{}).JsonbMap(&m, "id", "name")
JSONB 映射(List)	JsonbList(&dest)	SELECT(User{}).JsonbList(&list)
分页	PAGE(entity, page, size, excludes, cgs...)	PAGE(User{}, 1, 10, nil)
链式分页	Paginate(selectBuilder, page, size, &dest)	Paginate(SELECT(User{}).Where(...).Desc("id"), 1, 10, &list)
排序	Asc(tag...) / Desc(tag...)	Asc("id").Desc("createdAt") (必须使用 json tag)
上下文	WithContext(ctx)	SELECT(User{}).WithContext(ctx).One(&u)
事务绑定	Tx(tx)	INSERT(order).Tx(tx).Exec()
托管事务	Transaction(ctx, fn)	mworm.Transaction(ctx, func(tx *sqlx.Tx) error { ... })
独立客户端	New(db)	client := mworm.New(slaveDB); client.SELECT(...)
忽略 0 行	IgnoreZeroRows()	UPDATE(user).WherePK().IgnoreZeroRows().Exec()
原生 SQL	Raw(express, args...)	Raw("age > $1", 18)
原生查询	RawSQL(sql, args...)	RawSQL("SELECT ... WHERE id = $1", id).One(&u)
行级锁	ForUpdate(mode...)	SELECT(Order{}).Tx(tx).WherePK().ForUpdate().One(&o)
事务选项	TransactionWithOptions(ctx, opts, fn)	&sql.TxOptions{Isolation: sql.LevelSerializable}
全表放行	AllowFullTable()	DELETE(TmpLog{}).AllowFullTable().Exec()

---

进阶高级特性

1. 上下文与超时熔断 (WithContext)

支持传入 context.Context，在请求超时或客户端取消连接时，立即中断数据库执行，防止慢查询占满连接池：

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

var user User
err := mworm.SELECT(User{}).
    WithContext(ctx).
    Where(mworm.Eq("id", 123)).
    One(&user)

2. 链式事务与托管闭包 (Transactions)

支持两种事务使用方式：

方式 A：托管式事务闭包（推荐）

自动管理 Begin、Commit 并在发生 error 或 panic 时自动 Rollback：

err := mworm.Transaction(ctx, func(tx *sqlx.Tx) error {
    // 事务内直接链式调用 .Tx(tx)
    if err := mworm.INSERT(order).Tx(tx).Exec(); err != nil {
        return err
    }
    return mworm.UPDATE(account).Tx(tx).Where(mworm.Eq("id", 1)).Exec()
})

指定隔离级别 / 只读事务 + 行级锁

err := mworm.TransactionWithOptions(ctx, &sql.TxOptions{Isolation: sql.LevelRepeatableRead}, func(tx *sqlx.Tx) error {
    var o Order
    // SELECT ... FOR UPDATE；任务抢占场景可用 ForUpdate("SKIP LOCKED")，不等待用 ForUpdate("NOWAIT")
    if err := mworm.SELECT(Order{ID: id}).Tx(tx).WherePK().ForUpdate().One(&o); err != nil {
        return err
    }
    return mworm.UPDATE(Order{ID: id, Status: 2}).Tx(tx).WherePK().Exec()
})

嵌套事务与 SAVEPOINT 保存点（全链路 Context 透明自动传播）

当外部业务层已处于事务中，而调用的公共 Service 内部再次声明了事务时，底层通过 Context 自动检测并转换为 PostgreSQL 原生保存点（SAVEPOINT）：

• 内层逻辑报错或 panic 时，自动局部回滚当前保存点（ROLLBACK TO SAVEPOINT），绝不破坏外层主事务；
• 推荐使用 TransactionCtx，闭包直接接收携带当前事务的 ctx，调用下游方法时传该 ctx 即可全链路透明继承，下游 .WithContext(ctx) 自动提取执行，彻底告别手动 WithTx！

// 优雅范式：使用 TransactionCtx 实现零摩擦上下文传播
err := mworm.TransactionCtx(ctx, func(ctx context.Context, tx *sqlx.Tx) error {
    // 1. 本层写操作直接使用 tx 或携带 ctx
    if err := mworm.INSERT(order).Tx(tx).Exec(); err != nil {
        return err
    }

    // 2. 调用下游子模块（子模块签名通常只接收 ctx）
    // 此时 ctx 内部已注入当前事务，下游内部无论执行 SELECT(...).WithContext(ctx)
    // 还是再次调用 TransactionCtx(ctx, ...)，均能自动继承事务或嵌套为原生 SAVEPOINT 保存点！
    if err := subService.ProcessPayment(ctx); err != nil {
        log.Warn().Err(err).Msg("内层支付操作已局部回滚到保存点，执行业务降级")
    }
    return nil // 外层正常全量提交
})

方式 B：手动绑定外部事务

tx, _ := mworm.SqlxDB.Beginx()
defer tx.Rollback()

err := mworm.BulkInsert(items).Tx(tx).Exec()
if err != nil {
    return err
}
tx.Commit()

3. 多数据库实例与读写分离 (Client)

除全局单例 mworm.SqlxDB 外，支持独立客户端模式：

// 创建独立客户端实例
slaveClient := mworm.New(slaveDB)

// 针对从库查询
var users []User
err := slaveClient.SELECT(User{}).Where(mworm.Eq("status", 1)).Many(&users)

[!NOTE] 执行器优先级与读写一致性契约 当在 TransactionCtx 事务闭包内部时，上下文中注入的活跃事务拥有最高执行优先级（o.tx -> ctx 事务 -> WithDB -> 全局 DB），确保事务内数据读写强一致（Read-Your-Own-Writes）；若确需在事务期间绕过当前事务强制走只读从库，请传入不含事务标记的独立上下文（如 context.Background()）。

4. 优雅链式分页 (Paginate)

原生链式分页能够天然继承 Where、Desc、Asc、WithContext、Tx 等所有设置：

var userList []User
res, err := mworm.Paginate(
    mworm.SELECT(User{}).
        Where(mworm.Eq("status", 1)).
        Desc("createdAt").
        WithContext(ctx),
    1, 20, &userList,
)
if err != nil {
    return err
}

fmt.Printf("总数: %d, 总页数: %d, 是否有下一页: %v\n", res.Total, res.TotalPage, res.HasNext())

5. 影响行数控制与哨兵错误

对于 UPDATE/DELETE 操作，如果影响行数为 0，mworm 默认返回 mworm.ErrNoRowsAffected。可通过 IgnoreZeroRows() 豁免：

// 捕获特定错误
if errors.Is(err, mworm.ErrNoRowsAffected) {
    // 没有任何行被修改
}

// 或主动忽略 0 行影响
err := mworm.UPDATE(u).WherePK().IgnoreZeroRows().Exec()

6. 慢查询自动监控、告警与回调钩子

配置全局慢查询阈值，当查询耗时超过阈值时将自动打印 Warn 告警日志，并触发自定义回调捕获调用方位置：

// 设置慢查询告警阈值为 200 毫秒 (设为 0 则不启用)
mworm.SlowQueryThreshold = 200 * time.Millisecond

// 注册慢查询告警回调（sqlStr 为参数化 SQL，不含参数值，避免手机号/Token 等敏感数据写入日志）
mworm.OnSlowQuery = func(action string, cost time.Duration, sqlStr string, caller string) {
    log.Printf("[SLOW SQL] 耗时: %v | 调用来源: %s | 动作: %s | SQL: %s", cost, caller, action, sqlStr)
}

7. 数据库连接池状态监控 (Stats)

stats := mworm.Stats()
if stats != nil {
    fmt.Printf("连接池指标: 打开连接=%d, 正在使用=%d, 空闲=%d, 等待数=%d\n",
        stats.OpenConnections, stats.InUse, stats.Idle, stats.WaitCount)
}

8. 复合主键防全表误更/误删安全保护 (WherePK)

当调用 WherePK() 时，mworm 强制执行防呆安全拦截：任一主键字段为空值即返回错误，绝不生成无条件 SQL。 此外，任何最终没有 WHERE 条件的 UPDATE/DELETE（例如 AndAuto 条件全部为空被移除）都会在执行前返回 ErrFullTableOperation，确需全表操作时使用 AllowFullTable() 显式放行。

9. PostgreSQL 原生特性高能运算套件

彻底剔除多数据库兼容的历史妥协，专注于发挥 PostgreSQL 的最强威力：

A. JSONB 原生运算套件

• JsonContains(tag, value)：PostgreSQL 原生包含运算 (column @> ?)，支持结构体、Map、切片或 JSON 字符串自动序列化；
• JsonContainedBy(tag, value)：被包含运算 (column <@ ?)；
• JsonbHasKey(tag, key)：顶层键存在性检测 (jsonb_exists(column, ?)，避开 ? 操作符与参数占位符冲突，完美适配 GIN 索引)；
• JsonbHasAnyKeys(tag, keys)：检测是否包含任意一个键 (jsonb_exists_any(column, ?))；
• JsonbHasAllKeys(tag, keys)：检测是否同时包含所有键 (jsonb_exists_all(column, ?))；
• JsonPath(tag, path, op, val)：路径提取查询 (column#>>'{path}' op ?)。

// 查询 payload 中包含指定权限配置的记录
err := mworm.SELECT(MarketHistory{}).
    Where(mworm.JsonContains("payload", map[string]any{"level": "gold"})).
    Many(&list)

// 查询 payload 中包含指定顶层键的记录
err := mworm.SELECT(MarketHistory{}).
    Where(mworm.JsonbHasKey("payload", "user_id")).
    Many(&list)

B. PostgreSQL 原生数组 (Array) 运算套件

• ArrayContains(tag, val)：数组包含运算 (column @> ?)；
• ArrayOverlaps(tag, val)：数组重叠相交运算 (column && ?)，极度适合股票概念池、标签集合筛选；
• ArrayAny(tag, val)：标量值存在于数组字段中 (? = ANY(column))；
• AnyEquals(tag, slice)：某列等于参数切片中的任一元素 (column = ANY(?))，PostgreSQL 官方推荐的极致单参数替代 IN (?) 方案。

// 标签重叠筛选
err := mworm.SELECT(Stock{}).
    Where(mworm.ArrayOverlaps("tags", []string{"芯片", "半导体"})).
    Many(&stocks)

// 高效单参数替代 IN 查询
err := mworm.SELECT(User{}).
    Where(mworm.AnyEquals("id", []int64{101, 102, 103})).
    Many(&users)

C. 原生大小写不敏感匹配 (ILIKE)

• ILike(tag, "%keyword%")：原生生成 column ILIKE ?，告别 LOWER() 造成的无法利用 B-Tree 索引问题；
• 亦兼容结构体取值：mworm.SELECT(User{Name: "alice"}).Where(mworm.ILike("name"))。

err := mworm.SELECT(Stock{}).
    Where(mworm.ILike("name", "%茅台%")).
    Many(&stocks)

10. 编译期强类型 Fluent Builder (Typestate 设计)

为了从根本上消除动词错配与调用混淆，mworm 引入了基于 Typestate（状态机类型模式） 的强类型 Fluent Builder 架构。全局 SELECT/INSERT/BulkInsert/UPDATE/DELETE（以及 client.* 和 mworm.Table(...).*）统一返回正交物理隔离的专属构建器：

构建器类型	专职动词	专属方法子集 (IDE 补全仅可见此类)	严禁方法 (调用即编译报错)
*SelectBuilder	查询 (SELECT)	Where, WhereIf, WherePK, Fields, ExcludeFields, Asc, Desc, Limit, Offset, Join, GroupBy, Having, ForUpdate, WithContext, Tx, One, Many, Pluck, Count, Sum, Avg, Min, Max, Scan, JsonbMap, JsonbList	❌ SetField, SetExpression, Exec, OnConflict, Upsert, DoNothing, AllowFullTable
*InsertBuilder	写入 (INSERT, BulkInsert)	Fields, ExcludeFields, AllowEmpty, OnConflict, DoUpdate, DoNothing, Upsert, Chunk, Returning, WithContext, Tx, Exec, Scan, One, Many, IgnoreZeroRows	❌ Where, WhereIf, WherePK, Limit, Offset, Asc, Desc, Join, GroupBy, ForUpdate, SetField
*UpdateBuilder	更新 (UPDATE)	SetField, SetExpression, Where, WhereIf, WherePK, AllowEmpty, AllowFullTable, Fields, ExcludeFields, Returning, WithContext, Tx, Exec, Scan, One, Many, IgnoreZeroRows	❌ Limit, Offset, Asc, Desc, Join, GroupBy, Having, ForUpdate, OnConflict, Upsert, Chunk
*DeleteBuilder	删除 (DELETE)	Where, WhereIf, WherePK, AllowFullTable, Returning, WithContext, Tx, Exec, Scan, One, Many, IgnoreZeroRows	❌ SetField, SetExpression, Fields, ExcludeFields, Limit, Offset, Asc, Desc, Join, GroupBy, OnConflict

A. 编译期零容忍阻断

// ❌ 错误示范：在 INSERT 上写 WHERE 条件（以往会在运行时静默丢弃）
// 现在：Go 编译器直接报错：type *InsertBuilder has no field or method Where
mworm.INSERT(user).Where(mworm.Eq("id", 1)).Exec()

// ❌ 错误示范：在 SELECT 上调用 SetField 或 Exec
// 现在：Go 编译器直接报错：type *SelectBuilder has no field or method SetField / Exec
mworm.SELECT(user).SetField("status", 1).Exec()

B. 零额外内存分配 (Zero-Cost Abstraction)

所有强类型 Builder 均采用单一指针字段包装底层 *OrmModel：

type SelectBuilder struct { model *OrmModel }

内部链式转发全部为短方法，在 Go 编译器激进内联（Aggressive Inlining）下，编译产物直接内联展开为底层调用，零额外堆内存分配，零性能损耗。

C. .Model() 逃生舱与生态兼容

需要直接访问或传递底层 *OrmModel（如存量批处理、动态中间件组装）时，所有 Builder 均提供了 .Model() 方法无感转换：

// 转换为 *OrmModel
orm := mworm.SELECT(User{}).Where(mworm.Eq("status", 1)).Model()

// 链式分页 Paginate 仅接收 *SelectBuilder，传入 INSERT/UPDATE/DELETE 构建器在编译期即报错
pr, err := mworm.Paginate(mworm.SELECT(User{}).Where(mworm.Gt("age", 18)), 1, 10, &users)

D. 动态链式条件装配语法糖 (WhereIf & IfWhen)

在构建动态筛选接口时，以往常需拆分临时变量写大量 if ... { orm.Where(...) }。mworm 提供了 WhereIf 与 IfWhen 语法糖，让整条调用链一气呵成：

• WhereIf(cond bool, cgs...)：当 cond == true 时动态追加 WHERE 条件，否则忽略；
• IfWhen(cond bool, fn func(b *Builder))：当 cond == true 时执行回调，用于动态微调排序、分页、投影等属性。

// 一行代码流式闭环复杂的动态多条件查询：
err := mworm.SELECT(User{}).
    Where(mworm.Eq("status", 1)).
    WhereIf(req.Keyword != "", mworm.ILike("name", "%"+req.Keyword+"%")).
    WhereIf(req.MinAge > 0, mworm.Gte("age", req.MinAge)).
    IfWhen(req.SortByAge, func(b *mworm.SelectBuilder) {
        b.Desc("age")
    }).
    IfWhen(req.Limit > 0, func(b *mworm.SelectBuilder) {
        b.Limit(req.Limit)
    }).
    Many(&userList)