sqlbuilder

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 23, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

README

go-sqlbuilder

GitHub go.mod Go version GoDoc License

一个功能丰富、高性能的 Go 语言 GORM 仓储层封装库，提供类型安全的 CRUD 操作、复杂查询构建和便利方法。

✨ 特性

  • 🚀 仓储模式：泛型 BaseRepository 和 EnhancedRepository，类型安全的 CRUD 操作
  • 🔍 高级查询：FilterGroup 支持复杂的 AND/OR 条件组合和无限嵌套
  • 🎯 类型安全：完全的泛型支持，编译时类型检查
  • 📊 性能优化：批量操作、游标分页、原子字段更新
  • 🔐 错误处理：集成 go-toolbox/errorx 的结构化错误管理
  • 📝 审计追踪：内置审计字段（created_by, updated_by）
  • 🛠️ 便利方法：常用操作的快捷方法

📦 安装

go get github.com/kamalyes/go-sqlbuilder

🚀 快速开始

package main

import (
    "context"
    "log"
    
    sqlbuilder "github.com/kamalyes/go-sqlbuilder"
    "github.com/kamalyes/go-logger"
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

type User struct {
    sqlbuilder.BaseModel
    Name   string `gorm:"type:varchar(100)"`
    Email  string `gorm:"type:varchar(100);uniqueIndex"`
    Age    int    `gorm:"type:int"`
    Status string `gorm:"type:varchar(20)"`
}

func main() {
    // 1. 连接数据库
    dsn := "user:password@tcp(127.0.0.1:3306)/testdb?charset=utf8mb4&parseTime=True"
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal(err)
    }
    
    // 2. 创建 Handler
    handler, err := sqlbuilder.NewGormHandler(db)
    if err != nil {
        log.Fatal(err)
    }
    
    // 3. 创建 Repository
    logger := logger.NewLogger(nil)
    repo := sqlbuilder.NewBaseRepository[User](handler, logger, "users")
    
    ctx := context.Background()
    
    // 4. 使用 Repository
    
    // 创建
    user := &User{Name: "张三", Email: "zhangsan@example.com", Age: 25}
    created, err := repo.Create(ctx, user)
    
    // 查询
    user, err = repo.Get(ctx, 1)
    
    // 更新
    user.Age = 26
    updated, err := repo.Update(ctx, user)
    
    // 删除
    err = repo.Delete(ctx, 1)
}

📚 核心功能

BaseRepository - 完整 CRUD

提供所有基础数据库操作：

repo := sqlbuilder.NewBaseRepository[User](handler, logger, "users")

// 创建操作
user, err := repo.Create(ctx, &User{Name: "Alice"})
err = repo.CreateBatch(ctx, users...)
created, isNew, err := repo.CreateIfNotExists(ctx, user, "email")

// 查询操作
user, err := repo.Get(ctx, 1)
users, err := repo.GetAll(ctx)
users, paging, err := repo.ListWithPagination(ctx, query, paging)

// 更新操作
user, err := repo.Update(ctx, user)
err = repo.UpdateFields(ctx, 1, map[string]interface{}{"age": 30})

// 删除操作
err = repo.Delete(ctx, 1)
err = repo.SoftDelete(ctx, 1, "deleted_at", time.Now())

// 统计操作
count, err := repo.Count(ctx)
exists, err := repo.Exists(ctx, filter)
EnhancedRepository - 便利方法

扩展方法提供更便捷的操作：

enhanced := sqlbuilder.NewEnhancedRepository[User](handler, logger, "users")

// 字段查询
users, err := enhanced.FindByField(ctx, "status", "active")

// 游标分页（大数据量性能更好）
users, cursor, err := enhanced.FindByFieldWithCursor(ctx, "status", "active", "", 20, "id", "ASC")

// 原子字段操作
err = enhanced.IncrementField(ctx, 1, "points", 10)      // 积分 +10
err = enhanced.DecrementField(ctx, 1, "stock", 5)        // 库存 -5
err = enhanced.ToggleField(ctx, 1, "is_active")          // 切换布尔值
FilterGroup - 复杂查询

支持任意复杂的 AND/OR 条件组合：

// 查询条件：(status = 'active' OR status = 'trial') AND age > 18
statusGroup := sqlbuilder.NewFilterGroup(sqlbuilder.OR).
    AddFilter(sqlbuilder.NewEqFilter("status", "active")).
    AddFilter(sqlbuilder.NewEqFilter("status", "trial"))

mainGroup := sqlbuilder.NewFilterGroup(sqlbuilder.AND).
    AddGroup(statusGroup).
    AddFilter(sqlbuilder.NewGtFilter("age", 18))

query := sqlbuilder.NewQuery().SetFilterGroup(mainGroup)
users, err := repo.List(ctx, query)
丰富的过滤器
// 比较操作
NewEqFilter("status", "active")              // =
NewGtFilter("age", 18)                       // >
NewBetweenFilter("price", 100, 1000)         // BETWEEN

// 范围操作
NewInFilter("id", []interface{}{1, 2, 3})    // IN
NewNotInFilter("status", []interface{}{"deleted", "banned"})

// 模糊查询
NewLikeFilter("name", "张")                  // LIKE '%张%'

// NULL 检查
NewIsNullFilter("deleted_at")                // IS NULL
NewIsNotNullFilter("verified_at")            // IS NOT NULL

// 时间范围
NewTodayFilter("created_at")                 // 今天
NewThisWeekFilter("created_at")              // 本周
NewLastMonthFilter("created_at")             // 上月

// 自定义 SQL
NewCustomFilter("YEAR(created_at) = ?", 2024)

📖 完整文档

我们提供了详细的模块化文档：

🏗️ 内置模型

BaseModel

包含基础字段的模型：

type User struct {
    sqlbuilder.BaseModel  // ID, CreatedAt, UpdatedAt, DeletedAt
    Name  string
    Email string
}
AuditModel

包含审计字段的模型：

type Article struct {
    sqlbuilder.AuditModel  // BaseModel + CreatedBy, UpdatedBy
    Title   string
    Content string
}

⚙️ 配置选项

repo := sqlbuilder.NewBaseRepository[User](
    handler,
    logger,
    "users",
    sqlbuilder.WithBatchSize[User](200),              // 批处理大小
    sqlbuilder.WithTimeout[User](60),                 // 超时时间
    sqlbuilder.WithDefaultPreloads[User]("Profile"),  // 默认预加载
    sqlbuilder.WithDefaultOrder[User]("id DESC"),     // 默认排序
)

🧪 测试

# 运行所有测试
go test ./... -v

# 测试覆盖率
go test ./... -cover

# 运行特定测试
go test -v -run TestBaseRepository

📦 依赖

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

👨‍💻 作者

Kamal Yang (@kamalyes)

🙏 致谢

  • GORM 团队提供的优秀 ORM
  • Go 社区的灵感和支持

Documentation

Overview

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\constants.go * @Description: 常量定义 - 操作符、分页、批处理等配置 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\filter.go * @Description: 过滤器和查询构建 - Filter、FilterGroup、Query等查询条件 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\handler.go * @Description: 数据库处理器 - Handler 接口和 GORM 实现 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:48:38 * @FilePath: \go-sqlbuilder\helpers.go * @Description: 仓储辅助工具 - 软删除、查询辅助等功能 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:49:04 * @FilePath: \go-sqlbuilder\interfaces.go * @Description: 核心接口定义 - Repository、Transaction、Query 等 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\mapopt.go * @Description: Map类型扩展 - MapAny、MapString、StringSlice的数据库序列化 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\model.go * @Description: 基础模型定义 - BaseModel、AuditModel、UUIDModel 等 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\paging.go * @Description: 分页工具 - Pagination分页元数据和辅助方法 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-11 21:13:15 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:39:16 * @FilePath: \go-sqlbuilder\repository.go * @Description: * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-11-23 00:00:00 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-11-23 22:50:00 * @FilePath: \go-sqlbuilder\types.go * @Description: 类型定义 - Filter、Pagination、QueryCondition 等 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

Index

Constants

View Source 
const (
	OP_EQ          = OpEqual
	OP_NEQ         = OpNotEqual
	OP_GT          = OpGreaterThan
	OP_GTE         = OpGreaterThanOrEqual
	OP_LT          = OpLessThan
	OP_LTE         = OpLessThanOrEqual
	OP_LIKE        = OpLike
	OP_NOT_LIKE    = OpNotLike
	OP_IN          = OpIn
	OP_NOT_IN      = OpNotIn
	OP_BETWEEN     = OpBetween
	OP_IS_NULL     = OpIsNull
	OP_IS_NOT_NULL = OpIsNotNull
	OP_FIND_IN_SET = OpFindInSet
	LOGIC_AND      = LogicAnd
	LOGIC_OR       = LogicOr
)
View Source 
const (
	// DefaultPage 默认页码
	DefaultPage = 1

	// DefaultPageSize 默认每页大小
	DefaultPageSize = 10
)
View Source 
const (
	// SQL_EQUAL 等于条件模板
	SQL_EQUAL = "%s = ?"

	// SQL_NOT_EQUAL 不等于条件模板
	SQL_NOT_EQUAL = "%s != ?"

	// SQL_GREATER 大于条件模板
	SQL_GREATER = "%s > ?"

	// SQL_GREATER_EQUAL 大于等于条件模板
	SQL_GREATER_EQUAL = "%s >= ?"

	// SQL_LESS 小于条件模板
	SQL_LESS = "%s < ?"

	// SQL_LESS_EQUAL 小于等于条件模板
	SQL_LESS_EQUAL = "%s <= ?"

	// SQL_IN IN条件模板
	SQL_IN = "%s IN ?"

	// SQL_NOT_IN NOT IN条件模板
	SQL_NOT_IN = "%s NOT IN ?"

	// SQL_LIKE LIKE条件模板
	SQL_LIKE = "%s LIKE ?"

	// SQL_NOT_LIKE NOT LIKE条件模板
	SQL_NOT_LIKE = "%s NOT LIKE ?"

	// SQL_BETWEEN BETWEEN条件模板
	SQL_BETWEEN = "%s BETWEEN ? AND ?"

	// SQL_IS_NULL IS NULL条件模板
	SQL_IS_NULL = "%s IS NULL"

	// SQL_IS_NOT_NULL IS NOT NULL条件模板
	SQL_IS_NOT_NULL = "%s IS NOT NULL"

	// SQL_FIND_IN_SET FIND_IN_SET条件模板
	SQL_FIND_IN_SET = "FIND_IN_SET(?, %s)"

	// SQL_ORDER_BY 排序模板
	SQL_ORDER_BY = "%s %s"

	// SQL_INCREMENT 字段自增模板
	SQL_INCREMENT = "%s + ?"

	// SQL_DECREMENT 字段自减模板
	SQL_DECREMENT = "%s - ?"
)
View Source 
const (
	// Asc 升序
	Asc = "ASC"

	// Desc 降序
	Desc = "DESC"

	// DefaultOrder 默认排序方向
	DefaultOrder = Asc
)
View Source 
const (
	// DefaultBatchSize 默认批处理大小
	DefaultBatchSize = 100
)
View Source 
const (
	// DefaultQueryTimeout 默认查询超时时间（秒）
	DefaultQueryTimeout = 30
)

Variables

This section is empty.

Functions

func GetDeleted added in v0.2.0 

func GetDeleted[T any](ctx context.Context, db *gorm.DB, query *Query) ([]*T, error)

GetDeleted 获取已删除的记录（使用deleted_at字段）

func GetNonDeleted added in v0.2.0 

func GetNonDeleted[T any](ctx context.Context, db *gorm.DB, query *Query) ([]*T, error)

GetNonDeleted 获取未删除的记录（使用deleted_at字段）

func PermanentlyDelete added in v0.2.0 

func PermanentlyDelete[T any](ctx context.Context, db *gorm.DB, id interface{}) error

PermanentlyDelete 永久删除记录（从数据库中完全删除）

func PermanentlyDeleteBatch added in v0.2.0 

func PermanentlyDeleteBatch[T any](ctx context.Context, db *gorm.DB, ids []interface{}) error

PermanentlyDeleteBatch 批量永久删除记录（从数据库中完全删除）

func RestoreDeleted added in v0.2.0 

func RestoreDeleted[T any](ctx context.Context, db *gorm.DB, id interface{}) error

RestoreDeleted 恢复单个已删除记录（将deleted_at设为NULL）

func RestoreDeletedBatch added in v0.2.0 

func RestoreDeletedBatch[T any](ctx context.Context, db *gorm.DB, ids []interface{}) error

RestoreDeletedBatch 批量恢复已删除记录（将deleted_at设为NULL）

Types

type AuditModel added in v0.2.0 

type AuditModel struct {
	BaseModel
	CreatedBy uint `json:"created_by,omitempty" gorm:"index;comment:创建人ID"`
	UpdatedBy uint `json:"updated_by,omitempty" gorm:"index;comment:更新人ID"`
}

AuditModel 审计模型（包含创建人和更新人信息） 适用于需要追踪操作人的业务场景

func (*AuditModel) GetCreatedBy added in v0.2.0 

func (m *AuditModel) GetCreatedBy() uint

func (*AuditModel) GetUpdatedBy added in v0.2.0 

func (m *AuditModel) GetUpdatedBy() uint

func (*AuditModel) SetCreatedBy added in v0.2.0 

func (m *AuditModel) SetCreatedBy(userID uint)

func (*AuditModel) SetUpdatedBy added in v0.2.0 

func (m *AuditModel) SetUpdatedBy(userID uint)

type AuditableModel added in v0.2.0 

type AuditableModel interface {
	ModelInterface
	SetCreatedBy(userID uint)
	SetUpdatedBy(userID uint)
	GetCreatedBy() uint
	GetUpdatedBy() uint
}

AuditableModel 支持审计的模型接口

type BaseModel added in v0.2.0 

type BaseModel struct {
	ID        uint           `json:"id" gorm:"primaryKey;autoIncrement;comment:自增主键"`
	Version   int            `json:"version" gorm:"default:1;comment:版本号"`
	CreatedAt time.Time      `json:"created_at" gorm:"autoCreateTime;comment:创建时间"`
	UpdatedAt time.Time      `json:"updated_at" gorm:"autoUpdateTime;comment:更新时间"`
	DeletedAt gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index;comment:删除时间"`
	Remark    string         `json:"remark,omitempty" gorm:"type:varchar(500);comment:备注"`
	Status    int8           `json:"status" gorm:"default:1;index;comment:状态(1:启用 0:禁用)"`
}

BaseModel 公共基础模型（带软删除、状态管理、版本控制）

func (*BaseModel) BeforeUpdate added in v0.2.0 

func (m *BaseModel) BeforeUpdate(tx *gorm.DB) error

BeforeUpdate GORM更新前钩子

func (*BaseModel) Disable added in v0.2.0 

func (m *BaseModel) Disable()

Disable 禁用

func (*BaseModel) Enable added in v0.2.0 

func (m *BaseModel) Enable()

Enable 启用

func (*BaseModel) GetID added in v0.2.0 

func (m *BaseModel) GetID() uint

GetID 获取主键ID

func (*BaseModel) GetVersion added in v0.2.0 

func (m *BaseModel) GetVersion() int

GetVersion 获取版本号

func (*BaseModel) IsDeleted added in v0.2.0 

func (m *BaseModel) IsDeleted() bool

IsDeleted 判断是否已删除

func (*BaseModel) IsEnabled added in v0.2.0 

func (m *BaseModel) IsEnabled() bool

IsEnabled 判断是否启用

func (*BaseModel) IsNew added in v0.2.0 

func (m *BaseModel) IsNew() bool

IsNew 判断是否为新记录

func (*BaseModel) SetCreatedAt added in v0.2.0 

func (m *BaseModel) SetCreatedAt(t time.Time)

func (*BaseModel) SetRemark added in v0.2.0 

func (m *BaseModel) SetRemark(remark string)

SetRemark 设置备注

func (*BaseModel) SetUpdatedAt added in v0.2.0 

func (m *BaseModel) SetUpdatedAt(t time.Time)

type BaseRepository added in v0.2.0 

type BaseRepository[T any] struct {
	// contains filtered or unexported fields
}

BaseRepository 基础仓储实现，包含通用的 CRUD 操作

func NewBaseRepository added in v0.2.0 

func NewBaseRepository[T any](dbHandler Handler, logger gologger.ILogger, table string, options ...RepositoryOption[T]) *BaseRepository[T]

NewBaseRepository 创建基础仓储

func (*BaseRepository[T]) BulkCreate added in v0.2.0 

func (r *BaseRepository[T]) BulkCreate(ctx context.Context, entities []*T, batchSize ...int) error

BulkCreate 高性能批量创建

func (*BaseRepository[T]) Count added in v0.2.0 

func (r *BaseRepository[T]) Count(ctx context.Context, filters ...*Filter) (int64, error)

Count 计数

func (*BaseRepository[T]) CountByField added in v0.2.0 

func (r *BaseRepository[T]) CountByField(ctx context.Context, field string) (map[interface{}]int64, error)

CountByField 按字段计数（GROUP BY）

func (*BaseRepository[T]) Create added in v0.2.0 

func (r *BaseRepository[T]) Create(ctx context.Context, entity *T) (*T, error)

Create 创建单个记录

func (*BaseRepository[T]) CreateBatch added in v0.2.0 

func (r *BaseRepository[T]) CreateBatch(ctx context.Context, entities ...*T) error

CreateBatch 批量创建记录

func (*BaseRepository[T]) CreateIfNotExists added in v0.2.0 

func (r *BaseRepository[T]) CreateIfNotExists(ctx context.Context, entity *T, uniqueFields ...string) (*T, bool, error)

CreateIfNotExists 如果不存在则创建

func (*BaseRepository[T]) CreateOrUpdate added in v0.2.0 

func (r *BaseRepository[T]) CreateOrUpdate(ctx context.Context, entity *T, uniqueFields ...string) (*T, bool, error)

CreateOrUpdate 创建或更新记录

func (*BaseRepository[T]) DBHandler added in v0.2.0 

func (r *BaseRepository[T]) DBHandler() Handler

DBHandler 获取数据库处理器

func (*BaseRepository[T]) Delete added in v0.2.0 

func (r *BaseRepository[T]) Delete(ctx context.Context, id interface{}) error

Delete 删除单个记录

func (*BaseRepository[T]) DeleteBatch added in v0.2.0 

func (r *BaseRepository[T]) DeleteBatch(ctx context.Context, ids ...interface{}) error

DeleteBatch 批量删除记录

func (*BaseRepository[T]) DeleteByFilters added in v0.2.0 

func (r *BaseRepository[T]) DeleteByFilters(ctx context.Context, filters ...*Filter) error

DeleteByFilters 按过滤条件删除记录

func (*BaseRepository[T]) Distinct added in v0.2.0 

func (r *BaseRepository[T]) Distinct(ctx context.Context, field string, filters ...*Filter) ([]interface{}, error)

Distinct 获取去重后的字段值列表

func (*BaseRepository[T]) Exists added in v0.2.0 

func (r *BaseRepository[T]) Exists(ctx context.Context, filters ...*Filter) (bool, error)

Exists 检查记录是否存在

func (*BaseRepository[T]) Find added in v0.2.0 

func (r *BaseRepository[T]) Find(ctx context.Context, options *FindOptions) ([]*T, error)

Find 通用查询方法，兼容旧的API调用方式

func (*BaseRepository[T]) FindOne added in v0.2.0 

func (r *BaseRepository[T]) FindOne(ctx context.Context, filters ...*Filter) (*T, error)

FindOne 查找单条记录（不存在返回 nil）

func (*BaseRepository[T]) First added in v0.2.0 

func (r *BaseRepository[T]) First(ctx context.Context, filters ...*Filter) (*T, error)

First 获取第一条记录

func (*BaseRepository[T]) Get added in v0.2.0 

func (r *BaseRepository[T]) Get(ctx context.Context, id interface{}) (*T, error)

Get 获取单个记录

func (*BaseRepository[T]) GetAll added in v0.2.0 

func (r *BaseRepository[T]) GetAll(ctx context.Context) ([]*T, error)

GetAll 获取所有记录（不分页）

func (*BaseRepository[T]) GetByFields added in v0.2.0 

func (r *BaseRepository[T]) GetByFields(ctx context.Context, fields map[string]interface{}) (*T, error)

GetByFields 根据多个字段获取记录

func (*BaseRepository[T]) GetByFilter added in v0.2.0 

func (r *BaseRepository[T]) GetByFilter(ctx context.Context, filter *Filter) (*T, error)

GetByFilter 按单个过滤条件获取记录

func (*BaseRepository[T]) GetByFilters added in v0.2.0 

func (r *BaseRepository[T]) GetByFilters(ctx context.Context, filters ...*Filter) (*T, error)

GetByFilters 按多个过滤条件获取记录

func (*BaseRepository[T]) GetWithPreloads added in v0.2.0 

func (r *BaseRepository[T]) GetWithPreloads(ctx context.Context, id interface{}, preloads ...string) (*T, error)

GetWithPreloads 获取单个记录并指定预加载关联

func (*BaseRepository[T]) Last added in v0.2.0 

func (r *BaseRepository[T]) Last(ctx context.Context, filters ...*Filter) (*T, error)

Last 获取最后一条记录

func (*BaseRepository[T]) List added in v0.2.0 

func (r *BaseRepository[T]) List(ctx context.Context, query *Query) ([]*T, error)

List 列表查询

func (*BaseRepository[T]) ListWithPagination added in v0.2.0 

func (r *BaseRepository[T]) ListWithPagination(ctx context.Context, query *Query, page *Pagination) ([]*T, *Pagination, error)

ListWithPagination 分页列表查询

func (*BaseRepository[T]) ListWithPreloads added in v0.2.0 

func (r *BaseRepository[T]) ListWithPreloads(ctx context.Context, query *Query, preloads ...string) ([]*T, error)

ListWithPreloads 列表查询并指定预加载关联

func (*BaseRepository[T]) Pluck added in v0.2.0 

func (r *BaseRepository[T]) Pluck(ctx context.Context, field string, filters ...*Filter) ([]interface{}, error)

Pluck 提取单个字段的值列表

func (*BaseRepository[T]) Restore added in v0.2.0 

func (r *BaseRepository[T]) Restore(ctx context.Context, id interface{}, field string, restoreValue interface{}) error

Restore 恢复软删除的记录 field: 软删除字段名，如 "deleted_at", "is_deleted" 等 restoreValue: 恢复时的值，如 nil, 0 等

func (*BaseRepository[T]) RestoreBatch added in v0.2.0 

func (r *BaseRepository[T]) RestoreBatch(ctx context.Context, ids []interface{}, field string, restoreValue interface{}) error

RestoreBatch 批量恢复软删除的记录 field: 软删除字段名，如 "deleted_at", "is_deleted" 等 restoreValue: 恢复时的值，如 nil, 0 等

func (*BaseRepository[T]) SoftDelete added in v0.2.0 

func (r *BaseRepository[T]) SoftDelete(ctx context.Context, id interface{}, field string, value interface{}) error

SoftDelete 软删除（需要指定删除标记字段和值） field: 软删除字段名，如 "deleted_at", "is_deleted" 等 value: 软删除标记值，如 time.Now(), 1 等

func (*BaseRepository[T]) SoftDeleteBatch added in v0.2.0 

func (r *BaseRepository[T]) SoftDeleteBatch(ctx context.Context, ids []interface{}, field string, value interface{}) error

SoftDeleteBatch 批量软删除 field: 软删除字段名，如 "deleted_at", "is_deleted" 等 value: 软删除标记值，如 time.Now(), 1 等

func (*BaseRepository[T]) SoftDeleteByFilters added in v0.2.0 

func (r *BaseRepository[T]) SoftDeleteByFilters(ctx context.Context, field string, value interface{}, filters ...*Filter) error

SoftDeleteByFilters 按过滤条件软删除 field: 软删除字段名，如 "deleted_at", "is_deleted" 等 value: 软删除标记值，如 time.Now(), 1 等

func (*BaseRepository[T]) Table added in v0.2.0 

func (r *BaseRepository[T]) Table() string

Table 获取表名

func (*BaseRepository[T]) Transaction added in v0.2.0 

func (r *BaseRepository[T]) Transaction(ctx context.Context, fn func(tx Transaction[T]) error) error

Transaction 事务支持

func (*BaseRepository[T]) Update added in v0.2.0 

func (r *BaseRepository[T]) Update(ctx context.Context, entity *T) (*T, error)

Update 更新单个记录

func (*BaseRepository[T]) UpdateBatch added in v0.2.0 

func (r *BaseRepository[T]) UpdateBatch(ctx context.Context, entities ...*T) error

UpdateBatch 批量更新记录

func (*BaseRepository[T]) UpdateByFilters added in v0.2.0 

func (r *BaseRepository[T]) UpdateByFilters(ctx context.Context, entity *T, filters ...*Filter) error

UpdateByFilters 按过滤条件更新记录

func (*BaseRepository[T]) UpdateFields added in v0.2.0 

func (r *BaseRepository[T]) UpdateFields(ctx context.Context, id interface{}, fields map[string]interface{}) error

UpdateFields 更新指定字段

func (*BaseRepository[T]) UpdateFieldsByFilters added in v0.2.0 

func (r *BaseRepository[T]) UpdateFieldsByFilters(ctx context.Context, fields map[string]interface{}, filters ...*Filter) error

UpdateFieldsByFilters 按过滤条件更新指定字段

type ComparedColumn added in v0.2.0 

type ComparedColumn struct {
	TableAlias  string
	ColumnName  string
	DBFieldName string
}

type ComparedValue added in v0.2.0 

type ComparedValue struct {
	Value interface{}
	IsRaw bool
}

type Condition added in v0.2.0 

type Condition struct {
	Field string
	Op    Operator
	Value interface{}
}

Condition 查询条件结构

type ContextFieldExtractor added in v0.2.0 

type ContextFieldExtractor func(ctx context.Context, log logger.ILogger) logger.ILogger

ContextFieldExtractor context字段提取器函数类型 用于从context中提取需要记录到日志的字段

type EnhancedRepository added in v0.2.0 

type EnhancedRepository[T any] struct {
	*BaseRepository[T]
	// contains filtered or unexported fields
}

EnhancedRepository 增强版仓储实现

func NewEnhancedRepository added in v0.2.0 

func NewEnhancedRepository[T any](dbHandler Handler, logger gologger.ILogger, tableName string) *EnhancedRepository[T]

NewEnhancedRepository 创建增强版仓储实例

func NewEnhancedRepositoryWithDB added in v0.2.0 

func NewEnhancedRepositoryWithDB[T any](gormDB *gorm.DB, logger gologger.ILogger, tableName string) *EnhancedRepository[T]

NewEnhancedRepositoryWithDB 使用GORM DB直接创建增强版仓储

func (*EnhancedRepository[T]) BatchUpdateByField added in v0.2.0 

func (r *EnhancedRepository[T]) BatchUpdateByField(ctx context.Context, field string, values []interface{}, updates map[string]interface{}) error

BatchUpdateByField 根据字段批量更新

func (*EnhancedRepository[T]) CountByField added in v0.2.0 

func (r *EnhancedRepository[T]) CountByField(ctx context.Context, field string, value interface{}) (int64, error)

CountByField 根据字段统计数量

func (*EnhancedRepository[T]) CreateIfNotExists added in v0.2.0 

func (r *EnhancedRepository[T]) CreateIfNotExists(ctx context.Context, entity *T, checkField string) (*T, bool, error)

CreateIfNotExists 如果不存在则创建

func (*EnhancedRepository[T]) DecrementField added in v0.2.0 

func (r *EnhancedRepository[T]) DecrementField(ctx context.Context, whereField string, whereValue interface{}, decrementField string, step int64) error

DecrementField 字段自减

func (*EnhancedRepository[T]) DeleteByField added in v0.2.0 

func (r *EnhancedRepository[T]) DeleteByField(ctx context.Context, field string, value interface{}) error

DeleteByField 根据字段删除记录

func (*EnhancedRepository[T]) ExistsBy added in v0.2.0 

func (r *EnhancedRepository[T]) ExistsBy(ctx context.Context, field string, value interface{}) (bool, error)

ExistsBy 检查记录是否存在

func (*EnhancedRepository[T]) FindByField added in v0.2.0 

func (r *EnhancedRepository[T]) FindByField(ctx context.Context, field string, value interface{}) ([]*T, error)

FindByField 根据单个字段查找记录

func (*EnhancedRepository[T]) FindByFieldWithCursor added in v0.2.0 

func (r *EnhancedRepository[T]) FindByFieldWithCursor(ctx context.Context, field string, value interface{}, cursorField string, lastCursor interface{}, limit int) ([]*T, bool, error)

FindByFieldWithCursor 根据字段查找记录（游标分页）

func (*EnhancedRepository[T]) FindByFieldWithPagination added in v0.2.0 

func (r *EnhancedRepository[T]) FindByFieldWithPagination(ctx context.Context, field string, value interface{}, limit, offset int) ([]*T, int64, error)

FindByFieldWithPagination 根据字段查找记录（带分页）

func (*EnhancedRepository[T]) FindByFields added in v0.2.0 

func (r *EnhancedRepository[T]) FindByFields(ctx context.Context, conditions map[string]interface{}) ([]*T, error)

FindByFields 根据多个字段查找记录

func (*EnhancedRepository[T]) FindByTimeRange added in v0.2.0 

func (r *EnhancedRepository[T]) FindByTimeRange(ctx context.Context, timeField string, startTime, endTime interface{}) ([]*T, error)

FindByTimeRange 根据时间范围查找

func (*EnhancedRepository[T]) FindInField added in v0.2.0 

func (r *EnhancedRepository[T]) FindInField(ctx context.Context, field string, values []interface{}) ([]*T, error)

FindInField 根据字段的IN查询

func (*EnhancedRepository[T]) FindOneByField added in v0.2.0 

func (r *EnhancedRepository[T]) FindOneByField(ctx context.Context, field string, value interface{}) (*T, error)

FindOneByField 根据单个字段查找单条记录

func (*EnhancedRepository[T]) FindWithOrder added in v0.2.0 

func (r *EnhancedRepository[T]) FindWithOrder(ctx context.Context, whereField string, whereValue interface{}, orderField string, orderDirection string) ([]*T, error)

FindWithOrder 根据条件查找并排序

func (*EnhancedRepository[T]) GetDistinctValues added in v0.2.0 

func (r *EnhancedRepository[T]) GetDistinctValues(ctx context.Context, field string) ([]interface{}, error)

GetDistinctValues 获取字段的不同值

func (*EnhancedRepository[T]) IncrementField added in v0.2.0 

func (r *EnhancedRepository[T]) IncrementField(ctx context.Context, whereField string, whereValue interface{}, incrementField string, step int64) error

IncrementField 字段自增

func (*EnhancedRepository[T]) UpdateByField added in v0.2.0 

func (r *EnhancedRepository[T]) UpdateByField(ctx context.Context, field string, value interface{}, updates map[string]interface{}) error

UpdateByField 根据字段更新记录

func (*EnhancedRepository[T]) UpdateSingleField added in v0.2.0 

func (r *EnhancedRepository[T]) UpdateSingleField(ctx context.Context, whereField string, whereValue interface{}, updateField string, updateValue interface{}) error

UpdateSingleField 更新单个字段

type ErrorCode added in v0.2.0 

type ErrorCode = errorx.ErrorType

ErrorCode 错误代码类型(复用 errorx.ErrorType) 

const (
	ErrorCodeNotFound     ErrorCode = 1001 // 记录不存在
	ErrorCodeAlreadyExist ErrorCode = 1002 // 记录已存在
	ErrorCodeInvalidInput ErrorCode = 1003 // 输入参数无效
	ErrorCodeUnauthorized ErrorCode = 1004 // 未授权
	ErrorCodeForbidden    ErrorCode = 1005 // 禁止访问
	ErrorCodeConflict     ErrorCode = 1006 // 操作冲突
)

通用业务错误 (1000-1999) 

const (
	ErrorCodeDBError           ErrorCode = 2001 // 数据库操作失败
	ErrorCodeDBDuplicate       ErrorCode = 2002 // 数据库记录重复
	ErrorCodeDBConstraint      ErrorCode = 2003 // 数据库约束冲突
	ErrorCodeDBDeadlock        ErrorCode = 2004 // 数据库死锁
	ErrorCodeNoDatabaseConn    ErrorCode = 2005 // 无数据库连接
	ErrorCodeDBFailedUpdate    ErrorCode = 2006 // 数据库更新失败
	ErrorCodeDBFailedInsert    ErrorCode = 2007 // 数据库插入失败
	ErrorCodeDBFailedDelete    ErrorCode = 2008 // 数据库删除失败
	ErrorCodeNestedTransaction ErrorCode = 2009 // 嵌套事务错误
)

数据库错误 (2000-2999) 

const (
	ErrorCodeCacheError              ErrorCode = 3001 // 缓存操作失败
	ErrorCodeCacheMiss               ErrorCode = 3002 // 缓存未命中
	ErrorCodeCacheStoreNotFound      ErrorCode = 3003 // 缓存存储未找到
	ErrorCodeCacheKeyNotFound        ErrorCode = 3004 // 缓存键不存在
	ErrorCodeCacheExpired            ErrorCode = 3005 // 缓存已过期
	ErrorCodeCacheStoreNotConfigured ErrorCode = 3006 // 缓存存储未配置
	ErrorCodeCacheInvalidData        ErrorCode = 3007 // 缓存数据无效
)

缓存错误 (3000-3999) 

const (
	ErrorCodeResourceNotFound      ErrorCode = 4001 // 资源不存在
	ErrorCodeBuilderNotInitialized ErrorCode = 4002 // Builder未初始化
	ErrorCodeInvalidTableName      ErrorCode = 4003 // 表名无效
	ErrorCodeInvalidFieldName      ErrorCode = 4004 // 字段名无效
	ErrorCodeInvalidSQLQuery       ErrorCode = 4005 // SQL查询无效
	ErrorCodeAdapterNotSupported   ErrorCode = 4006 // 适配器不支持
)

SQL构建器错误 (4000-4999) 

const (
	ErrorCodeInvalidOperator    ErrorCode = 4101 // 无效的操作符
	ErrorCodeInvalidFilterValue ErrorCode = 4102 // 过滤值无效
	ErrorCodePageNumberInvalid  ErrorCode = 4103 // 页码无效
	ErrorCodePageSizeInvalid    ErrorCode = 4104 // 页大小无效
	ErrorCodeTimeRangeInvalid   ErrorCode = 4105 // 时间范围无效
	ErrorCodeEmptyFilterParam   ErrorCode = 4106 // 过滤参数为空
)

查询错误 (复用4000区间扩展) 

const (
	ErrorCodeInternal        ErrorCode = 9001 // 内部服务错误
	ErrorCodeTimeout         ErrorCode = 9002 // 请求超时
	ErrorCodeTooManyRequests ErrorCode = 9003 // 请求过于频繁（限流）
	ErrorCodeUnsupported     ErrorCode = 9004 // 不支持的操作
	ErrorCodeUnknown         ErrorCode = 9005 // 未知错误
	ErrorCodeOperationFailed ErrorCode = 9006 // 操作失败
)

系统级错误 (9000-9999) 

const (
	ErrorCodeSuccess ErrorCode = 0 // 成功
)

基础通用错误 (0-999)

type Filter 

type Filter struct {
	Field    string      // 字段名
	Operator Operator    // 操作符
	Value    interface{} // 值
}

Filter 过滤条件

func NewBetweenFilter added in v0.2.0 

func NewBetweenFilter(field string, min, max interface{}) *Filter

NewBetweenFilter 创建 BETWEEN 过滤条件

func NewContainsFilter added in v0.2.0 

func NewContainsFilter(field string, value string) *Filter

NewContainsFilter 创建包含匹配过滤条件（与 NewLikeFilter 相同）

func NewEndsWithFilter added in v0.2.0 

func NewEndsWithFilter(field string, value string) *Filter

NewEndsWithFilter 创建后缀匹配过滤条件

func NewEqFilter added in v0.2.0 

func NewEqFilter(field string, value interface{}) *Filter

NewEqFilter 创建等于过滤条件

func NewFindInSetFilter added in v0.2.0 

func NewFindInSetFilter(field string, value interface{}) *Filter

NewFindInSetFilter 创建 FIND_IN_SET 过滤条件（MySQL特定）

func NewGtFilter added in v0.2.0 

func NewGtFilter(field string, value interface{}) *Filter

NewGtFilter 创建大于过滤条件

func NewGteFilter added in v0.2.0 

func NewGteFilter(field string, value interface{}) *Filter

NewGteFilter 创建大于等于过滤条件

func NewInFilter added in v0.2.0 

func NewInFilter(field string, values ...interface{}) *Filter

NewInFilter 创建 IN 过滤条件

func NewIsNotNullFilter added in v0.2.0 

func NewIsNotNullFilter(field string) *Filter

NewIsNotNullFilter 创建 IS NOT NULL 过滤条件

func NewIsNullFilter added in v0.2.0 

func NewIsNullFilter(field string) *Filter

NewIsNullFilter 创建 IS NULL 过滤条件

func NewLikeFilter added in v0.2.0 

func NewLikeFilter(field string, value string) *Filter

NewLikeFilter 创建 LIKE 过滤条件

func NewLtFilter added in v0.2.0 

func NewLtFilter(field string, value interface{}) *Filter

NewLtFilter 创建小于过滤条件

func NewLteFilter added in v0.2.0 

func NewLteFilter(field string, value interface{}) *Filter

NewLteFilter 创建小于等于过滤条件

func NewNeqFilter added in v0.2.0 

func NewNeqFilter(field string, value interface{}) *Filter

NewNeqFilter 创建不等于过滤条件

func NewNotInFilter added in v0.2.0 

func NewNotInFilter(field string, values ...interface{}) *Filter

NewNotInFilter 创建 NOT IN 过滤条件

func NewNotLikeFilter added in v0.2.0 

func NewNotLikeFilter(field string, value string) *Filter

NewNotLikeFilter 创建 NOT LIKE 过滤条件

func NewStartsWithFilter added in v0.2.0 

func NewStartsWithFilter(field string, value string) *Filter

NewStartsWithFilter 创建前缀匹配过滤条件

type FilterGroup 

type FilterGroup struct {
	Filters []*Filter      // 过滤条件列表
	Groups  []*FilterGroup // 嵌套条件组
	LogicOp Operator       // 逻辑操作符：AND/OR
}

FilterGroup 过滤条件组，支持逻辑操作

func NewFilterGroup added in v0.2.0 

func NewFilterGroup(logicOp Operator) *FilterGroup

NewFilterGroup 创建新的过滤条件组

func (*FilterGroup) AddFilter added in v0.2.0 

func (fg *FilterGroup) AddFilter(filter *Filter) *FilterGroup

AddFilter 向条件组添加过滤条件

func (*FilterGroup) AddFilters added in v0.2.0 

func (fg *FilterGroup) AddFilters(filters ...*Filter) *FilterGroup

AddFilters 向条件组批量添加过滤条件

func (*FilterGroup) AddGroup added in v0.2.0 

func (fg *FilterGroup) AddGroup(group *FilterGroup) *FilterGroup

AddGroup 向条件组添加嵌套条件组

func (*FilterGroup) Count added in v0.2.0 

func (fg *FilterGroup) Count() int

Count 返回条件总数（包括嵌套组）

func (*FilterGroup) IsEmpty added in v0.2.0 

func (fg *FilterGroup) IsEmpty() bool

IsEmpty 检查条件组是否为空

type FindOptions 

type FindOptions struct {
	Conditions []Condition
	Orders     []OrderBy
	Limit      int
	Offset     int
}

FindOptions 兼容旧API的查询选项结构

type FullFeaturedModel added in v0.2.0 

type FullFeaturedModel interface {
	ModelInterface
	VersionedModel
	SoftDeletableModel
	AuditableModel
	StatusModel
	RemarkableModel
}

FullFeaturedModel 全功能模型接口（组合所有特性）

type GormHandler added in v0.2.0 

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

GormHandler 标准 GORM 处理器实现

func (*GormHandler) GetDB added in v0.2.0 

func (h *GormHandler) GetDB() *gorm.DB

DB 返回底层 GORM 实例

func (*GormHandler) IsConnected added in v0.2.0 

func (h *GormHandler) IsConnected() bool

IsConnected 检查数据库连接是否有效

type Handler added in v0.2.0 

type Handler interface {
	// GetDB 返回 GORM 数据库实例
	GetDB() *gorm.DB

	// IsConnected 检查数据库连接是否有效
	IsConnected() bool
}

Handler 数据库处理器接口 所有 Repository 都基于这个接口工作，提供统一的数据库访问抽象

func MustNewGormHandler added in v0.2.0 

func MustNewGormHandler(db *gorm.DB) Handler

MustNewGormHandler 创建 GORM 处理器（panic 版本） 仅在确定 db 不为 nil 时使用，通常用于初始化阶段

func NewGormHandler added in v0.2.0 

func NewGormHandler(db *gorm.DB) (Handler, error)

NewGormHandler 创建 GORM 处理器 返回 Handler 接口和可能的错误

type LightModel added in v0.2.0 

type LightModel struct {
	ID        uint      `json:"id" gorm:"primaryKey;autoIncrement;comment:自增主键"`
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime;comment:创建时间"`
	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime;comment:更新时间"`
	Status    int8      `json:"status" gorm:"default:1;index;comment:状态(1:启用 0:禁用)"`
}

LightModel 轻量级模型（仅包含基本字段，无软删除、无版本控制）

func (*LightModel) Disable added in v0.2.0 

func (m *LightModel) Disable()

func (*LightModel) Enable added in v0.2.0 

func (m *LightModel) Enable()

func (*LightModel) GetID added in v0.2.0 

func (m *LightModel) GetID() uint

func (*LightModel) IsEnabled added in v0.2.0 

func (m *LightModel) IsEnabled() bool

func (*LightModel) IsNew added in v0.2.0 

func (m *LightModel) IsNew() bool

type MapAny 

type MapAny map[string]any

func (*MapAny) Scan 

func (m *MapAny) Scan(value interface{}) error

func (MapAny) Value 

func (m MapAny) Value() (driver.Value, error)

type MapString 

type MapString map[string]string

func (*MapString) Scan 

func (m *MapString) Scan(value interface{}) error

func (MapString) Value 

func (m MapString) Value() (driver.Value, error)

type ModelInterface 

type ModelInterface interface {
	IsNew() bool
}

ModelInterface 模型通用接口

type Operator added in v0.2.0 

type Operator string

Operator 操作符类型（统一定义，避免重复） 

const (
	OpEqual              Operator = "="  // 等于
	OpNotEqual           Operator = "!=" // 不等于
	OpGreaterThan        Operator = ">"  // 大于
	OpGreaterThanOrEqual Operator = ">=" // 大于等于
	OpLessThan           Operator = "<"  // 小于
	OpLessThanOrEqual    Operator = "<=" // 小于等于
)
const (
	OpLike    Operator = "LIKE"     // 模糊匹配
	OpNotLike Operator = "NOT LIKE" // 不匹配
)
const (
	OpIn      Operator = "IN"      // 包含
	OpNotIn   Operator = "NOT IN"  // 不包含
	OpBetween Operator = "BETWEEN" // 范围
)
const (
	OpIsNull    Operator = "IS NULL"     // 为空
	OpIsNotNull Operator = "IS NOT NULL" // 不为空
)
const (
	OpFindInSet Operator = "FIND_IN_SET" // MySQL FIND_IN_SET
	OpRegex     Operator = "REGEXP"      // 正则匹配
	OpNotRegex  Operator = "NOT REGEXP"  // 正则不匹配
)
const (
	LogicAnd Operator = "AND" // 逻辑与
	LogicOr  Operator = "OR"  // 逻辑或
	LogicNot Operator = "NOT" // 逻辑非
)

type Order added in v0.2.0 

type Order struct {
	Field     string
	Direction string // "ASC" or "DESC"
}

Order 排序条件

type OrderBy 

type OrderBy struct {
	Field     string
	Direction string
}

OrderBy 排序条件结构

type Pagination added in v0.2.0 

type Pagination struct {
	Page     int32 `json:"page"`      // 当前页码（从1开始）
	PageSize int32 `json:"page_size"` // 每页记录数
	Offset   int32 `json:"offset"`    // 数据库偏移量
	Limit    int32 `json:"limit"`     // 查询限制数
	Total    int64 `json:"total"`     // 总记录数
}

Pagination 分页元数据

func (*Pagination) GetLimit added in v0.2.0 

func (p *Pagination) GetLimit() int

GetLimit 获取查询限制数

func (*Pagination) GetOffset added in v0.2.0 

func (p *Pagination) GetOffset() int

GetOffset 计算数据库偏移量

func (*Pagination) GetTotalPages added in v0.2.0 

func (p *Pagination) GetTotalPages() int64

GetTotalPages 计算总页数

func (*Pagination) HasNextPage added in v0.2.0 

func (p *Pagination) HasNextPage() bool

HasNextPage 是否有下一页

func (*Pagination) HasPrevPage added in v0.2.0 

func (p *Pagination) HasPrevPage() bool

HasPrevPage 是否有上一页

type Query added in v0.2.0 

type Query struct {
	Filters     []*Filter    // 简单过滤条件
	FilterGroup *FilterGroup // 复合过滤条件组
	Orders      []Order      // 排序条件
	Pagination  *Pagination  // 分页信息
	LimitValue  *int         // 限制数量
	OffsetValue *int         // 偏移量
	Distinct    bool         // 是否去重
	GroupBy     []string     // 分组字段
	Having      []*Filter    // HAVING 条件
}

Query 查询条件

func NewQuery added in v0.2.0 

func NewQuery() *Query

NewQuery 创建查询条件

func (*Query) AddFilter added in v0.2.0 

func (q *Query) AddFilter(filter *Filter) *Query

AddFilter 添加过滤条件

func (*Query) AddFilters added in v0.2.0 

func (q *Query) AddFilters(filters ...*Filter) *Query

AddFilters 批量添加过滤条件

func (*Query) AddGroupBy added in v0.2.0 

func (q *Query) AddGroupBy(fields ...string) *Query

AddGroupBy 添加分组字段

func (*Query) AddHaving added in v0.2.0 

func (q *Query) AddHaving(filter *Filter) *Query

AddHaving 添加HAVING条件

func (*Query) AddOrder added in v0.2.0 

func (q *Query) AddOrder(field, direction string) *Query

AddOrder 添加排序条件

func (*Query) GetAllFilters added in v0.2.0 

func (q *Query) GetAllFilters() []*Filter

GetAllFilters 获取所有过滤条件（扁平化）

func (*Query) HasFilters added in v0.2.0 

func (q *Query) HasFilters() bool

HasFilters 检查是否有过滤条件

func (*Query) Limit added in v0.2.0 

func (q *Query) Limit(limit int) *Query

Limit 设置查询限制数量

func (*Query) Offset added in v0.2.0 

func (q *Query) Offset(offset int) *Query

Offset 设置查询偏移量

func (*Query) WithDistinct added in v0.2.0 

func (q *Query) WithDistinct(distinct bool) *Query

WithDistinct 设置去重查询

func (*Query) WithFilterGroup added in v0.2.0 

func (q *Query) WithFilterGroup(group *FilterGroup) *Query

WithFilterGroup 设置复合过滤条件组

func (*Query) WithPaging added in v0.2.0 

func (q *Query) WithPaging(page, pageSize int) *Query

WithPaging 设置分页条件

type QueryCondition added in v0.2.0 

type QueryCondition struct {
	Filters    []Filter
	Orders     []OrderBy
	Pagination *Pagination
}

type RemarkableModel added in v0.2.0 

type RemarkableModel interface {
	ModelInterface
	SetRemark(remark string)
}

RemarkableModel 支持备注的模型接口

type Repository added in v0.2.0 

type Repository[T any] interface {
	// 创建
	Create(ctx context.Context, entity *T) (*T, error)
	CreateBatch(ctx context.Context, entities ...*T) error

	// 读取
	Get(ctx context.Context, id interface{}) (*T, error)
	GetByFilter(ctx context.Context, filter *Filter) (*T, error)
	GetByFilters(ctx context.Context, filters ...*Filter) (*T, error)
	GetAll(ctx context.Context) ([]*T, error)
	First(ctx context.Context, filters ...*Filter) (*T, error)
	Last(ctx context.Context, filters ...*Filter) (*T, error)
	FindOne(ctx context.Context, filters ...*Filter) (*T, error)
	List(ctx context.Context, query *Query) ([]*T, error)
	ListWithPagination(ctx context.Context, query *Query, page *Pagination) ([]*T, *Pagination, error)

	// 更新
	Update(ctx context.Context, entity *T) (*T, error)
	UpdateBatch(ctx context.Context, entities ...*T) error
	UpdateByFilters(ctx context.Context, entity *T, filters ...*Filter) error
	UpdateFields(ctx context.Context, id interface{}, fields map[string]interface{}) error
	UpdateFieldsByFilters(ctx context.Context, fields map[string]interface{}, filters ...*Filter) error

	// 删除
	Delete(ctx context.Context, id interface{}) error
	DeleteBatch(ctx context.Context, ids ...interface{}) error
	DeleteByFilters(ctx context.Context, filters ...*Filter) error
	SoftDelete(ctx context.Context, id interface{}, field string, value interface{}) error
	SoftDeleteBatch(ctx context.Context, ids []interface{}, field string, value interface{}) error
	SoftDeleteByFilters(ctx context.Context, field string, value interface{}, filters ...*Filter) error
	Restore(ctx context.Context, id interface{}, field string, restoreValue interface{}) error
	RestoreBatch(ctx context.Context, ids []interface{}, field string, restoreValue interface{}) error

	// 事务
	Transaction(ctx context.Context, fn func(tx Transaction[T]) error) error

	// 工具方法
	Count(ctx context.Context, filters ...*Filter) (int64, error)
	Exists(ctx context.Context, filters ...*Filter) (bool, error)
	CountByField(ctx context.Context, field string) (map[interface{}]int64, error)
	Pluck(ctx context.Context, field string, filters ...*Filter) ([]interface{}, error)
	Distinct(ctx context.Context, field string, filters ...*Filter) ([]interface{}, error)
}

Repository 通用仓储接口

type RepositoryFactory added in v0.2.0 

type RepositoryFactory[T any] interface {
	// 创建仓储
	CreateRepository(table string) Repository[T]

	// 关闭工厂
	Close() error
}

RepositoryFactory 仓储工厂接口

type RepositoryOption added in v0.2.0 

type RepositoryOption[T any] func(*BaseRepository[T])

RepositoryOption 仓储配置选项

func WithBatchSize added in v0.2.0 

func WithBatchSize[T any](size int) RepositoryOption[T]

WithBatchSize 设置批处理大小

func WithDefaultOrder added in v0.2.0 

func WithDefaultOrder[T any](order string) RepositoryOption[T]

WithDefaultOrder 设置默认排序

func WithDefaultPreloads added in v0.2.0 

func WithDefaultPreloads[T any](preloads ...string) RepositoryOption[T]

WithDefaultPreloads 设置默认预加载关联

func WithLogger added in v0.2.0 

func WithLogger[T any](log gologger.ILogger) RepositoryOption[T]

WithLogger 设置日志记录器

func WithReadOnly added in v0.2.0 

func WithReadOnly[T any]() RepositoryOption[T]

WithReadOnly 设置为只读模式

func WithTimeout added in v0.2.0 

func WithTimeout[T any](seconds int) RepositoryOption[T]

WithTimeout 设置查询超时时间

type RepositoryWithSoftDelete added in v0.2.0 

type RepositoryWithSoftDelete[T any] struct {
	*BaseRepository[T]
}

RepositoryWithSoftDelete 带软删除功能的仓储

func NewRepositoryWithSoftDelete added in v0.2.0 

func NewRepositoryWithSoftDelete[T any](repo *BaseRepository[T]) *RepositoryWithSoftDelete[T]

NewRepositoryWithSoftDelete 创建带软删除功能的仓储

func (*RepositoryWithSoftDelete[T]) ListDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) ListDeleted(ctx context.Context, query *Query) ([]*T, error)

ListDeleted 查询已删除的记录（deleted_at 字段）

func (*RepositoryWithSoftDelete[T]) ListDeletedByIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) ListDeletedByIsDeleted(ctx context.Context, query *Query) ([]*T, error)

ListDeletedByIsDeleted 查询已删除的记录（is_deleted 字段）

func (*RepositoryWithSoftDelete[T]) ListNotDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) ListNotDeleted(ctx context.Context, query *Query) ([]*T, error)

ListNotDeleted 查询未删除的记录（deleted_at 字段）

func (*RepositoryWithSoftDelete[T]) ListNotDeletedByIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) ListNotDeletedByIsDeleted(ctx context.Context, query *Query) ([]*T, error)

ListNotDeletedByIsDeleted 查询未删除的记录（is_deleted 字段）

func (*RepositoryWithSoftDelete[T]) RestoreBatchWithDeletedAt added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) RestoreBatchWithDeletedAt(ctx context.Context, ids []interface{}) error

RestoreBatchWithDeletedAt 使用 deleted_at 字段批量恢复

func (*RepositoryWithSoftDelete[T]) RestoreBatchWithIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) RestoreBatchWithIsDeleted(ctx context.Context, ids []interface{}) error

RestoreBatchWithIsDeleted 使用 is_deleted 字段批量恢复

func (*RepositoryWithSoftDelete[T]) RestoreWithDeletedAt added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) RestoreWithDeletedAt(ctx context.Context, id interface{}) error

RestoreWithDeletedAt 使用 deleted_at 字段恢复

func (*RepositoryWithSoftDelete[T]) RestoreWithIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) RestoreWithIsDeleted(ctx context.Context, id interface{}) error

RestoreWithIsDeleted 使用 is_deleted 字段恢复

func (*RepositoryWithSoftDelete[T]) SoftDeleteBatchWithDeletedAt added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteBatchWithDeletedAt(ctx context.Context, ids []interface{}) error

SoftDeleteBatchWithDeletedAt 使用 deleted_at 字段批量软删除

func (*RepositoryWithSoftDelete[T]) SoftDeleteBatchWithIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteBatchWithIsDeleted(ctx context.Context, ids []interface{}) error

SoftDeleteBatchWithIsDeleted 使用 is_deleted 字段批量软删除

func (*RepositoryWithSoftDelete[T]) SoftDeleteByFiltersWithDeletedAt added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteByFiltersWithDeletedAt(ctx context.Context, filters ...*Filter) error

SoftDeleteByFiltersWithDeletedAt 使用 deleted_at 字段按条件软删除

func (*RepositoryWithSoftDelete[T]) SoftDeleteByFiltersWithIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteByFiltersWithIsDeleted(ctx context.Context, filters ...*Filter) error

SoftDeleteByFiltersWithIsDeleted 使用 is_deleted 字段按条件软删除

func (*RepositoryWithSoftDelete[T]) SoftDeleteWithDeletedAt added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteWithDeletedAt(ctx context.Context, id interface{}) error

SoftDeleteWithDeletedAt 使用 deleted_at 字段软删除

func (*RepositoryWithSoftDelete[T]) SoftDeleteWithIsDeleted added in v0.2.0 

func (r *RepositoryWithSoftDelete[T]) SoftDeleteWithIsDeleted(ctx context.Context, id interface{}) error

SoftDeleteWithIsDeleted 使用 is_deleted 字段软删除

type SimpleModel added in v0.2.0 

type SimpleModel struct {
	ID        uint      `json:"id" gorm:"primaryKey;autoIncrement;comment:自增主键"`
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime;comment:创建时间"`
	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime;comment:更新时间"`
}

SimpleModel 简化模型（不带软删除）

func (*SimpleModel) GetID added in v0.2.0 

func (m *SimpleModel) GetID() uint

func (*SimpleModel) IsNew added in v0.2.0 

func (m *SimpleModel) IsNew() bool

type SoftDeletableModel added in v0.2.0 

type SoftDeletableModel interface {
	ModelInterface
	IsDeleted() bool
}

SoftDeletableModel 支持软删除的模型接口

type SoftDeleteHelper added in v0.2.0 

type SoftDeleteHelper[T any] interface {
	// 使用 deleted_at 字段的软删除
	SoftDeleteWithDeletedAt(ctx context.Context, id interface{}) error
	SoftDeleteBatchWithDeletedAt(ctx context.Context, ids []interface{}) error
	SoftDeleteByFiltersWithDeletedAt(ctx context.Context, filters ...*Filter) error
	RestoreWithDeletedAt(ctx context.Context, id interface{}) error
	RestoreBatchWithDeletedAt(ctx context.Context, ids []interface{}) error

	// 使用 is_deleted 字段的软删除
	SoftDeleteWithIsDeleted(ctx context.Context, id interface{}) error
	SoftDeleteBatchWithIsDeleted(ctx context.Context, ids []interface{}) error
	SoftDeleteByFiltersWithIsDeleted(ctx context.Context, filters ...*Filter) error
	RestoreWithIsDeleted(ctx context.Context, id interface{}) error
	RestoreBatchWithIsDeleted(ctx context.Context, ids []interface{}) error
}

SoftDeleteHelper 软删除辅助接口

type StatusModel added in v0.2.0 

type StatusModel interface {
	ModelInterface
	Enable()
	Disable()
	IsEnabled() bool
}

StatusModel 支持状态管理的模型接口

type StringSlice 

type StringSlice []string

func (*StringSlice) Scan 

func (s *StringSlice) Scan(value interface{}) error

func (StringSlice) Value 

func (s StringSlice) Value() (driver.Value, error)

type TimestampModel added in v0.2.0 

type TimestampModel struct {
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime;comment:创建时间"`
	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime;comment:更新时间"`
}

TimestampModel 仅包含时间戳的模型

type Transaction added in v0.2.0 

type Transaction[T any] interface {
	// 执行事务内的操作
	Create(ctx context.Context, entity *T) error
	CreateBatch(ctx context.Context, entities ...*T) error
	Update(ctx context.Context, entity *T) error
	UpdateBatch(ctx context.Context, entities ...*T) error
	Delete(ctx context.Context, entity *T) error
	DeleteBatch(ctx context.Context, entities ...*T) error
}

Transaction 事务接口

type UUIDModel added in v0.2.0 

type UUIDModel struct {
	ID        string         `json:"id" gorm:"primaryKey;type:char(36);comment:UUID主键"`
	Version   int            `json:"version" gorm:"default:1;comment:版本号"`
	CreatedAt time.Time      `json:"created_at" gorm:"autoCreateTime;comment:创建时间"`
	UpdatedAt time.Time      `json:"updated_at" gorm:"autoUpdateTime;comment:更新时间"`
	DeletedAt gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index;comment:删除时间"`
}

UUIDModel UUID作为主键的模型

func (*UUIDModel) BeforeUpdate added in v0.2.0 

func (m *UUIDModel) BeforeUpdate(tx *gorm.DB) error

func (*UUIDModel) GetID added in v0.2.0 

func (m *UUIDModel) GetID() string

func (*UUIDModel) IsNew added in v0.2.0 

func (m *UUIDModel) IsNew() bool

type VersionedModel added in v0.2.0 

type VersionedModel interface {
	ModelInterface
	GetVersion() int
}

VersionedModel 支持版本控制的模型接口

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.