gormdriver

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

README

gofast-gorm

GoFast 框架的 GORM 数据库驱动插件。

框架核心 go-fast-framework 不再内置 ORM 驱动，需显式安装并注册本插件。

安装

go get github.com/zhoudm1743/gofast-gorm@latest

接入

import (
    "github.com/zhoudm1743/go-fast-framework/database"
    "github.com/zhoudm1743/go-fast-framework/foundation"
    gormdriver "github.com/zhoudm1743/gofast-gorm"
)

app.SetProviders([]foundation.ServiceProvider{
    // ...
    &database.ServiceProvider{},
    &gormdriver.ServiceProvider{},
})

database:
  connections:
    main:
      driver: gormdriver
      engine: mysql   # mysql | postgres | sqlite | mssql
      # ...

语义差异固化说明

与 gofast-xorm 驱动的双驱动一致性语义（差异 = 有意保留的 gorm 原生行为，断言锁定于测试）：

差异点 gorm 侧行为 锁定测试
Save 值无变化 affected MySQL=0 / PG=1（均不报错不误插） fullcov_write Save_值无变化
Save 0 行回落 upsert 忽略链上 Where 回落插入不受显式条件限定（xorm 0 行不落库） fullcov_write SaveResult
CreateInBatches 中途失败 分批包裹单事务整体回滚（xorm 前块已提交） fullcov_write CreateInBatches_中途失败
FirstOrCreate 已填充 dest 主键内联收窄未命中回落 Create（xorm 按 conds 命中回填） fullcov_chain 链式不可变与dest条件
Having 带参占位符 支持（xorm 链上拒绝 ErrUnsupported） fullcov_chain Having过滤
Joins 非法串 数据库原始错误（xorm 报 ErrUnsupported） fullcov_ext Joins
Preload contracts 回调 仅共享引擎路径（gorm:"-"）支持，原生路径报错 fullcov_ext PL-02
软删业务级 deleted_at 列 gorm 不识别（Delete 为物理删，需业务 Update 软删；OnlyTrashed/Restore 已兼容 int64 与 gorm.DeletedAt 双形态）；打 sd 标记升级为框架托管软删（Delete 自动改写置位 UPDATE、默认查询自动过滤，sec/milli/nano/flag/time 五模式，文档 §4.5/§11.9） fullcov_ext SoftDelete_*
事务终态误用 sql.ErrTxDone → ErrInvalidTransaction（errors.go 映射） fullcov_rawtx Begin_重复Commit与终态后误用
超时/连接失败哨兵 statement_timeout(57014)/max_execution_time(3024) → ErrQueryTimeout；连接失败 → ErrConnFailed fault_integration_test

双驱动联合测试方案与执行报告：../docs/md/dual-driver-test-plan.md。

依赖

  • github.com/zhoudm1743/go-fast-framework >= v0.8.2
  • gorm.io/gorm 及对应方言驱动

License

Apache-2.0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PatchSchema added in v1.0.1 

func PatchSchema(db *gorm.DB, models ...any) error

PatchSchema 将 models 的 orm/ext 统一标签 patch 进 db 连接的 gorm schema 缓存（7.1）， 供自带迁移/DDL 工具链的业务在自定义 gorm 连接上复用统一标签事实源（典型用法： 自建连接先 PatchSchema(db, models...) 再 db.AutoMigrate(models...)，DDL 即由 orm 标签驱动）。

db 语义与 ensurePatched 一致：gorm schema 缓存以类型为键、首次解析钉住 NamingStrategy 表名前缀，Parse 与后续 AutoMigrate 必须使用同一条连接。 幂等性以「每函数调用」为界（索引双写片段不可重复注入）：同一连接请合并 models 一次性传入；每连接一次 PatchSchema 的迁移场景天然满足。

Types

type GormDriver 

type GormDriver struct {
	// contains filtered or unexported fields
}

GormDriver 实现 contracts.Driver

func NewGormDriver 

func NewGormDriver(cfg contracts.ConnectionConfig, log contracts.Log) (*GormDriver, error)

NewGormDriver 根据连接配置创建 GORM 驱动实例。

func (*GormDriver) AutoMigrate 

func (d *GormDriver) AutoMigrate(models ...any) error

func (*GormDriver) Close 

func (d *GormDriver) Close() error

func (*GormDriver) DriverName 

func (d *GormDriver) DriverName() string

func (*GormDriver) EnableCaches 

func (d *GormDriver) EnableCaches(cache contracts.Cache) error

EnableCaches 为连接启用查询缓存插件（go-gorm/caches）。 底层使用框架 Cache 服务存储，只有显式调用 Query().Cache() 的查询才会读写缓存。 写操作（Create/Update/Delete/Save）会自动失效全部查询缓存。 重复调用安全（仅首次注册插件）。

func (*GormDriver) Ping 

func (d *GormDriver) Ping() error

func (*GormDriver) Query 

func (d *GormDriver) Query(ctx ...context.Context) contracts.Query

func (*GormDriver) RawDB 

func (d *GormDriver) RawDB() *gorm.DB

RawDB 逃生口：允许高级用户直接获取 *gorm.DB（不推荐常规使用）。

type GormQuery 

type GormQuery struct {
	// contains filtered or unexported fields
}

GormQuery 将 contracts.Query 的每个方法代理到 *gorm.DB。 所有链式方法返回新的 GormQuery 实例，保持不可变。

func (*GormQuery) Begin 

func (q *GormQuery) Begin(opts ...contracts.TxOption) contracts.Query

func (*GormQuery) Cache 

func (q *GormQuery) Cache(opts ...contracts.CacheOption) contracts.Query

Cache 对当前查询链开启结果缓存。 通过 context 注入缓存配置，gormCacher（caches.Cacher 实现）据此决定是否读写缓存。 未启用缓存插件的连接上调用本方法无副作用。 注意：Row()/Rows() 等游标类终结方法会内部剥离缓存标记（见 withoutCache）， 避免命中缓存时返回空游标导致 panic。

func (*GormQuery) Commit 

func (q *GormQuery) Commit() error

func (*GormQuery) Count 

func (q *GormQuery) Count(count *int64) error

func (*GormQuery) Create 

func (q *GormQuery) Create(value any) error

func (*GormQuery) CreateInBatches 

func (q *GormQuery) CreateInBatches(value any, batchSize int) error

func (*GormQuery) CreateResult 

func (q *GormQuery) CreateResult(value any) contracts.Result

func (*GormQuery) Debug 

func (q *GormQuery) Debug() contracts.Query

func (*GormQuery) Delete 

func (q *GormQuery) Delete(value any, conds ...any) error

func (*GormQuery) DeleteResult 

func (q *GormQuery) DeleteResult(value any, conds ...any) contracts.Result

func (*GormQuery) Distinct 

func (q *GormQuery) Distinct(args ...any) contracts.Query

func (*GormQuery) Exec 

func (q *GormQuery) Exec(sql string, values ...any) error

func (*GormQuery) ExecResult 

func (q *GormQuery) ExecResult(sql string, values ...any) contracts.Result

ExecResult 执行原生 SQL 写操作并返回受影响行数（X-08）。 与 Exec 的差异：Exec 只返回错误，ExecResult 额外携带 RowsAffected， 适用于需要依据行数做业务判定的原生 SQL 场景（如配额原子扣减、存在性更新）。

func (*GormQuery) Exists 

func (q *GormQuery) Exists(dest any, conds ...any) (bool, error)

func (*GormQuery) Find 

func (q *GormQuery) Find(dest any, conds ...any) error

func (*GormQuery) FindInBatches 

func (q *GormQuery) FindInBatches(dest any, batchSize int, fc func(tx contracts.Query, batch int) error) error

func (*GormQuery) First 

func (q *GormQuery) First(dest any, conds ...any) error

func (*GormQuery) FirstOrCreate 

func (q *GormQuery) FirstOrCreate(dest any, conds ...any) error

func (*GormQuery) FirstOrInit 

func (q *GormQuery) FirstOrInit(dest any, conds ...any) error

func (*GormQuery) ForceDelete 

func (q *GormQuery) ForceDelete(value any, conds ...any) error

func (*GormQuery) GetSchema 

func (q *GormQuery) GetSchema() string

GetSchema 返回当前查询上下文的 schema 名称（PostgreSQL 多 schema 场景）。 无 schema 上下文时返回空字符串。 业务代码需要在原生 SQL 中拼接 schema 限定的表名时使用此方法。

func (*GormQuery) Group 

func (q *GormQuery) Group(name string) contracts.Query

func (*GormQuery) Having 

func (q *GormQuery) Having(query any, args ...any) contracts.Query

func (*GormQuery) Joins 

func (q *GormQuery) Joins(query string, args ...any) contracts.Query

func (*GormQuery) Last 

func (q *GormQuery) Last(dest any, conds ...any) error

func (*GormQuery) Limit 

func (q *GormQuery) Limit(limit int) contracts.Query

func (*GormQuery) Lock 

func (q *GormQuery) Lock(mode contracts.LockMode) contracts.Query

func (*GormQuery) Model 

func (q *GormQuery) Model(value any) contracts.Query

func (*GormQuery) Not 

func (q *GormQuery) Not(query any, args ...any) contracts.Query

func (*GormQuery) Offset 

func (q *GormQuery) Offset(offset int) contracts.Query

func (*GormQuery) Omit 

func (q *GormQuery) Omit(columns ...string) contracts.Query

func (*GormQuery) OnlyTrashed 

func (q *GormQuery) OnlyTrashed() contracts.Query

OnlyTrashed 仅查询已软删除的记录。 sd 标记模型（框架托管软删）：按 SdMeta.TrashedCond 类型感知——time 模式 IS NOT NULL、flag 模式 = 1、其余整数模式 <> 0。 未标记模型（旧版业务级两形态并存：int64 deleted_at 0=未删 / gorm.DeletedAt NULL=未删）：调用顺序允许 OnlyTrashed 先于 Model（此时无法做类型探测）， 故用跨类型 CAST 比较，两种形态同一条件成立：

  • int64 列：'0' 仅未删值，非 0 即已删；
  • 时间列：NULL 经 CAST 仍为 NULL（被 WHERE 恒假排除），非 NULL 恒 <> '0'。

方言差异：PG 用 TEXT（CAST AS CHAR 会截断为 char(1)），MySQL/SQLite 用 CHAR。 代价：deleted_at 上索引不可用（软删恢复类低频查询可接受）。 注意：列名 "deleted_at" 与 database.SoftDelete.DeletedAt 字段绑定， 若自定义软删除列名需自行实现此逻辑。

func (*GormQuery) OrWhere 

func (q *GormQuery) OrWhere(query any, args ...any) contracts.Query

func (*GormQuery) Order 

func (q *GormQuery) Order(value any) contracts.Query

func (*GormQuery) Paginate 

func (q *GormQuery) Paginate(page, size int) contracts.Query

func (*GormQuery) Pluck 

func (q *GormQuery) Pluck(column string, dest any) error

func (*GormQuery) Preload 

func (q *GormQuery) Preload(query string, args ...any) contracts.Query

Preload 关联预加载（9.3 分流）：

  1. 字段有 gorm 关联 tag（foreignKey/many2many/polymorphic 等）→ gorm 原生 Preload；
  2. 字段有 gorm:"-" → 共享 Preload 引擎（rel tag 元数据，含 many2many/polymorphic）， 回填在终结方法行装载完成后执行；
  3. 字段无任何 tag → gorm 原生 Preload（约定外键）。

func (*GormQuery) Raw 

func (q *GormQuery) Raw(sql string, values ...any) contracts.Query

func (*GormQuery) Restore 

func (q *GormQuery) Restore() error

func (*GormQuery) Rollback 

func (q *GormQuery) Rollback() error

func (*GormQuery) RollbackTo 

func (q *GormQuery) RollbackTo(name string) error

func (*GormQuery) Row 

func (q *GormQuery) Row() contracts.Row

func (*GormQuery) Rows 

func (q *GormQuery) Rows() (contracts.Rows, error)

func (*GormQuery) Save 

func (q *GormQuery) Save(value any) error

func (*GormQuery) SavePoint 

func (q *GormQuery) SavePoint(name string) error

func (*GormQuery) SaveResult 

func (q *GormQuery) SaveResult(value any) contracts.Result

func (*GormQuery) Scan 

func (q *GormQuery) Scan(dest any) error

func (*GormQuery) ScanMap 

func (q *GormQuery) ScanMap(dest *[]map[string]any) error

func (*GormQuery) Schema 

func (q *GormQuery) Schema(name string) contracts.Query

Schema 在当前查询链上设置动态 schema（主要用于 PostgreSQL）。 后续的 Model()/Table() 调用将自动在表名前加上 "schema." 前缀。 示例：facades.DB().Connection("pg").Schema("analytics").Model(&Event{}).Find(&events)

func (*GormQuery) Scopes 

func (q *GormQuery) Scopes(funcs ...func(contracts.Query) contracts.Query) contracts.Query

func (*GormQuery) Select 

func (q *GormQuery) Select(query any, args ...any) contracts.Query

func (*GormQuery) Table 

func (q *GormQuery) Table(name string) contracts.Query

func (*GormQuery) Take 

func (q *GormQuery) Take(dest any, conds ...any) error

func (*GormQuery) Transaction 

func (q *GormQuery) Transaction(fc func(tx contracts.Query) error, opts ...contracts.TxOption) error

func (*GormQuery) Unscoped 

func (q *GormQuery) Unscoped() contracts.Query

func (*GormQuery) Update 

func (q *GormQuery) Update(column string, value any) error

func (*GormQuery) UpdateResult 

func (q *GormQuery) UpdateResult(column string, value any) contracts.Result

func (*GormQuery) Updates 

func (q *GormQuery) Updates(values any) error

func (*GormQuery) UpdatesResult 

func (q *GormQuery) UpdatesResult(values any) contracts.Result

func (*GormQuery) Where 

func (q *GormQuery) Where(query any, args ...any) contracts.Query

func (*GormQuery) WithContext 

func (q *GormQuery) WithContext(ctx context.Context) contracts.Query

type ServiceProvider 

type ServiceProvider struct{}

ServiceProvider gorm 驱动接入点（可选驱动，需显式加入应用 providers）。 将本 Provider 加入应用 providers 后，配置 driver: "gormdriver" 即可使用： 

app.SetProviders(append(providers, &gormdriver.ServiceProvider{}))

func (*ServiceProvider) Boot 

func (sp *ServiceProvider) Boot(app foundation.Application) error

func (*ServiceProvider) Register 

func (sp *ServiceProvider) Register(app foundation.Application)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.