Help us shape the future of Go! Take the 2026 Go Developer Survey

redisx

package module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: MIT Imports: 6 Imported by: 3

README

redisx

Redis 全家桶——客户端封装/分布式缓存/分布式锁与信号量/分布式限流

⚠️ 原名 oekit/redis，v0.4.0 起更名 oekit/redisx（消除与 go-redis 的包名撞车与 /redis/redis 口吃）；旧路径经 GitHub 重定向可拉取 ≤ v0.3.1

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

安装

go get github.com/oekit/redisx@v0.9.0

这个仓库做什么

redisx 是 Redis 全家桶：客户端封装（根包）、分布式缓存后端（cache）、 分布式锁与分布式信号量（distlock）、分布式限流（ratelimit）。

组成

包 做什么
根包 Redis 客户端封装（NewClientFromConfig，原 redisx 子包上收）
cache pkg 缓存接口（pkg/cache）的 Redis 后端实现（原 redis/ 子包；行为契约由 pkg 的 cachetest 套件机器验证）
distlock 分布式锁（TryLock/Lock + 可选自动续期 WithAutoRenew，TryLock 与 Lock 对称；手动续期 Renew Lua CAS；无 Redis 优雅降级）+ 分布式信号量 Semaphore（ZSET 槽位 + slotTTL 过期自愈，跨实例共享并发上限，崩溃持有者槽位自动回收）+ 分布式防爆破锁 Lockout（v0.9.0，redisx#6：滑窗失败计数达阈值 → 锁定 Penalty 时长——惩罚只按首次触发计算不延长（SET PX NX）→ 成功 Reset 清零；Fail/Check(剩余时长)/Reset 全 Lua 原子，窗口 ZSET PEXPIRE 空闲消亡；与 concurrency/ratelimit.Lockout 成对——多实例共享计数防「失败打散绕过进程内锁」）
ratelimit 分布式限流——固定窗口 + 令牌桶（Lua 三态 + 故障本地兜底，存储抽象收 go-redis v9 的 redis.Scripter 接口）

快速使用

import "github.com/oekit/redisx"

cli, err := redisx.NewClientFromConfig(ctx, redisx.RedisConfig{ /* Addr/DB/Pool */ })

tracing 接入（显式装饰器，零注入默认）：

import redisotel "github.com/oekit/tracing/redisotel"

_ = redisotel.InstrumentTracing(cli.Client()) // 无 SDK 时 noop

边界

  • 缓存接口定义在 pkg 的 cache 子包；本仓 cache 是其 Redis 后端 （import github.com/oekit/redisx/cache），行为契约由 data 的 cachetest 套件机器验证

规划

  • 新缓存后端（etcd/consul 等）落在 data 侧按其 cachetest 模板接入，本仓仅在需要时提供传输层封装
  • 两级缓存（Local + Redis 组合，含失效广播）：单独立项

矩阵总览（24 活跃模块，自动生成）

模块 内容 矩阵内依赖
pkg 微工具集 20 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap/singleflighttest；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient；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 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口 pkg
logx 统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 —
core 应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、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）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 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（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 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 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8） concurrency、core、logx、metrics、registry、tracing
network 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 concurrency、logx、tracing
timertask 分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效） concurrency、logx
middleware Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶） 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 应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；Metrics/Tracing 在嵌套模块 bootstrap/obs concurrency、logx
hertz Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整/WithReadyAddr 探活地址），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接 bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx 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 redisx 提供 Redis 客户端封装。

所有 enjoydream 后端服务共享此包，统一封装：key 前缀管理。 零可观测性副作用：构造不注入任何 tracing；需要 OpenTelemetry span 时 用 github.com/oekit/tracing/redisotel 装饰器显式接入。

核心特性

  • key 前缀自动添加（prefix:key 格式）
  • 支持 redis.UniversalClient（兼容单机、集群、哨兵模式）
  • 提供 Client() 方法获取原生客户端（用于 distlock、tracing 接入等场景）

快速接入

从地址创建： 

client, err := redisx.NewClientFromAddr("localhost:6379", "", 0,
    redisx.WithPrefix("myservice"),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

从配置创建（支持集群）： 

opt := &redis.UniversalOptions{
    Addrs:    []string{"redis-1:6379", "redis-2:6379"},
    Password: "password",
    DB:       0,
}
client, err := redisx.NewClient(opt, redisx.WithPrefix("myservice"))

Key 前缀

所有操作的 key 会自动添加 "prefix:" 前缀： 

client.Set(ctx, "user:123", value, 0)
// 实际存储的 key 为 "myservice:user:123"

原生客户端

需要原生 redis.UniversalClient 时（如 distlock、cache、tracing 接入等包）： 

locker := distlock.NewRedisLocker(client.Client(), distlock.WithPrefix("myservice"))
_ = redisotel.InstrumentTracing(client.Client()) // github.com/oekit/tracing/redisotel

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Batch 

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

Batch 封装 Redis Pipeline 批量操作。 将多个命令打包发送，减少网络往返次数。 与直接使用 Pipeline 不同，Batch 自动处理 key 前缀转换。

func (*Batch) Del 

func (b *Batch) Del(ctx context.Context, keys ...string)

Del 批量删除。

func (*Batch) Discard 

func (b *Batch) Discard()

Discard 丢弃批量操作中的所有命令。

func (*Batch) Exec 

func (b *Batch) Exec(ctx context.Context) ([]redis.Cmder, error)

Exec 执行所有批量操作，返回所有命令的结果。

func (*Batch) Exists 

func (b *Batch) Exists(ctx context.Context, keys ...string) *redis.IntCmd

Exists 批量检查 key 存在。

func (*Batch) Expire 

func (b *Batch) Expire(ctx context.Context, key string, ttl time.Duration)

Expire 批量设置过期时间。

func (*Batch) Get 

func (b *Batch) Get(ctx context.Context, key string) *redis.StringCmd

Get 批量 Get 操作。

func (*Batch) HGet 

func (b *Batch) HGet(ctx context.Context, key, field string) *redis.StringCmd

HGet 批量 Hash Get。

func (*Batch) HSet 

func (b *Batch) HSet(ctx context.Context, key string, values ...any)

HSet 批量 Hash Set。

func (*Batch) Incr 

func (b *Batch) Incr(ctx context.Context, key string) *redis.IntCmd

Incr 批量自增。

func (*Batch) IncrBy 

func (b *Batch) IncrBy(ctx context.Context, key string, value int64) *redis.IntCmd

IncrBy 批量按增量自增。

func (*Batch) Len 

func (b *Batch) Len() int

Len 返回批量操作中待执行的命令数量。

func (*Batch) Set 

func (b *Batch) Set(ctx context.Context, key string, value any, ttl time.Duration)

Set 批量 Set 操作。

type BloomFilter 

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

BloomFilter 是基于 RedisBloom 的布隆过滤器封装。 需要 Redis 服务器安装 RedisBloom 模块。

func (*BloomFilter) Add 

func (bf *BloomFilter) Add(ctx context.Context, item string) (bool, error)

Add 向布隆过滤器添加元素。 返回 true 表示元素可能是新添加的，false 表示元素已存在。

func (*BloomFilter) Exists 

func (bf *BloomFilter) Exists(ctx context.Context, item string) (bool, error)

Exists 检查元素是否可能存在。 返回 true 表示元素可能存在（有误判率），false 表示元素一定不存在。

func (*BloomFilter) Info 

func (bf *BloomFilter) Info(ctx context.Context) (map[string]any, error)

Info 获取布隆过滤器信息。 BF.INFO 返回交替的 key-value 数组，本方法将其解析为 map。

func (*BloomFilter) MAdd 

func (bf *BloomFilter) MAdd(ctx context.Context, items ...string) ([]bool, error)

MAdd 批量添加元素。 返回每个元素的结果：true 表示新添加，false 表示已存在。

func (*BloomFilter) MExists 

func (bf *BloomFilter) MExists(ctx context.Context, items ...string) ([]bool, error)

MExists 批量检查元素是否存在。

type Client 

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

Client 是带 key 前缀的 Redis 客户端封装。

func NewClient 

func NewClient(opt *redis.UniversalOptions, opts ...RedisClientOptionFunc) (*Client, error)

NewClient 从 UniversalOptions 创建 Redis 客户端。

零可观测性副作用：不自动注入任何 tracing。需要 OpenTelemetry span 时 用装饰器显式接入（无 SDK 时 noop）： 

c, _ := redisx.NewClient(opt)
_ = redisotel.InstrumentTracing(c.Client()) // github.com/oekit/tracing/redisotel

func NewClientFromAddr 

func NewClientFromAddr(addr, password string, db int, opts ...RedisClientOptionFunc) (*Client, error)

NewClientFromAddr 从地址字符串创建 Redis 客户端（便捷方法）。

func NewClientFromConfig 

func NewClientFromConfig(ctx context.Context, cfg RedisConfig) (*Client, error)

NewClientFromConfig 从配置创建 Redis 客户端（构造后立即 Ping 验证连通性）。

用法： 

client, err := redis.NewClientFromConfig(ctx, redis.RedisConfig{
    Host: cfg.Redis.Host, Port: cfg.Redis.Port,
    Password: cfg.Redis.Password, DB: cfg.Redis.DB,
})

func (*Client) Client 

func (c *Client) Client() redis.UniversalClient

Client 返回底层 redis.UniversalClient（用于 distlock 等需要原生客户端的场景）。

func (*Client) Close 

func (c *Client) Close() error

Close 关闭底层 Redis 连接。

func (*Client) Decr 

func (c *Client) Decr(ctx context.Context, key string) *redis.IntCmd

Decr 将 key 的值减 1。

func (*Client) DecrBy 

func (c *Client) DecrBy(ctx context.Context, key string, value int64) *redis.IntCmd

DecrBy 将 key 的值减少指定减量。

func (*Client) Del 

func (c *Client) Del(ctx context.Context, keys ...string) *redis.IntCmd

Del 删除一个或多个 key。

func (*Client) Eval 

func (c *Client) Eval(ctx context.Context, script string, keys []string, args ...any) *redis.Cmd

Eval 执行 Lua 脚本。

func (*Client) EvalRO 

func (c *Client) EvalRO(ctx context.Context, script string, keys []string, args ...any) *redis.Cmd

EvalRO 执行只读 Lua 脚本。

func (*Client) EvalSha 

func (c *Client) EvalSha(ctx context.Context, sha1 string, keys []string, args ...any) *redis.Cmd

EvalSha 通过 SHA1 执行已缓存的 Lua 脚本。

func (*Client) EvalShaRO 

func (c *Client) EvalShaRO(ctx context.Context, sha1 string, keys []string, args ...any) *redis.Cmd

EvalShaRO 通过 SHA1 执行已缓存的只读 Lua 脚本。

func (*Client) Exists 

func (c *Client) Exists(ctx context.Context, keys ...string) *redis.IntCmd

Exists 检查 key 是否存在。

func (*Client) Expire 

func (c *Client) Expire(ctx context.Context, key string, expiration time.Duration) *redis.BoolCmd

Expire 设置 key 的过期时间。

func (*Client) Get 

func (c *Client) Get(ctx context.Context, key string) *redis.StringCmd

Get 获取 key 的值。

func (*Client) HDel 

func (c *Client) HDel(ctx context.Context, key string, fields ...string) *redis.IntCmd

HDel 删除 hash 中的一个或多个字段。

func (*Client) HGet 

func (c *Client) HGet(ctx context.Context, key, field string) *redis.StringCmd

HGet 获取 hash 中指定字段的值。

func (*Client) HGetAll 

func (c *Client) HGetAll(ctx context.Context, key string) *redis.MapStringStringCmd

HGetAll 获取 hash 中所有字段和值。

func (*Client) HSet 

func (c *Client) HSet(ctx context.Context, key string, values ...any) *redis.IntCmd

HSet 设置 hash 中的一个或多个字段。

func (*Client) Incr 

func (c *Client) Incr(ctx context.Context, key string) *redis.IntCmd

Incr 将 key 的值加 1。

func (*Client) IncrBy 

func (c *Client) IncrBy(ctx context.Context, key string, value int64) *redis.IntCmd

IncrBy 将 key 的值增加指定增量。

func (*Client) LLen 

func (c *Client) LLen(ctx context.Context, key string) *redis.IntCmd

LLen 获取列表长度。

func (*Client) LPop 

func (c *Client) LPop(ctx context.Context, key string) *redis.StringCmd

LPop 移除并返回列表头部元素。

func (*Client) LPush 

func (c *Client) LPush(ctx context.Context, key string, values ...any) *redis.IntCmd

LPush 将一个或多个值插入列表头部。

func (*Client) LRange 

func (c *Client) LRange(ctx context.Context, key string, start, stop int64) *redis.StringSliceCmd

LRange 获取列表指定范围的元素。

func (*Client) NewBatch 

func (c *Client) NewBatch() *Batch

NewBatch 创建一个批量操作实例。

func (*Client) NewBloomFilter 

func (c *Client) NewBloomFilter(ctx context.Context, key string, errorRate float64, capacity int64) (*BloomFilter, error)

NewBloomFilter 创建布隆过滤器。 如果 key 不存在，会自动创建。

参数:

  • ctx: 上下文（支持超时/取消）
  • key: 布隆过滤器的 key 名
  • errorRate: 误判率（如 0.01 表示 1%）
  • capacity: 预计元素数量

func (*Client) NewCounter 

func (c *Client) NewCounter(key string) *Counter

NewCounter 创建分布式计数器。

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) *redis.StatusCmd

Ping 测试连接。

func (*Client) Pipeline 

func (c *Client) Pipeline() redis.Pipeliner

Pipeline 创建一个管道（批量发送命令，减少网络往返）。

注意：返回的 Pipeline 不会自动添加 key 前缀。 如需前缀处理，请使用 NewBatch()。

func (*Client) Publish 

func (c *Client) Publish(ctx context.Context, channel string, message any) *redis.IntCmd

Publish 向频道发布消息。

func (*Client) RPop 

func (c *Client) RPop(ctx context.Context, key string) *redis.StringCmd

RPop 移除并返回列表尾部元素。

func (*Client) RPush 

func (c *Client) RPush(ctx context.Context, key string, values ...any) *redis.IntCmd

RPush 将一个或多个值插入列表尾部。

func (*Client) SAdd 

func (c *Client) SAdd(ctx context.Context, key string, members ...any) *redis.IntCmd

SAdd 向集合添加一个或多个成员。

func (*Client) SIsMember 

func (c *Client) SIsMember(ctx context.Context, key string, member any) *redis.BoolCmd

SIsMember 判断成员是否在集合中。

func (*Client) SMembers 

func (c *Client) SMembers(ctx context.Context, key string) *redis.StringSliceCmd

SMembers 获取集合所有成员。

func (*Client) SRem 

func (c *Client) SRem(ctx context.Context, key string, members ...any) *redis.IntCmd

SRem 从集合移除一个或多个成员。

func (*Client) ScriptExists 

func (c *Client) ScriptExists(ctx context.Context, hashes ...string) *redis.BoolSliceCmd

ScriptExists 检查脚本是否已缓存。

func (*Client) ScriptLoad 

func (c *Client) ScriptLoad(ctx context.Context, script string) *redis.StringCmd

ScriptLoad 将脚本加载到脚本缓存。

func (*Client) Set 

func (c *Client) Set(ctx context.Context, key string, value any, expiration time.Duration) *redis.StatusCmd

Set 设置 key 的值。

func (*Client) SetNX 

func (c *Client) SetNX(ctx context.Context, key string, value any, expiration time.Duration) *redis.BoolCmd

SetNX 仅当 key 不存在时设置。

func (*Client) Subscribe 

func (c *Client) Subscribe(ctx context.Context, channels ...string) *redis.PubSub

Subscribe 订阅一个或多个频道。

func (*Client) TxPipeline 

func (c *Client) TxPipeline() redis.Pipeliner

TxPipeline 创建一个事务管道。

注意：返回的 Pipeline 不会自动添加 key 前缀。 如需前缀处理，请使用 NewBatch()。

func (*Client) ZAdd 

func (c *Client) ZAdd(ctx context.Context, key string, members ...redis.Z) *redis.IntCmd

ZAdd 向有序集合添加一个或多个成员。

func (*Client) ZCard 

func (c *Client) ZCard(ctx context.Context, key string) *redis.IntCmd

ZCard 获取有序集合的成员数。

func (*Client) ZRange 

func (c *Client) ZRange(ctx context.Context, key string, start, stop int64) *redis.StringSliceCmd

ZRange 获取有序集合指定范围的成员。

func (*Client) ZRangeWithScores 

func (c *Client) ZRangeWithScores(ctx context.Context, key string, start, stop int64) *redis.ZSliceCmd

ZRangeWithScores 获取有序集合指定范围的成员（含分数）。

func (*Client) ZRem 

func (c *Client) ZRem(ctx context.Context, key string, members ...any) *redis.IntCmd

ZRem 从有序集合移除一个或多个成员。

type Counter 

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

Counter 是分布式原子计数器。 基于 Redis INCR/DECR 实现，支持原子增减和过期。

func (*Counter) Decr 

func (ct *Counter) Decr(ctx context.Context, delta int64) (int64, error)

Decr 原子减少并返回新值。 注意：Redis DECR 允许结果为负数。如需下界保护，使用 DecrFloor。

func (*Counter) DecrFloor 

func (ct *Counter) DecrFloor(ctx context.Context, delta int64, floor int64) (int64, error)

DecrFloor 原子减少并返回新值，结果不低于 floor（默认 0）。 适用于配额、限流等不允许负数的场景。

func (*Counter) Get 

func (ct *Counter) Get(ctx context.Context) (int64, error)

Get 获取当前值。key 不存在时返回 0。

func (*Counter) Incr 

func (ct *Counter) Incr(ctx context.Context, delta int64) (int64, error)

Incr 原子增加并返回新值。

func (*Counter) IncrWithTTL 

func (ct *Counter) IncrWithTTL(ctx context.Context, delta int64, ttl time.Duration) (int64, error)

IncrWithTTL 原子增加并设置过期时间。 如果 key 已有 TTL，只增加不影响原有 TTL；如果 key 无 TTL，设置指定的 TTL。

func (*Counter) Reset 

func (ct *Counter) Reset(ctx context.Context) error

Reset 重置计数器（删除 key）。

type RedisClientOption 

type RedisClientOption struct {
	Prefix string
}

RedisClientOption 配置 Client 的可选参数。

type RedisClientOptionFunc 

type RedisClientOptionFunc func(*RedisClientOption)

RedisClientOptionFunc 配置函数类型。

func WithPrefix 

func WithPrefix(prefix string) RedisClientOptionFunc

WithPrefix 设置 key 前缀。 所有操作的 key 会自动添加 "prefix:" 前缀。

type RedisConfig 

type RedisConfig struct {
	Host     string `yaml:"host"`
	Port     int    `yaml:"port"`
	Password string `yaml:"password"`
	DB       int    `yaml:"db"`
}

RedisConfig 是 Redis 连接配置，可直接从 YAML 反序列化。

Source Files

View all Source files

Directories

Path Synopsis
Package cache 提供基于 go-redis 的 Cache[T] 分布式缓存实现。
 Package cache 提供基于 go-redis 的 Cache[T] 分布式缓存实现。
Package distlock 提供分布式锁门面。
 Package distlock 提供分布式锁门面。
Package ratelimit 提供基于 Redis 的分布式限流器。
 Package ratelimit 提供基于 Redis 的分布式限流器。

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.