Documentation
¶
Index ¶
- Constants
- Variables
- type BaseRepo
- func (r *BaseRepo[T]) Count(ctx context.Context) (int64, error)
- func (r *BaseRepo[T]) CountWhere(ctx context.Context, query string, args ...any) (int64, error)
- func (r *BaseRepo[T]) Create(ctx context.Context, model *T) error
- func (r *BaseRepo[T]) CreateBatch(ctx context.Context, models []T) error
- func (r *BaseRepo[T]) Delete(ctx context.Context, id uint) error
- func (r *BaseRepo[T]) DeleteBatch(ctx context.Context, ids []uint) error
- func (r *BaseRepo[T]) Exists(ctx context.Context, id uint) (bool, error)
- func (r *BaseRepo[T]) ExistsWhere(ctx context.Context, query string, args ...any) (bool, error)
- func (r *BaseRepo[T]) FindAll(ctx context.Context) ([]T, error)
- func (r *BaseRepo[T]) FindAllUnbounded(ctx context.Context) ([]T, error)
- func (r *BaseRepo[T]) FindAllWithDeleted(ctx context.Context) ([]T, error)
- func (r *BaseRepo[T]) FindByID(ctx context.Context, id uint) (*T, error)
- func (r *BaseRepo[T]) FindByIDs(ctx context.Context, ids []uint) ([]T, error)
- func (r *BaseRepo[T]) FindDeleted(ctx context.Context) ([]T, error)
- func (r *BaseRepo[T]) FindLimited(ctx context.Context, limit int) ([]T, error)
- func (r *BaseRepo[T]) FindOne(ctx context.Context, query string, args ...any) (*T, error)
- func (r *BaseRepo[T]) FindOrdered(ctx context.Context, order string, limit int) ([]T, error)
- func (r *BaseRepo[T]) FindPage(ctx context.Context, page, pageSize int) (*PageResult[T], error)
- func (r *BaseRepo[T]) FindPageOrdered(ctx context.Context, page, pageSize int, order string) (*PageResult[T], error)
- func (r *BaseRepo[T]) FindPageWhere(ctx context.Context, page, pageSize int, query string, args ...any) (*PageResult[T], error)
- func (r *BaseRepo[T]) FindPageWhereOrdered(ctx context.Context, page, pageSize int, order, query string, args ...any) (*PageResult[T], error)
- func (r *BaseRepo[T]) FindWhere(ctx context.Context, query string, args ...any) ([]T, error)
- func (r *BaseRepo[T]) FindWhereOrdered(ctx context.Context, order, query string, args ...any) ([]T, error)
- func (r *BaseRepo[T]) GetDB() *gorm.DB
- func (r *BaseRepo[T]) HardDelete(ctx context.Context, id uint) error
- func (r *BaseRepo[T]) HardDeleteBatch(ctx context.Context, ids []uint) error
- func (r *BaseRepo[T]) NewQueryBuilder() *QueryBuilder[T]
- func (r *BaseRepo[T]) Restore(ctx context.Context, id uint) error
- func (r *BaseRepo[T]) RestoreBatch(ctx context.Context, ids []uint) error
- func (r *BaseRepo[T]) SoftDeleteColumn() string
- func (r *BaseRepo[T]) Update(ctx context.Context, model *T) error
- func (r *BaseRepo[T]) UpdateBatch(ctx context.Context, ids []uint, field string, value any) error
- func (r *BaseRepo[T]) UpdateFields(ctx context.Context, model any, conds ...any) error
- func (r *BaseRepo[T]) WithTransaction(ctx context.Context, fn func(txRepo *BaseRepo[T]) error) error
- type BaseRepository
- type PageResult
- type QueryBuilder
- func (qb *QueryBuilder[T]) Count(ctx context.Context) (int64, error)
- func (qb *QueryBuilder[T]) Find(ctx context.Context) ([]T, error)
- func (qb *QueryBuilder[T]) First(ctx context.Context) (*T, error)
- func (qb *QueryBuilder[T]) Limit(limit int) *QueryBuilder[T]
- func (qb *QueryBuilder[T]) Offset(offset int) *QueryBuilder[T]
- func (qb *QueryBuilder[T]) Or(query string, args ...any) *QueryBuilder[T]
- func (qb *QueryBuilder[T]) Order(order string) *QueryBuilder[T]
- func (qb *QueryBuilder[T]) Page(ctx context.Context, page, pageSize int) (*PageResult[T], error)
- func (qb *QueryBuilder[T]) Where(query string, args ...any) *QueryBuilder[T]
Constants ¶
const ( // DefaultFindAllLimit caps FindAll to avoid accidental full-table scans. DefaultFindAllLimit = 1000 // DefaultPageSize is used when pageSize<=0. DefaultPageSize = 20 // MaxPageSize caps page queries to avoid Limit(0)/huge-limit footguns. MaxPageSize = 100 // MaxPage caps deep-offset queries; deeper traversal should use keyset pagination. MaxPage = 10000 )
Variables ¶
var ( ErrUnsafeOrder = errors.New("repository: unsafe order clause") ErrUnsafeField = errors.New("repository: unsafe field name") )
Functions ¶
This section is empty.
Types ¶
type BaseRepo ¶
type BaseRepo[T any] struct { // contains filtered or unexported fields }
BaseRepo 基础仓库实现。
连接路由契约（H6c 修复）：
- 读操作经 readConn(ctx) 路由：优先 join 外层事务，否则走 database.GetDBFromContext （默认从库，支持 UseMaster/UseReplica 读写分离），DefaultManager 未初始化时回退 r.db。
- 写操作经 writeConn(ctx) 路由：优先 join 外层事务，否则走主库 database.GetWriteDB()， 回退 r.db。写操作不路由到从库（从库只读）。
- 事务内（WithTransaction 创建的 txRepo）所有方法 join 同一事务。
下游典型用法 NewBaseRepo[T](database.GetDB()) 仍兼容：GetDB 返回主库，DefaultManager 初始化后读操作自动路由到从库；未初始化（如单测注入 sqlite）时回退到 r.db。
func (*BaseRepo[T]) CountWhere ¶
CountWhere 条件统计
func (*BaseRepo[T]) CreateBatch ¶
CreateBatch 批量创建
func (*BaseRepo[T]) Delete ¶
Delete 删除记录。
行为契约（H6b）：若 T 内嵌 gorm.DeletedAt（或 gorm.Model），为软删除； 否则为硬删除（泛型类型约束无法在编译期强制）。需硬删用 HardDelete，需恢复用 Restore。
func (*BaseRepo[T]) DeleteBatch ¶
DeleteBatch 批量删除
func (*BaseRepo[T]) ExistsWhere ¶
ExistsWhere 条件检查是否存在
func (*BaseRepo[T]) FindAll ¶
FindAll 查询记录，默认最多返回 DefaultFindAllLimit 条，避免误用导致全表扫描。 需要明确全量扫描时使用 FindAllUnbounded。
func (*BaseRepo[T]) FindAllUnbounded ¶ added in v1.3.0
FindAllUnbounded 查询所有记录（无默认 limit）。 仅用于明确需要全表扫描的后台任务/小表场景；在线请求优先使用分页或 FindAll。
func (*BaseRepo[T]) FindAllWithDeleted ¶
FindAllWithDeleted 查询所有记录（包括软删除）
func (*BaseRepo[T]) FindDeleted ¶
FindDeleted 查询已软删除的记录
func (*BaseRepo[T]) FindLimited ¶
FindLimited 查询指定数量记录
func (*BaseRepo[T]) FindOrdered ¶
FindOrdered 查询并排序
func (*BaseRepo[T]) FindPage ¶
FindPage 分页查询。
count 与 list 包进单事务（H6d），保证 total 与 items 在同一快照下一致， 避免高并发下两条独立语句间数据变动致 total/items 不一致。
若 ctx 已携带外层事务（database.WithTx），readConn 返回该 tx，此处 .Transaction 在其上开 savepoint（gorm 行为），count+list 仍同快照一致；无外层事务则开独立读事务。
func (*BaseRepo[T]) FindPageOrdered ¶
func (r *BaseRepo[T]) FindPageOrdered(ctx context.Context, page, pageSize int, order string) (*PageResult[T], error)
FindPageOrdered 分页查询并排序（count+list 单事务，H6d）
func (*BaseRepo[T]) FindPageWhere ¶
func (r *BaseRepo[T]) FindPageWhere(ctx context.Context, page, pageSize int, query string, args ...any) (*PageResult[T], error)
FindPageWhere 条件分页查询（count+list 单事务，H6d）
func (*BaseRepo[T]) FindPageWhereOrdered ¶
func (r *BaseRepo[T]) FindPageWhereOrdered(ctx context.Context, page, pageSize int, order, query string, args ...any) (*PageResult[T], error)
FindPageWhereOrdered 条件分页查询并排序（count+list 单事务，H6d）。
H-15 修复（breaking）：签名由 (ctx, page, pageSize, query, args []any, order) 改为 (ctx, page, pageSize, order, query string, args ...any)，与 FindPageWhere 统一为变长 args。 Go 语法要求变长参数必须为最后一个，故 order 前置于 query。
func (*BaseRepo[T]) FindWhereOrdered ¶
func (r *BaseRepo[T]) FindWhereOrdered(ctx context.Context, order, query string, args ...any) ([]T, error)
FindWhereOrdered 条件查询并排序。
H-15 修复（breaking）：签名由 (ctx, query, args []any, order) 改为 (ctx, order, query string, args ...any)，与 FindWhere 等同类方法统一为变长 args。 Go 语法要求变长参数必须为最后一个，故 order 前置于 query。
func (*BaseRepo[T]) GetDB ¶
GetDB 获取数据库实例。 事务内（txRepo）返回当前事务的 tx；否则返回构造时注入的 db。 注意：此方法无 ctx 参数，不参与读写分离路由；需要路由请用具体方法（FindByID/FindPage 等）。
func (*BaseRepo[T]) HardDelete ¶
HardDelete 硬删除记录（物理删除）
func (*BaseRepo[T]) HardDeleteBatch ¶
HardDeleteBatch 批量硬删除
func (*BaseRepo[T]) NewQueryBuilder ¶
func (r *BaseRepo[T]) NewQueryBuilder() *QueryBuilder[T]
NewQueryBuilder 创建查询构建器
func (*BaseRepo[T]) RestoreBatch ¶
RestoreBatch 批量恢复软删除记录
func (*BaseRepo[T]) SoftDeleteColumn ¶ added in v1.2.0
SoftDeleteColumn 返回软删除列名（RP2 修复：可被子类覆盖以适配自定义列名）。 默认 "deleted_at"，与 GORM gorm.DeletedAt 的默认列名一致。
func (*BaseRepo[T]) Update ¶
Update 更新记录（全列覆写，基于 Save）。
注意（H6a）：Save 会写入所有字段（包括零值），无法区分"未设置"与"清零"， 且可能用零值覆盖并发更新。需要局部更新（仅更新非零字段或指定字段）请用 UpdateFields。
func (*BaseRepo[T]) UpdateBatch ¶
UpdateBatch 批量更新（指定字段）
func (*BaseRepo[T]) UpdateFields ¶ added in v1.2.0
UpdateFields 局部更新（H6a）：基于 gorm.Updates，仅更新非零字段（struct）或指定字段（map）。
- 传 struct：仅更新非零字段（零值被忽略，避免覆盖）。
- 传 map[string]any：更新指定字段（可显式置零）。
示例：
repo.UpdateFields(ctx, &User{Name: "new"}) // struct：仅更新非零字段 name
repo.UpdateFields(ctx, map[string]any{"status": 0}, "id = ?", id) // map：显式置零，带条件
func (*BaseRepo[T]) WithTransaction ¶
func (r *BaseRepo[T]) WithTransaction(ctx context.Context, fn func(txRepo *BaseRepo[T]) error) error
WithTransaction 在事务中执行操作。
fn 收到的 txRepo 处于事务内，其所有方法（FindByID/Create/Update/...）自动 join 该事务， 不再路由到主从库（H6c）。事务在主库上开启。
跨 repo / 跨层 join：若 fn 内需调用其它 repo 或 database 层方法参与同一事务， 用 database.WithTx(ctx, tx) 把事务注入 ctx 后传递：
return repo.WithTransaction(ctx, func(txRepo *BaseRepo[T]) error {
if err := txRepo.Create(ctx, a); err != nil { return err }
// 另一个 repo 也加入同一事务：
ctx2 := database.WithTx(ctx, txRepo.GetDB())
return otherRepo.Update(ctx2, b)
})
注：fn 内捕获的 ctx 不会自动携带 tx；仅 txRepo 的方法 join 事务。
type BaseRepository ¶
type BaseRepository[T any] interface { // FindByID 根据 ID 查询 FindByID(ctx context.Context, id uint) (*T, error) // Create 创建记录 Create(ctx context.Context, model *T) error // Update 更新记录 Update(ctx context.Context, model *T) error // Delete 删除记录（T 含软删除字段时为软删除，否则为硬删除；详见 BaseRepo.Delete） Delete(ctx context.Context, id uint) error // FindByIDs 批量查询 FindByIDs(ctx context.Context, ids []uint) ([]T, error) }
BaseRepository 基础仓库接口
type PageResult ¶
type PageResult[T any] struct { Items []T `json:"items"` Total int64 `json:"total"` Page int `json:"page"` PageSize int `json:"page_size"` }
PageResult 分页结果
type QueryBuilder ¶
type QueryBuilder[T any] struct { // contains filtered or unexported fields }
QueryBuilder 链式查询构建器
func (*QueryBuilder[T]) Count ¶
func (qb *QueryBuilder[T]) Count(ctx context.Context) (int64, error)
Count 执行统计。 克隆并剥离 Limit/Offset（H6e），避免先前 Limit()/Offset() 残留截断统计行数。
func (*QueryBuilder[T]) Find ¶
func (qb *QueryBuilder[T]) Find(ctx context.Context) ([]T, error)
Find 执行查询
func (*QueryBuilder[T]) First ¶
func (qb *QueryBuilder[T]) First(ctx context.Context) (*T, error)
First 执行查询并返回第一条
func (*QueryBuilder[T]) Limit ¶
func (qb *QueryBuilder[T]) Limit(limit int) *QueryBuilder[T]
Limit 设置数量限制
func (*QueryBuilder[T]) Offset ¶
func (qb *QueryBuilder[T]) Offset(offset int) *QueryBuilder[T]
Offset 设置偏移量
func (*QueryBuilder[T]) Or ¶
func (qb *QueryBuilder[T]) Or(query string, args ...any) *QueryBuilder[T]
Or 添加 OR 条件
func (*QueryBuilder[T]) Order ¶
func (qb *QueryBuilder[T]) Order(order string) *QueryBuilder[T]
Order 设置排序
func (*QueryBuilder[T]) Page ¶
func (qb *QueryBuilder[T]) Page(ctx context.Context, page, pageSize int) (*PageResult[T], error)
Page 执行分页查询。 count 与 list 基于同一 Session 克隆，count 剥离 Limit/Offset（H6e）。 注意：与 FindPage 不同，Page 的 count+list 不包单事务（QueryBuilder 为轻量构建器）； 需要 total/items 快照一致请用 BaseRepo.FindPage。
func (*QueryBuilder[T]) Where ¶
func (qb *QueryBuilder[T]) Where(query string, args ...any) *QueryBuilder[T]
Where 添加条件
Source Files