Help us shape the future of Go! Take the 2026 Go Developer Survey

gormx

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 15 Imported by: 0

README

gormx

SQL/GORM 全家桶——连接池增强/框架无关 CRUD Service/仓储

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/gormx@v0.6.0

这个仓库做什么

gormx 是 SQL/GORM 全家桶：连接池增强、框架无关的 CRUD Service、GORM 仓储实现。 让业务 handler 不直接碰 gorm，也让 Service 可被 HTTP/RPC 双协议复用。

组成

包 import 路径 做什么
gormx（模块根包） github.com/oekit/gormx Open（函数选项连接池）、OpenMySQL、Paginate（单查询分页）、InTransactionContext、FilterBuilder
crud github.com/oekit/gormx/crud 框架无关 CRUD Service：泛型 NewBaseService[T, ID, CreateReq, UpdateReq]（ID=实体主键类型，int64/string 文本主键/UUID 均可）；repo 实现 TxRepository 时 Update 自动「事务 + FOR UPDATE 行锁」消除丢更新，afterUpdate 钩子失败整体回滚
gormrepo github.com/oekit/gormx/gormrepo NewGormRepository[T, ID](db, opts...) 仓储实现（可选查询装饰器：行级 scope 自动注入，含按 ID 路径）

快速使用

import (
    "github.com/oekit/gormx"
    "github.com/oekit/gormx/crud"
    "github.com/oekit/gormx/gormrepo"
)

db, _ := gormx.Open(dialector, gormx.WithConnectionPool(10, 100, time.Hour))
repo := gormrepo.NewGormRepository[Project, int64](db)
svc := crud.NewBaseService[Project, int64, CreateReq, UpdateReq](repo)

第二个类型参数 ID 是实体主键类型（comparable）：int64 自增、string 文本主键（TEXT PRIMARY KEY）、UUID 等均可，v0.6.0 起不再写死 int64。

查询装饰器（多租户 / 行级隔离）

scope 从「每个调用点手拼」上收为仓储层强制——按 ID 的 Get/Update/Delete 同样自动注入（越权最常出在主键路径）：

repo := gormrepo.NewGormRepository[Project, int64](db,
    gormrepo.WithQueryDecorator[Project](func(ctx context.Context) func(*gorm.DB) *gorm.DB {
        uid := identity.UID(ctx)
        return func(db *gorm.DB) *gorm.DB { return db.Where("uid = ?", uid) }
    }),
    gormrepo.WithScopeRequired[Project](), // fail-closed：裸查询显式报错
)
  • decorator 返回 nil = 本次不加 scope（admin 直通）；开启 WithScopeRequired 时 nil scope 报错，admin 请返回空 scope （func(db *gorm.DB) *gorm.DB { return db }）
  • RunInTx 事务仓储 / WithTx 副本继承同一 decorator（「事务 + 行锁读」 不丢 scope）
  • 默认无 decorator 即 passthrough：单租户服务零负担

SQLite 驱动与 cgo

  • 只用 gormx 不会引入 cgo：生产代码仅依赖 gorm.io/driver/mysql（纯 Go）。 gorm.io/driver/sqlite（CGO 实现，mattn/go-sqlite3）只是本仓测试依赖（内存库）， 不进消费方二进制；Go 1.17+ 模块图剪枝下，下游 go.mod / go.sum 不会出现任何 sqlite 条目。代价是本仓自身 go test 需要 CGO。
  • 想要纯 Go SQLite：dialector 换 glebarez/sqlite （modernc 系），CGO_ENABLED=0 全静态构建；复用已有 *sql.DB 用 sqlite.Dialector{Conn: db}。
  • ⚠️ 驱动名冲突，运行时才炸：modernc.org/sqlite 与 glebarez/go-sqlite （glebarez dialector 的底层）都在 init() 里注册名为 "sqlite" 的驱动， 同时引入两者启动即 panic（sql: Register called twice for driver sqlite）。 典型踩法：自己 import _ "modernc.org/sqlite" 又引 glebarez dialector。 注册者必须唯一——用 glebarez 就不要再直接 import modernc。mattn 系 （gorm.io/driver/sqlite）注册的是 "sqlite3"，与两者不冲突。

边界

矩阵总览（24 活跃模块，自动生成）

模块 内容 矩阵内依赖
pkg 微工具集 21 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap/singleflighttest/urlguard；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11） —
concurrency 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口；v0.16.0 起 ratelimit NewKeyedLimiterByFunc[K]——factory func(K) Limiter 按 key 定配额（一个管理器按接口维度分档位，NewKeyedLimiterOf 零破坏随迁；未登记 key 拿 factory 兜底档的坑已在 doc 点名，#31）；v0.17.0 起 KeyedLimiter.Create 护栏内原子登记（表满先回收空闲与 Allow 同路、仍满拒绝计 OverCapHits、已存在不覆盖——热更走 Replace；解决 ByFunc factory 库锁内调用致消费方锁序倒置，#33） pkg
logx 统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 —
core 应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、network IP 工具、version；v0.9.0 起 config FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖——LoadBootstrap 默认接线，免全量指针化）+ require tag（必须 yaml/env 提供，缺失列全并附 env 提示）+ v0.9.1 修 yaml:,inline 字段在 FieldSet 下漏标记（inline 叶子显式零值曾被 default 覆盖）；v0.9.2 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——误报 PATH/HOME、漏无人设置的真拼错，core#8），命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免 —
kitx 标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 pkg v0.10.0 拆出 pkg
metrics Prometheus 门面 + 弹性指标族 core
tracing OpenTelemetry 追踪 + trace_id 真相源 logx
registry 注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge core、logx
data 数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract concurrency、gormx、logx、pkg、redisx、timertask
gormx SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名） logx、pkg
redisx Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）；v0.9.0 起 distlock Lockout 分布式防爆破锁（Redis 侧 fail2ban：滑窗失败计数→阈值锁定 Penalty→Reset 清零，与 concurrency/ratelimit.Lockout 进程内孪生——多实例共享计数是存在理由；惩罚只按首次触发计算、nil client fail-fast 不降级，#6） concurrency、logx、pkg
etcdx etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行） concurrency、core、logx、registry
httpx HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8）；v0.8.0 起 SafeDialFunc/WithSafeDial 出站 SSRF 防护胶水（判定单源 pkg/urlguard v0.15.0：解析 IP 全量预检 + 实际 RemoteAddr 端点核对闭合重解析 TOCTOU、Happy-Eyeballs 覆盖，构造态豁免；v0.7.0 内置的独立 httpx/urlguard 实现收敛删除，#11） concurrency、core、logx、metrics、pkg、registry、tracing
network 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 concurrency、logx、tracing
timertask 分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效） concurrency、logx
middleware Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord{Method,Path,Status,Latency,ClientIP,UserAgent,TraceID} 与日志同源、c 同传可读业务键、error/panic 只记 Warn 不影响主链路、SkipPaths 命中不触发）+ chainmw.WithSink 内核同构（kitex 随 ToKitex 获得）+ StackConfig.DisableResponseWrap 响应自管一键形态（TraceID→Recovery→AccessLog）与 AccessLogOptions 透传 + doc/README「适用边界」段（响应契约统一 vs handler 自管的推荐组合，#18）；v0.12.0 起 AccessLog panic 恢复点产出记录（AccessRecord.Panic 标记 + Err 摘要，Hertz status 按 Recovery 缺省 500）后按原值重抛——panic 请求不再零访问记录，sink/kitex 桥接同步留痕，#20 concurrency、core、logx、metrics、pkg、registry、tracing
k8s Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限） logx
nns NNS 服务治理客户端——provider 无关发现/配置/实例缓存 concurrency、core、logx、registry
nns-endpoint NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池 concurrency、core、httpx、logx、metrics、nns、pkg、registry
bootstrap 应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；Metrics/Tracing 在嵌套模块 bootstrap/obs concurrency、logx
hertz Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整/WithReadyAddr 探活地址），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接 bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow 组合式流程编排——串行/并行/异步/条件分支 + Hook AOP concurrency、logx
kitex-examples Kitex echo 示例——client/server + IDL + 治理配置 bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE

Documentation

Overview

Package gormx 提供 GORM 数据库客户端封装。

统一封装：自定义 Logger、连接池配置。 零可观测性副作用：构造不注入任何 tracing 插件。

快速接入

基本用法： 

db, err := gorm.Open(mysql.Open(dsn))
if err != nil {
    log.Fatal(err)
}

自定义连接池： 

db, err := gorm.OpenWithPool(mysql.Open(dsn),
    10,              // maxIdleConns
    100,             // maxOpenConns
    30*time.Minute,  // connMaxLifetime
)

OTel 追踪（装饰器显式接入）

本包不做任何 tracing 注入。需要 SQL Span 时 用 github.com/oekit/tracing/gormotel 显式挂载（无 SDK 时 noop）： 

db, err := gormx.Open(mysql.Open(dsn))
if err := db.Use(gormotel.NewPlugin(gormotel.WithDBName("mydb"))); err != nil {
    return err
}

自定义 Logger

默认使用内置 Logger，支持：

  • 慢查询阈值：默认 200ms
  • 日志级别：默认 Info

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func InTransactionContext 

func InTransactionContext(ctx context.Context, db *gorm.DB, fn TXFunc) error

InTransactionContext 在带有 context 的数据库事务中执行指定函数。

func IsUniqueViolation 

func IsUniqueViolation(err error) bool

IsUniqueViolation 判断给定 error 是否为唯一键冲突。

func Open 

func Open(dialector gorm.Dialector, opts ...OpenOption) (*gorm.DB, error)

Open 使用指定的 dialector 打开数据库连接，自动注入默认日志。

默认行为：

  • 注入默认 Logger（Info 级别）
  • 零 tracing 注入：需要 SQL Span 经 github.com/oekit/tracing/gormotel 显式挂载

可通过选项配置连接池等： 

db, err := gormx.Open(
    mysql.Open(dsn),
    gormx.WithConnectionPool(10, 100, time.Hour),
)

需要 OTel 追踪时（装饰器显式接入，无 SDK 时 noop）： 

db, err := gormx.Open(mysql.Open(dsn))
if err := db.Use(gormotel.NewPlugin()); err != nil { ... }

func OpenMySQL 

func OpenMySQL(cfg MySQLConfig) (*gorm.DB, error)

OpenMySQL 从配置创建 GORM DB 实例（含连接池配置；零 tracing 注入， 需要 SQL Span 经 github.com/oekit/tracing/gormotel 显式挂载）。

用法： 

db, err := gormx.OpenMySQL(gormx.MySQLConfig{
    Host: cfg.Database.Host, Port: cfg.Database.Port,
    User: cfg.Database.User, Password: cfg.Database.Password,
    DBName: cfg.Database.DBName,
    MaxIdleConns: 10, MaxOpenConns: 100,
})

func PaginateScope 

func PaginateScope(req *pagination.PageRequest) func(db *gorm.DB) *gorm.DB

PaginateScope 返回一个 GORM Scope 函数，自动应用分页的 Offset 和 Limit。

Types

type AuditModel 

type AuditModel struct {
	ID        int64          `gorm:"primaryKey" json:"id"`
	CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at"`
	UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"deleted_at,omitempty"`
	CreatedBy int64          `json:"created_by"`
	UpdatedBy int64          `json:"updated_by"`
}

AuditModel 是带审计字段的基础模型。 除了软删除外，还包含 created_by 和 updated_by 字段。

func (*AuditModel) GetID 

func (m *AuditModel) GetID() int64

GetID 返回主键 ID。

func (*AuditModel) SetID 

func (m *AuditModel) SetID(id int64)

SetID 设置主键 ID。

type AuditPlugin 

type AuditPlugin struct {
	// UserIDFunc 从 context 提取当前用户 ID。
	UserIDFunc func(ctx context.Context) int64
}

AuditPlugin 是 GORM 审计插件，自动填充 created_by/updated_by 字段。 实体必须包含 CreatedBy 和 UpdatedBy 字段。

func NewAuditPlugin 

func NewAuditPlugin(userIDFunc func(ctx context.Context) int64) *AuditPlugin

NewAuditPlugin 创建审计插件。 userIDFunc 从 context 提取当前用户 ID 的函数。

func (*AuditPlugin) Initialize 

func (p *AuditPlugin) Initialize(db *gorm.DB) error

Initialize 初始化插件，注册 GORM 回调。

func (*AuditPlugin) Name 

func (p *AuditPlugin) Name() string

Name 返回插件名称。

type BaseModel 

type BaseModel struct {
	ID        int64     `gorm:"primaryKey" json:"id"`
	CreatedAt time.Time `gorm:"autoCreateTime" json:"created_at"`
	UpdatedAt time.Time `gorm:"autoUpdateTime" json:"updated_at"`
}

BaseModel 是通用基础模型，包含 ID 和时间戳。 嵌入此结构体后，实体自动获得主键和时间戳字段。

func (*BaseModel) GetID 

func (m *BaseModel) GetID() int64

GetID 返回主键 ID。

func (*BaseModel) SetID 

func (m *BaseModel) SetID(id int64)

SetID 设置主键 ID。

type FilterBuilder 

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

FilterBuilder 构建动态 SQL WHERE 条件。 适用于查询参数可选的场景，避免大量 if-else 拼接。

用法: 

fb := gormx.NewFilterBuilder()
fb.Add(opts.Provider != "", "provider = ?", opts.Provider)
fb.Add(opts.Repo != "", "repo ILIKE ?", "%"+opts.Repo+"%")
fb.Add(!opts.From.IsZero(), "created_at >= ?", opts.From)
db = fb.Apply(db)

func NewFilterBuilder 

func NewFilterBuilder() *FilterBuilder

NewFilterBuilder 创建过滤构建器。

func (*FilterBuilder) Add 

func (fb *FilterBuilder) Add(ok bool, sql string, args ...any) *FilterBuilder

Add 条件为 true 时追加 WHERE 子句。

func (*FilterBuilder) Apply 

func (fb *FilterBuilder) Apply(db *gorm.DB) *gorm.DB

Apply 将构建的条件应用到 GORM 查询链。 每个条件之间用 AND 连接。

func (*FilterBuilder) Clauses 

func (fb *FilterBuilder) Clauses() (string, []any)

Clauses 返回合并后的子句字符串和参数（用于 raw SQL 场景）。

func (*FilterBuilder) IsEmpty 

func (fb *FilterBuilder) IsEmpty() bool

IsEmpty 是否没有任何条件。

type Logger 

type Logger struct {
	gormLogger.Config
	// contains filtered or unexported fields
}

Logger 是基于 logx 的 GORM 日志适配器，实现 gormLogger.Interface 接口。 通过 logx 门面输出，支持 slog 结构化日志和 trace_id 传播。

func NewDefaultLogger 

func NewDefaultLogger() *Logger

NewDefaultLogger 创建带有合理默认配置（慢查询阈值 200ms、Info 级别）的 Logger。

func NewLogger 

func NewLogger(config gormLogger.Config) *Logger

NewLogger 根据给定的配置创建 Logger 实例。 内部持有 Delegating logger 懒解析默认后端：构造（gormx.Open）先于业务 logx.SetDefault 时，SQL 日志仍能跟随运行期切换的后端，不会固化到构造 时刻的 Default。

func (*Logger) Error 

func (l *Logger) Error(ctx context.Context, msg string, data ...any)

Error 以 Error 级别记录日志。

func (*Logger) Info 

func (l *Logger) Info(ctx context.Context, msg string, data ...any)

Info 以 Info 级别记录日志。

func (*Logger) LogMode 

func (l *Logger) LogMode(level gormLogger.LogLevel) gormLogger.Interface

LogMode 返回一个设置了新日志级别的 Logger 副本。

func (*Logger) Trace 

func (l *Logger) Trace(ctx context.Context, begin time.Time, fc func() (sql string, rowsAffected int64), err error)

Trace 根据耗时和错误情况，以相应级别记录 SQL 追踪日志。 通过 logx 结构化日志输出，包含调用位置、耗时、行数、SQL 等字段。

func (*Logger) Warn 

func (l *Logger) Warn(ctx context.Context, msg string, data ...any)

Warn 以 Warn 级别记录日志。

type Model 

type Model interface {
	GetID() int64
	SetID(id int64)
}

Model 是 GORM 模型的最小接口，只需暴露主键。 与 BaseModel/SoftDeleteModel/AuditModel 的主键类型（int64）保持一致。

type MySQLConfig 

type MySQLConfig struct {
	Host           string `yaml:"host"`
	Port           int    `yaml:"port"`
	User           string `yaml:"user"`
	Password       string `yaml:"password"`
	DBName         string `yaml:"dbname"`
	MaxIdleConns   int    `yaml:"max_idle_conns"`
	MaxOpenConns   int    `yaml:"max_open_conns"`
	ConnMaxLifeMin int    `yaml:"conn_max_life_min"`
}

MySQLConfig 是 MySQL 连接配置，可直接从 YAML 反序列化。

type OpenOption 

type OpenOption func(*openConfig)

OpenOption 配置 Open 的行为（函数选项模式）。

func WithConnMaxIdleTime 

func WithConnMaxIdleTime(d time.Duration) OpenOption

WithConnMaxIdleTime 配置连接最大空闲时间。 空闲超过此时间的连接会被关闭，防止 stale 连接积累。

func WithConnectionPool 

func WithConnectionPool(maxIdleConns, maxOpenConns int, connMaxLifetime time.Duration) OpenOption

WithConnectionPool 配置连接池参数（避免 OpenWithPool 的位置参数易错问题）。

func WithGormOptions 

func WithGormOptions(opts ...gorm.Option) OpenOption

WithGormOptions 追加底层 gorm.Option。

type PageResponse 

type PageResponse[T any] = pagination.PageResponse[T]

PageResponse 分页查询的响应结果（pkg/pagination 统一信封的别名）。 字段为 Items（JSON "items"），与 crud、hertz/crudh 的契约统一为 pkg/pagination.PageResponse。

func Paginate 

func Paginate[T any](db *gorm.DB, req *pagination.PageRequest, queryFn func(db *gorm.DB) *gorm.DB) (*PageResponse[T], error)

Paginate 执行分页查询，返回指定类型的分页结果。 queryFn 只调用一次（GORM 的 *gorm.DB 是不可变的，每次方法调用返回新实例）。

type SingletonRepo 

type SingletonRepo[T Model] struct {
	// contains filtered or unexported fields
}

SingletonRepo 提供单例记录的 get-or-default + upsert 模式。 适用于全局配置、系统设置等只有一条记录的场景。

主键列名通过 GORM schema 解析（不硬编码 "id"），主键列名非 id 的模型 同样可用；解析失败时 Get/Save/GetOrCreate 返回错误。

用法: 

type MyConfig struct { gormx.BaseModel; Value string }
// MyConfig 通过嵌入 BaseModel 自动获得 GetID/SetID，满足 Model 接口

repo := gormx.NewSingletonRepo(db, func() *MyConfig { return &MyConfig{Value: "default"} })
cfg, err := repo.Get(ctx)
cfg.Value = "updated"
err = repo.Save(ctx, cfg)

func NewSingletonRepo 

func NewSingletonRepo[T Model](db *gorm.DB, defaultVal func() T) *SingletonRepo[T]

NewSingletonRepo 创建单例仓库。 defaultVal 返回当记录不存在时的默认值。

func (*SingletonRepo[T]) Get 

func (r *SingletonRepo[T]) Get(ctx context.Context) (T, error)

Get 获取唯一的记录。不存在时返回 defaultVal() 的结果，不返回 error。

func (*SingletonRepo[T]) GetOrCreate 

func (r *SingletonRepo[T]) GetOrCreate(ctx context.Context) (T, error)

GetOrCreate 获取记录，不存在时创建默认值并返回。 在事务中使用 SELECT ... FOR UPDATE 锁定行。与 Save 相同：FOR UPDATE 锁不住空表并发插入的幻影，Create 撞唯一约束时重读收敛（最多重试一次）； 单例表建议加唯一约束作为最终防线。

func (*SingletonRepo[T]) Save 

func (r *SingletonRepo[T]) Save(ctx context.Context, model T) error

Save 保存单例记录。已存在则更新（通过 ID），不存在则创建。 在事务中使用 SELECT ... FOR UPDATE 锁定行。注意：FOR UPDATE 锁不住 "空表并发插入"的幻影（READ COMMITTED 下两个事务都读到 not found 后 各自 Create）——Create 撞唯一约束/主键冲突时重读并改走更新路径收敛； 单例表建议加唯一约束作为最终防线。

type SoftDeleteModel 

type SoftDeleteModel struct {
	ID        int64          `gorm:"primaryKey" json:"id"`
	CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at"`
	UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"deleted_at,omitempty"`
}

SoftDeleteModel 是带软删除的基础模型。 Delete 操作会设置 deleted_at 而非物理删除。

func (*SoftDeleteModel) GetID 

func (m *SoftDeleteModel) GetID() int64

GetID 返回主键 ID。

func (*SoftDeleteModel) SetID 

func (m *SoftDeleteModel) SetID(id int64)

SetID 设置主键 ID。

type TXFunc 

type TXFunc func(tx *gorm.DB) error

TXFunc 是在事务中执行的函数类型，接收事务内的 *gorm.DB 并返回 error。

Source Files

View all Source files

Directories

Path Synopsis
Package crud 提供通用 CRUD 的泛型数据层基础设施。
 Package crud 提供通用 CRUD 的泛型数据层基础设施。
Package gormrepo 提供 github.com/oekit/gormx/crud 仓储接口的 GORM 实现。
 Package gormrepo 提供 github.com/oekit/gormx/crud 仓储接口的 GORM 实现。

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.