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.5.2
这个仓库做什么
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, CreateReq, UpdateReq]；repo 实现 TxRepository 时 Update 自动「事务 + FOR UPDATE 行锁」消除丢更新，afterUpdate 钩子失败整体回滚 |
gormrepo |
github.com/oekit/gormx/gormrepo |
NewGormRepository[T](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](db)
svc := crud.NewBaseService[Project, CreateReq, UpdateReq](repo)
查询装饰器（多租户 / 行级隔离）
scope 从「每个调用点手拼」上收为仓储层强制——按 ID 的 Get/Update/Delete 同样自动注入（越权最常出在主键路径）：
repo := gormrepo.NewGormRepository[Project](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：单租户服务零负担
边界
- HTTP handler 在 hertz/crudh（crudh 直接消费 crud.Service）
- Redis 侧在 redisx；分页类型在 pkg/pagination
矩阵总览（24 活跃模块，自动生成）
| 模块 | 内容 | 矩阵内依赖 |
|---|---|---|
| pkg | 微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用） | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮 | pkg |
| logx | 统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 | — |
| core | 应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version） | — |
| kitx | 标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 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、分布式限流 ratelimit（Lua 三态 + 故障本地兜底） | 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 透传/一致性哈希（权重感知虚拟副本） | concurrency、core、logx、metrics、registry、tracing |
| network | 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 | concurrency、logx、tracing |
| timertask | 分片定时任务（FNV-1a、心跳续约） | concurrency、logx |
| middleware | Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载 | 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、registry |
| bootstrap | 应用生命周期引导——bootstrap.Run 骨架 + healthz | concurrency、logx |
| hertz | Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh/versionh（原 handler 微库收编） | bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing |
| kitex | Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编） | 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 ¶
- func InTransactionContext(ctx context.Context, db *gorm.DB, fn TXFunc) error
- func IsUniqueViolation(err error) bool
- func Open(dialector gorm.Dialector, opts ...OpenOption) (*gorm.DB, error)
- func OpenMySQL(cfg MySQLConfig) (*gorm.DB, error)
- func PaginateScope(req *pagination.PageRequest) func(db *gorm.DB) *gorm.DB
- type AuditModel
- type AuditPlugin
- type BaseModel
- type FilterBuilder
- type Logger
- func (l *Logger) Error(ctx context.Context, msg string, data ...any)
- func (l *Logger) Info(ctx context.Context, msg string, data ...any)
- func (l *Logger) LogMode(level gormLogger.LogLevel) gormLogger.Interface
- func (l *Logger) Trace(ctx context.Context, begin time.Time, ...)
- func (l *Logger) Warn(ctx context.Context, msg string, data ...any)
- type Model
- type MySQLConfig
- type OpenOption
- type PageResponse
- type SingletonRepo
- type SoftDeleteModel
- type TXFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InTransactionContext ¶
InTransactionContext 在带有 context 的数据库事务中执行指定函数。
func IsUniqueViolation ¶
IsUniqueViolation 判断给定 error 是否为唯一键冲突。
func Open ¶
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 字段。
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 回调。
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 和时间戳。 嵌入此结构体后，实体自动获得主键和时间戳字段。
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 (*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 场景）。
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) LogMode ¶
func (l *Logger) LogMode(level gormLogger.LogLevel) gormLogger.Interface
LogMode 返回一个设置了新日志级别的 Logger 副本。
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 撞唯一约束时重读收敛（最多重试一次）； 单例表建议加唯一约束作为最终防线。
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 而非物理删除。
Source Files
Directories