Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
Open more actions menu

Repository files navigation

go-crud · 通用数据访问层工具库

一套泛型 Repository 接口,统一驾驭 8 种数据存储引擎

让数据操作不再是重复劳动,让每一行代码都聚焦业务价值

中文 · English · 日本語

Go Version License PRs Welcome Go Reference


项目亮点

  • 统一数据访问层:一套泛型 Repository 接口,覆盖 GORM、Ent、MongoDB、ClickHouse、Apache Doris、Elasticsearch、OpenSearch、InfluxDB 八大数据引擎,告别重复 Boilerplate
  • 三种分页策略:Offset / Page / Token 三种分页模式,从传统 Web 分页到无限滚动,全场景覆盖
  • 结构化过滤引擎:29+ 种操作符,支持 AND/OR 多层嵌套,同时兼容 JSON 与 Google AIP 两种过滤语法,参数化查询杜绝 SQL 注入
  • Protocol Buffers 契约:基于 Protobuf 定义标准化的分页、过滤、排序协议,天然适配 gRPC 微服务架构,接口即文档
  • Redis 缓存层:内置 Cache-Aside 模式与 SingleFlight 防击穿机制,一行代码开启缓存,保护后端数据库
  • 审计日志:统一的 Auditor 接口,Context 注入、全链路操作追溯与数据变更记录
  • 数据权限控制:Viewer 上下文支持多租户隔离、五级数据范围(SELF / UNIT / USER / ALL / NONE),精细化的行级权限
  • 完全类型安全:基于 Go 1.24+ 泛型,DTO ↔ Entity 双向映射,编译时即可捕获类型错误
  • Upsert 支持:GORM / ClickHouse / Doris 原生支持 Upsert(INSERT ON CONFLICT),冲突自动更新
  • 树形查询:Ent 模块内置树形结构组装,自动根据 ParentID 构建层级关系

支持的数据引擎

引擎 类型 状态 适用场景
GORM 关系型 ORM MySQL、PostgreSQL、SQLite、SQL Server 等主流关系型数据库
Ent 关系型 ORM (Code Gen) MySQL、PostgreSQL、SQLite,编译时类型安全,Facebook 开源
MongoDB 文档数据库 半结构化数据、灵活 Schema、内容管理
ClickHouse 列式 OLAP 海量日志分析、指标聚合、用户行为分析、实时数仓
Apache Doris 列式 OLAP 实时 BI 报表、交互式分析、Stream Load 高速写入
Elasticsearch 搜索引擎 全文检索、日志分析、高亮搜索、聚合分析
OpenSearch 搜索引擎 Elasticsearch 开源替代、向量检索、安全分析
InfluxDB 时序数据库 IoT 监控、DevOps 指标、时序数据分析
Cassandra 宽列数据库 🚧 高可用写入、跨数据中心复制(开发中)

系统架构

graph TB
    subgraph API["API 契约层"]
        Proto["Protobuf 定义<br/>PagingRequest · PaginationRequest<br/>FilterExpr · Sorting · FieldMask"]
    end

    subgraph Infra["基础设施层"]
        Pagination["Pagination<br/>分页策略 · 过滤引擎 · 排序转换"]
        Cache["Cache<br/>Redis Cache-Aside · SingleFlight 防击穿"]
        Audit["Audit<br/>审计日志 · Context 注入 · 变更追踪"]
        Viewer["Viewer<br/>身份上下文 · 权限检查 · 五级数据范围"]
    end

    subgraph DAL["数据访问层"]
        GORM["GORM"]
        ENT["Ent"]
        Mongo["MongoDB"]
        CH["ClickHouse"]
        Doris["Apache Doris"]
        ES["Elasticsearch"]
        OS["OpenSearch"]
        Influx["InfluxDB"]
    end

    API --> Pagination
    Pagination --> DAL
    Cache --> DAL
    Audit --> DAL
    Viewer --> DAL
Loading

项目结构

go-crud/
├── api/                          # Protocol Buffers 契约定义与生成代码
│   ├── protos/pagination/v1/     # .proto 源文件 (PagingRequest / FilterExpr / Sorting)
│   └── gen/go/pagination/v1/     # buf 生成的 Go 代码
├── pagination/                   # 分页 · 过滤 · 排序核心工具包
│   ├── paginator/                # 分页器实现 (Page / Offset / Token)
│   ├── filter/                   # 过滤器转换器 (JSON 语法 / Google AIP 语法)
│   └── sorting/                  # 排序格式转换器
├── cache/                        # Redis 缓存层 (Cache-Aside + SingleFlight 防击穿)
├── audit/                        # 统一审计日志接口 (Auditor · Entry · Context)
├── viewer/                       # 查看者上下文 (身份 · 权限 · 五级数据范围)
├── gorm/                         # GORM 数据访问层 (CRUD · Upsert · 缓存 · 软删除)
├── entgo/                        # Ent 数据访问层 (CRUD · 树形查询 · 缓存 · 事务)
├── mongodb/                      # MongoDB 数据访问层 (CRUD · QueryBuilder)
├── clickhouse/                   # ClickHouse 数据访问层 (CRUD · 批量写入 · Upsert)
├── doris/                        # Apache Doris 数据访问层 (CRUD · Stream Load · SQL 查询)
├── elasticsearch/                # Elasticsearch 客户端与工具
├── opensearch/                   # OpenSearch 客户端与工具
├── influxdb/                     # InfluxDB 数据访问层 (Flux 查询)
└── cassandra/                    # Cassandra 数据访问层 (开发中)

核心功能

数据访问层

每个数据访问层模块均提供统一的泛型 Repository 封装,基于 mapper.CopierMapper[DTO, ENTITY] 实现 DTO ↔ Entity 双向自动映射:

能力 GORM Ent MongoDB ClickHouse Doris ES / OS InfluxDB
Create / Get / Update / Delete
分页查询 (Page / Offset / Token)
结构化过滤 (29+ 操作符)
多字段排序
字段选择 (FieldMask)
批量写入 (BatchCreate)
Upsert (INSERT ON CONFLICT)
软删除 (SoftDelete)
计数 (Count / CountWithOptions)
存在性检查 (Exists)
Redis 缓存
树形查询
事务支持
Stream Load
SQL 原生查询

过滤操作符

基于 Protobuf 定义的结构化过滤引擎,支持 29+ 种操作符:

分类 操作符
基本比较 EQ NEQ GT GTE LT LTE
模糊匹配 LIKE ILIKE NOT_LIKE
集合操作 IN NIN
空值判断 IS_NULL IS_NOT_NULL
范围与正则 BETWEEN REGEXP IREGEXP
字符串操作 CONTAINS STARTS_WITH ENDS_WITH ICONTAINS ISTARTS_WITH IENDS_WITH
JSON / 数组 JSON_CONTAINS ARRAY_CONTAINS EXISTS
全文检索 SEARCH EXACT IEXACT

支持 AND / OR 多层嵌套组合,通过 FilterExpr 表达任意复杂的查询逻辑。

分页策略

模式 适用场景 说明
Page-Based 传统 Web 分页 页码 + 页大小,适合有总页数展示的列表
Offset-Based API 跳页查询 偏移量 + 限制数,适合灵活跳页
Token-Based 无限滚动 / 流式加载 基于游标的分页,性能稳定不偏移

缓存层

能力 说明
Cache-Aside 模式 读时回填,写时失效,保证数据一致性
SingleFlight 防击穿 并发请求自动合并,保护后端数据库
单条 / 列表独立 TTL 单条缓存与列表缓存支持不同的过期策略
指标监控 内置缓存命中率、延迟等指标采集

审计日志

能力 说明
Auditor 接口 统一的审计日志记录接口,支持同步写入与异步缓冲
Context 注入 通过 Context 透传审计信息,无侵入式集成
Entry 数据模型 标准化的审计记录结构,包含操作者、操作类型、变更内容
Noop 实现 内置空实现,无审计需求时零开销

数据权限控制

范围级别 说明
SELF 仅限本人创建 / 拥有的数据
UNIT 组织维度隔离,支持本部门及下级部门
USER 指定的用户列表
ALL 全量放行,不注入过滤条件
NONE 禁止任何数据访问

技术栈

层级 技术 说明
语言 Go 1.24+ 高性能编译型语言,泛型支持
ORM GORM / Ent 主流关系型 ORM,按需选用
文档数据库 MongoDB NoSQL 文档存储
OLAP 引擎 ClickHouse / Apache Doris 列式存储,极致分析性能
搜索引擎 Elasticsearch / OpenSearch 全文检索与数据分析
时序数据库 InfluxDB 时序数据采集与分析
缓存 Redis 内存数据库,防击穿保护
DTO 映射 go-utils/mapper 泛型 CopierMapper,双向自动映射
API 定义 Protobuf + buf.build 接口契约优先,跨语言支持
日志 go-kratos/log Kratos 框架日志集成
可观测性 OpenTelemetry 分布式追踪与指标(GORM / Ent)

快速开始

安装

# 按需安装所需模块

go get github.com/tx7do/go-crud/gorm         # GORM
go get github.com/tx7do/go-crud/entgo         # Ent
go get github.com/tx7do/go-crud/mongodb       # MongoDB
go get github.com/tx7do/go-crud/clickhouse    # ClickHouse
go get github.com/tx7do/go-crud/doris         # Apache Doris
go get github.com/tx7do/go-crud/elasticsearch # Elasticsearch
go get github.com/tx7do/go-crud/opensearch    # OpenSearch
go get github.com/tx7do/go-crud/influxdb      # InfluxDB

示例:GORM Repository

package main

import (
    "context"
    "fmt"

    "github.com/tx7do/go-crud/gorm"
    "github.com/tx7do/go-utils/mapper"
    paginationV1 "github.com/tx7do/go-crud/api/gen/go/pagination/v1"
)

// 1. 定义 Entity(数据库表映射)
type UserEntity struct {
    ID    uint64 `gorm:"primaryKey;autoIncrement"
    Name  string `gorm:"column:name;type:varchar(100)"
    Email string `gorm:"column:email;type:varchar(200)"
}

func (UserEntity) TableName() string { return "users" }

// 2. 创建 Repository
func main() {
    ctx := context.Background()

    m := mapper.NewCopierMapper[User, UserEntity]()
    repo := gorm.NewRepository[User, UserEntity](m)

    // 创建记录
    user, _ := repo.Create(ctx, db, &User{Name: "John", Email: "john@example.com"}, nil)

    // 分页查询
    page := uint32(1)
    pageSize := uint32(10)
    result, _ := repo.ListWithPaging(ctx, db, &paginationV1.PagingRequest{
        Page:     &page,
        PageSize: &pageSize,
    })
    fmt.Printf("Total: %d, Items: %d\n", result.Total, len(result.Items))
}

示例:ClickHouse Repository

package main

import (
    "github.com/tx7do/go-crud/clickhouse"
    "github.com/tx7do/go-utils/mapper"
)

func main() {
    // 创建 Client
    client, _ := clickhouse.NewClient(
        clickhouse.WithDsn("clickhouse://default:123456@localhost:9000/my_database"),
    )

    // 创建 Repository
    m := mapper.NewCopierMapper[Event, EventEntity]()
    repo := clickhouse.NewRepository[Event, EventEntity](client, m, "events", logger)

    // 批量写入
    events := []*Event{{...}, {...}}
    repo.BatchCreate(ctx, events, nil)

    // 分页查询
    result, _ := repo.ListWithPaging(ctx, req)
}

示例:结构化过滤

// 使用 Protobuf FilterExpr 构建复杂查询
page := uint32(1)
pageSize := uint32(10)
result, _ := repo.ListWithPaging(ctx, db, &paginationV1.PagingRequest{
    Page:     &page,
    PageSize: &pageSize,
    FilteringType: &paginationV1.PagingRequest_FilterExpr{
        FilterExpr: &paginationV1.FilterExpr{
            Type: paginationV1.ExprType_AND,
            Conditions: []*paginationV1.FilterCondition{
                {Field: "status", Op: paginationV1.Operator_EQ, Value: &paginationV1.FilterCondition_Value{Value: "active"}},
                {Field: "age", Op: paginationV1.Operator_GTE, Value: &paginationV1.FilterCondition_Value{Value: "18"}},
            },
        },
    },
})

与同类项目的区别

特性 go-crud 纯手写 Repository 其他 CRUD 库
多引擎统一 API ✅ 8 种引擎 ❌ 每种手写 ❌ 通常只支持一种
泛型类型安全 ✅ DTO ↔ Entity 双向映射 ⚠️ 视实现而定 ⚠️ 部分支持
Protocol Buffers 契约 ✅ 标准化接口定义
结构化过滤引擎 ✅ 29+ 操作符 + AND/OR 嵌套 ⚠️ 基础过滤
三种分页策略 ✅ Page / Offset / Token
内置缓存 ✅ Cache-Aside + 防击穿
审计日志 ✅ 全链路追踪
数据权限控制 ✅ 五级数据范围
Upsert 支持 ✅ INSERT ON CONFLICT ⚠️ 手写
OLAP 引擎支持 ✅ ClickHouse + Doris
搜索引擎支持 ✅ Elasticsearch + OpenSearch
时序数据库支持 ✅ InfluxDB

贡献

欢迎提交 Issue 或 Pull Request 参与项目改进。贡献前请确保:

  • 代码通过 go vet 检查
  • 新功能有对应的单元测试
  • 遵循项目现有的代码规范

许可证

本项目基于 MIT 许可证 开源,允许自由使用、修改和分发。

About

Generic data access layer toolkit for Go. Powered by Protobuf contracts, supporting structured filtering, Redis caching, and 8 database storage engines.

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Morty Proxy This is a proxified and sanitized view of the page, visit original site.