data

README

data

oekit 数据访问门面——复刻 ekit 单体库 data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包，一个 import 前缀直达

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

安装

go get github.com/oekit/data@v0.5.0

这个仓库做什么

data 是纯 re-export 门面：复刻 ekit 单体库 data/ 的能力面，类型为泛型 type alias（与源包完全同一类型，双向赋值互通），实现分别住在各子仓——

门面子包	能力	实现
cache	缓存接口（Cache/CacheAside/SourceFunc）+ LocalCache/SingleFlightCache + 键构造 + Checker	pkg cache/
rediscache	Redis 分布式缓存（CacheAside 的 Redis 后端）	redisx cache/
crud	框架无关 CRUD Service/仓储	gormx crud/
distlock	分布式锁（RedisLocker/WithLock/优雅降级）	redisx distlock/
gormx	SQL/GORM 增强（Open/审计/OTel 插件/分页/单例仓储）	gormx
redisx	Redis 客户端封装（String/Hash/Set/ZSet/Bloom/Batch/PubSub）	redisx
timertask	分片定时任务（FNV-1a 分片、心跳续约）	timertask
cachetest	CacheAside 实现契约测试套件（8 场景）	pkg cache/cachetest/

缓存接口与契约套件已下沉 pkg 的 cache 子包（v0.4.0）——Redis 等后端实现依赖接口，接口必须位于门面下游。

快速使用

import (
    "github.com/oekit/data/cache"
    "github.com/oekit/data/rediscache"
)

// 本地缓存（L1）
local := cache.NewLocalCache(cache.LocalConfig[HotConfig]{
    TTL: 30 * time.Second,
    Source: loadHotConfig, // 未命中回源（Cache-Aside）
})

// Redis 缓存（L2）——与本地缓存实现同一 CacheAside 接口
remote := rediscache.NewRedisCache(redisCli, rediscache.RedisConfig[HotConfig]{
    Prefix: "hot:", TTL: 24 * time.Hour, Source: loadHotConfig,
})
cfg, err := local.GetOrLoad(ctx, "tenant:acme")

边界

• 门面不含实现：本仓只做命名空间聚合（type alias + var 转发）；源仓新增 导出符号时本仓壳需同步（跟版税由门面化决策承担，dependabot 只升 pin 不补壳）
• 只用单一能力时直接依赖对应子仓（依赖面最小）：gormx/redisx/timertask/pkg
• 只需本地缓存的轻量场景可直接依赖 pkg 的 cache 子包（不经门面）
• 需要"一键全家桶依赖聚合"（不 import 门面命名空间）的旧行为已废弃： github.com/oekit/data/all 已 retract（v0.5.0 起由本门面取代）

规划

• 两级缓存装饰器（Local + Redis 读穿写透，原 all/ 模块的 TwoLevelCache）： 等真实需求在门面子包立项（可实现为对两个 CacheAside 的组合装饰）
• 两级缓存失效广播（Redis pubsub 主动失效 L1）：单独立项

Documentation

Overview

Package data 是 oekit 数据访问门面——复刻 ekit 单体库 data/ 的能力面： 缓存、CRUD、分布式锁、GORM、Redis、定时任务，一个 import 前缀直达。

本仓是纯 re-export 门面：类型为泛型 type alias（与源包完全同一类型， 双向赋值互通），实现分别住在 pkg/cache 与 gormx/redisx/timertask 各子仓； 门面只做命名空间聚合，不持有实现。只使用单一能力时可直接依赖对应子仓 （依赖面最小）；全家桶场景 go get github.com/oekit/data 即可。

子包地图（目标 ← 实现仓）：

cache/      ← pkg/cache            缓存接口 + LocalCache/SingleFlightCache + 键构造 + Checker
rediscache/ ← redisx/cache         Redis 分布式缓存（CacheAside 的 Redis 后端）
crud/       ← gormx/crud           框架无关 CRUD Service/仓储
distlock/   ← redisx/distlock      分布式锁
gormx/      ← gormx                SQL/GORM 增强
redisx/     ← redisx               Redis 客户端封装
timertask/  ← timertask            分片定时任务
cachetest/  ← pkg/cache/cachetest  缓存实现契约测试套件

门面跟版约定：源仓新增导出符号时本仓壳需同步（dependabot 只升 pin 不补 壳）；接口与契约的实现演进以源仓 README 为准。