redisx

package module
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2026 License: MIT Imports: 8 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.14.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 微工具集 28 合 1（errors/bloomx/contextx/ctxscope/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/secretx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/webhook/cli/pack/procx；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 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；cli（v0.16.0 起）框架无关可单测的子命令分发原语——App/Command + 退出码 0/1/2 写死在包里、usage 按 Summary 自动生成、不读 os.Args 不调 os.Exit（输出流全由调用方给）；pack（v0.16.0 起）迁移包容器原语——zip + manifest（格式版本/条数/每文件 SHA-256）+ JSONL 流式读写 + Inspect 体检一次列全问题并区分包损坏与版本不认识 —
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 枚举可观测出口；v0.16.0 起 ratelimit NewKeyedLimiterByFunc[K]——factory func(K) Limiter 按 key 定配额（一个管理器按接口维度分档位，NewKeyedLimiterOf 零破坏随迁；未登记 key 拿 factory 兜底档的坑已在 doc 点名，#31）；v0.17.0 起 KeyedLimiter.Create 护栏内原子登记（表满先回收空闲与 Allow 同路、仍满拒绝计 OverCapHits、已存在不覆盖——热更走 Replace；解决 ByFunc factory 库锁内调用致消费方锁序倒置，#33）；v0.18.0 起 retry.DoValue 泛型伴生——带返回值的重试（DoValue[T](ctx, cfg, fn func(attempt int) (T, error))；Do 改为委托给 DoValue——退避序列/抖动/MaxDelay 封顶/DelayHint 优先/Retryable 门控/ctx 取消只有一份实现，杜绝「同一个仓里两份实现」；失败返回零值与最后一次错误） 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
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；v0.9.0 起 config FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖——LoadBootstrap 默认接线，免全量指针化）+ require tag（必须 yaml/env 提供，缺失列全并附 env 提示）+ v0.9.1 修 yaml:,inline 字段在 FieldSet 下漏标记（inline 叶子显式零值曾被 default 覆盖）；v0.9.2 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——误报 PATH/HOME、漏无人设置的真拼错，core#8），命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免；v0.10.0 起 config 严格模式——LoadBootstrap[T](envFlag string, opts ...LoadOption) 传 config.WithStrict() 开启：未知键拒载（不再静默忽略），错误带嵌套路径 + 该层合法键清单 + 近似拼写建议（UnknownKeyError）；默认行为不变，严格模式显式开启；v0.11.0 起 config 加载入口按来源拆开——LoadFile（任意路径：CLI -config 路径、容器内固定挂载位）+ Unmarshal（字节源：API 下发 / 模板渲染 / 测试夹具），与 LoadBootstrap（etc/ 约定）共享同一条解码线，因此严格模式诊断面（嵌套路径 / 合法键清单 / 拼写建议）与来源无关；LoadBootstrap 行为与错误文案逐字不变 —
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 拆出 logx、pkg
metrics Prometheus 门面 + 弹性指标族 core
tracing OpenTelemetry 追踪 + trace_id 真相源（v0.3.0 起 OTLP 双协议导出：gRPC 缺省 / HTTP，Config.Protocol + Headers，切换协议不丢传播器/指标/旧 provider 关闭） logx
registry 注册发现核心（provider 无关 SPI：Registrar/Discoverer/Subscriber/ConfigStore + 实例模型 + netutil）+ sdbridge + registrymocks——根仓零第三方依赖；Nacos 实现与 Nacos 配置源已拆成嵌套模块（v0.5.0 起：registry/nacosimpl、registry/nacos——nacos-sdk-go 重依赖隔离在此，实测单独引入即拖 63 个第三方模块，不隔离时只要 SPI 接口的消费方也会被连带拖入） core
data 数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；v0.15.0 起壳跟随源仓演进——cache 壳补 LocalCache 可选形状（EvictPolicy/Sweeper/HitGetter）、cachetest 壳补 5 个契约套件入口（套件 8 → 13 场景）、v0.18.0 起 cache 壳补 PeekGetter 别名 + cachetest 壳补 2 个 stale-if-error 契约入口（套件 13 → 15 场景）、timertask 壳的 Redis 形态随源仓 v0.2.0 迁至嵌套模块 timertask/redis（壳不再转发 RedisBackend/ShardManager，Redis 形态直接依赖该嵌套模块）；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 三态 + 故障本地兜底）；v0.9.0 起 distlock Lockout 分布式防爆破锁（Redis 侧 fail2ban：滑窗失败计数→阈值锁定 Penalty→Reset 清零，与 concurrency/ratelimit.Lockout 进程内孪生——多实例共享计数是存在理由；惩罚只按首次触发计算、nil client fail-fast 不降级，#6） 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、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）；v0.8.0 起 SafeDialFunc/WithSafeDial 出站 SSRF 防护胶水（判定单源 pkg/urlguard v0.15.0：解析 IP 全量预检 + 实际 RemoteAddr 端点核对闭合重解析 TOCTOU、Happy-Eyeballs 覆盖，构造态豁免；v0.7.0 内置的独立 httpx/urlguard 实现收敛删除，#11） concurrency、logx、metrics、pkg、registry、tracing
network 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 concurrency、logx、tracing
timertask 分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）；v0.2.0 起 Redis 后端迁至嵌套模块 timertask/redis（根包不再引 go-redis/logx/concurrency，require 仅 pkg——import timertask 与 import timertask/local 的模块依赖面均无 redis，纯 stdlib 嵌入式场景可用）+ 新增 local 子包 cron 调度器 Scheduler（表达式复用 pkg/timex/cron 不另写一份；并发度/CatchUp 补跑/退出语义明确，FakeClock 假时钟驱动、触发点序列可确定性断言） pkg
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 去端口（连接桶→地址桶）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord{Method,Path,Status,Latency,ClientIP,UserAgent,TraceID} 与日志同源、c 同传可读业务键、error/panic 只记 Warn 不影响主链路、SkipPaths 命中不触发）+ chainmw.WithSink 内核同构（kitex 随 ToKitex 获得）+ StackConfig.DisableResponseWrap 响应自管一键形态（TraceID→Recovery→AccessLog）与 AccessLogOptions 透传 + doc/README「适用边界」段（响应契约统一 vs handler 自管的推荐组合，#18）；v0.12.0 起 AccessLog panic 恢复点产出记录（AccessRecord.Panic 标记 + Err 摘要，Hertz status 按 Recovery 缺省 500）后按原值重抛——panic 请求不再零访问记录，sink/kitex 桥接同步留痕，#20；v0.13.0 起 accesslog 内建日志可关闭/改道（WithAccessLogSilent 只采不写、WithAccessLogLogger 注入宿主 logger 避免双写；静默下 skip/redact/sink/panic 记录照常），内核 chainmw.WithSilent 同构（kitex 随 ToKitex 获得），#38 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 池 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 关闭；就绪门漏接时可观测——nacos 看门狗超时打 ERROR 点明「服务不会注册到注册中心」（WithReadyTimeout 可调）+ NNSComponent.RegistrationState() 暴露注册阶段（pending/registered/failed/skipped/shutdown）；Metrics/Tracing 在嵌套模块 bootstrap/obs concurrency、core、logx
hertz Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整——探活目标是 server 自动取到的全部 HostPort，无探活地址覆盖选项（kitex 侧才有 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、core、kitex、logx、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 接入等场景）
  • Close(ctx) error 幂等关停（sync.Once；重复调用稳定返回同一结果）

快速接入

从地址创建： 

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

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

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 批量操作。 将多个命令打包发送，减少网络往返次数。 Batch 自动处理 key 前缀转换（与 Pipeline 代理同口径）。

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 客户端。

opt 为 nil 属调用方参数错误，构造期 fail-fast 返回 error（#129）—— 函数签名预留了 error 返回通道，nil 入参不应升级成进程崩溃（构造期直接 解引用会 nil 指针 panic，调用方拿不到任何可处理的错误）。与 etcdx 的 同族构造口径一致（etcdx.NewClient(nil) 同样返回 error 而非 panic）。

opt 不会被改写（#116）：入口先 shallow-copy 再填缺省值——调用方复用同一 opt 构建第二个实例（同配置双实例/测试矩阵常见）时，不会拿到被第一次调用 污染过的配置（否则「调用方显式设置的字段不覆盖」的判定基线已变，比如 调用方故意传 DialTimeout: 0 想用 go-redis 自身缺省，第一次调用后被固化 为 3s）。*redis.UniversalOptions 是纯值结构（字段全为值/切片），浅拷贝 安全。与 NewClientFromClient 的「一个参数都不动」口径对齐。

零可观测性副作用：不自动注入任何 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 NewClientFromClient added in v0.10.5 

func NewClientFromClient(c redis.UniversalClient, opts ...RedisClientOptionFunc) *Client

NewClientFromClient **包住既有** go-redis 客户端，不新建连接、不改连接参数。

为什么需要：消费方（pigeonbox/core）自己管连接池与超时（不想让 redisx 改写 它们的连接语义），但又想用 redisx 的原语（典型是 Counter.IncrWithTTL： 「计数 + 首次命中才设 TTL」的原子版）。 与 NewClient 的关键区别：

  • NewClient 会在副本上（不改调用方 opt，#116）填连接默认参数 （DialTimeout/ReadTimeout/WriteTimeout/PoolTimeout/MinIdleConns） ⇒ 连接语义会变；
  • NewClientFromClient 一个参数都不动 ⇒ 纯包装，调用方的连接行为完全不变。

传入 nil 会得到一个不可用的 Client（调用其方法会 panic）——调用方应自行保证非 nil。

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(_ context.Context) error

Close 幂等关闭底层 Redis 连接（#148）。

契约（本仓生命周期硬规则：组件 Close 统一 Close(ctx) error + sync.Once 幂等）：

  • sync.Once 保证「显式 Close + defer Close」双路径、多持有者各自 Close 时 底层连接池只真正关一次，重复调用稳定返回**首次**关闭的结果（成功即恒 nil， 不再透传 go-redis 的 redis.ErrClosed——「二次关闭被误记为关闭失败」的口径 就此关闭）；
  • 签名与 etcdx.Client.Close(ctx) 同形（矩阵统一口径）：底层 go-redis 连接池 关闭是同步有界操作，ctx 仅承接统一签名、不参与期限控制（无需 goroutine 包装），停机期限由调用方在外层关停流程约束。

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) GetDel added in v0.11.0 

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

GetDel 原子返回 key 的值并删除该键（Redis GETDEL，要求 Redis >= 6.2）。

一次性凭据（OAuth state、授权 code、短信/图形验证码）的「恰好一次核销」 语义：GETDEL 单命令原子取删，并发下也只有一个调用方拿得到值——GET+DEL 两步在并发下会双核销。与其它单发命令同口径：convertKey 套 key 前缀， 超时/观测随底层客户端配置；key 不存在时返回 redis.Nil。

部署在 Redis < 6.2（无 GETDEL）时用 GetDelCompat（自动原子回退）。

func (*Client) GetDelCompat added in v0.11.0 

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

GetDelCompat 语义与 GetDel 相同，额外兼容 Redis < 6.2（无 GETDEL）： GETDEL 返回 unknown command 时回退到 Lua「GET+DEL」单次原子执行—— 不是两步 GET+DEL（并发下会双核销），核销语义不降级。

为什么不直接全部走 Lua：GETDEL 是服务端单命令，成本低于 EVAL； 回退只在老 Redis 上触发一次（后续命令仍会先试 GETDEL）。 管道版不提供 Compat：unknown command 只在 Exec 时暴露，无法在排队期 选择回退路径（见 Pipeline 类型文档）。

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 不存在，会自动创建。

⚠️ key 已存在时**复用既有过滤器**：errorRate 与 capacity 以既有实例为准， 本次传入的参数不生效（Redis 的 BF.RESERVE 对已存在的 key 不覆盖）。 需要按新参数重建，请先 DEL 该 key。

「已存在」的判定**不做错误文本匹配**（#112）：任何含 "exists" 的错误消息 （连接/代理/集群客户端的错误文案恰好带该词）此前都会被误判成「已存在，复用」， 后续 BF.ADD 打在不存在的过滤器上必然失败且错误点远离根因。RESERVE 报错后 改用 BF.INFO 探测区分——过滤器确实存在时 INFO 必成功（与 RedisBloom 各版本 的措辞无关，miniredis 与真实 Redis 通吃）；INFO 也失败则 RESERVE 的失败另有 原因（连接故障/模块缺失等），原始错误上抛不吞。

参数:

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

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() *Pipeline

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

与单发命令同口径：管道上排队的命令同样经 convertKey 应用 key 前缀。 此前直接返回裸 redis.Pipeliner，管道命令绕过前缀——配了前缀的部署里 同一逻辑键在「管道」与「单发」落到不同物理键，静默分叉（redisx#79）。 覆盖面与裸管道逃生舱见 Pipeline 类型文档。

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() *Pipeline

TxPipeline 创建事务管道（MULTI/EXEC），键转换口径与 Pipeline 相同。

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 Pipeline added in v0.11.0 

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

Pipeline 是 redis.Pipeliner 的键前缀代理：管道上排队的命令与单发命令同口径， 所有键经 convertKey 应用 key 前缀。

为什么需要（redisx#79）：此前 Pipeline()/TxPipeline() 直接返回裸 redis.Pipeliner，管道命令不经 convertKey —— 配了 key 前缀的部署里， 同一逻辑键在「管道」与「单发」两条路径落到不同物理键（缓存击穿、计数分裂、 锁不住该锁的键），且两边各自自洽、静默无报错。键转换是 Client 的既有承诺， 管道不该是例外。

覆盖面：与 Client 单发封装一一对应的全部键命令（string/key/hash/list/set/ zset/Lua/Publish）。未覆盖的命令（MGet、Geo、Stream…）不会静默漏前缀—— 本类型不暴露它们（编译期即拦截）；需要时用 Raw() 拿底层裸 Pipeliner （不做键转换，键名请自行处理），或在本仓补一层封装。

GetDelCompat 的 <6.2 回退不提供管道版：unknown command 只在 Exec 时才暴露， 无法在排队期选择回退路径；老 Redis 请用单发 Client.GetDelCompat。

func (*Pipeline) Decr added in v0.11.0 

func (p *Pipeline) Decr(ctx context.Context, key string) *redis.IntCmd

Decr 将 key 的值减 1。

func (*Pipeline) DecrBy added in v0.11.0 

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

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

func (*Pipeline) Del added in v0.11.0 

func (p *Pipeline) Del(ctx context.Context, keys ...string) *redis.IntCmd

Del 删除一个或多个 key。

func (*Pipeline) Discard added in v0.11.0 

func (p *Pipeline) Discard()

Discard 丢弃管道中尚未执行的命令。

func (*Pipeline) Eval added in v0.11.0 

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

Eval 执行 Lua 脚本。

func (*Pipeline) EvalRO added in v0.11.0 

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

EvalRO 执行只读 Lua 脚本。

func (*Pipeline) EvalSha added in v0.11.0 

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

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

func (*Pipeline) EvalShaRO added in v0.11.0 

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

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

func (*Pipeline) Exec added in v0.11.0 

func (p *Pipeline) Exec(ctx context.Context) ([]redis.Cmder, error)

Exec 执行管道中排队的全部命令，返回各命令的结果。

func (*Pipeline) Exists added in v0.11.0 

func (p *Pipeline) Exists(ctx context.Context, keys ...string) *redis.IntCmd

Exists 检查 key 是否存在。

func (*Pipeline) Expire added in v0.11.0 

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

Expire 设置 key 的过期时间。

func (*Pipeline) Get added in v0.11.0 

func (p *Pipeline) Get(ctx context.Context, key string) *redis.StringCmd

Get 获取 key 的值。

func (*Pipeline) GetDel added in v0.11.0 

func (p *Pipeline) GetDel(ctx context.Context, key string) *redis.StringCmd

GetDel 原子返回 key 的值并删除该键（Redis GETDEL，要求 Redis >= 6.2）。 与单发 Client.GetDel 同口径：convertKey 应用 key 前缀，缺失键回 redis.Nil。

func (*Pipeline) HDel added in v0.11.0 

func (p *Pipeline) HDel(ctx context.Context, key string, fields ...string) *redis.IntCmd

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

func (*Pipeline) HGet added in v0.11.0 

func (p *Pipeline) HGet(ctx context.Context, key, field string) *redis.StringCmd

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

func (*Pipeline) HGetAll added in v0.11.0 

func (p *Pipeline) HGetAll(ctx context.Context, key string) *redis.MapStringStringCmd

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

func (*Pipeline) HSet added in v0.11.0 

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

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

func (*Pipeline) Incr added in v0.11.0 

func (p *Pipeline) Incr(ctx context.Context, key string) *redis.IntCmd

Incr 将 key 的值加 1。

func (*Pipeline) IncrBy added in v0.11.0 

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

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

func (*Pipeline) LLen added in v0.11.0 

func (p *Pipeline) LLen(ctx context.Context, key string) *redis.IntCmd

LLen 获取列表长度。

func (*Pipeline) LPop added in v0.11.0 

func (p *Pipeline) LPop(ctx context.Context, key string) *redis.StringCmd

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

func (*Pipeline) LPush added in v0.11.0 

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

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

func (*Pipeline) LRange added in v0.11.0 

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

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

func (*Pipeline) Len added in v0.11.0 

func (p *Pipeline) Len() int

Len 返回管道中排队的命令数量。

func (*Pipeline) Publish added in v0.11.0 

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

Publish 向频道发布消息（频道名经 convertKey 套前缀，与单发 Client.Publish 同口径）。

func (*Pipeline) RPop added in v0.11.0 

func (p *Pipeline) RPop(ctx context.Context, key string) *redis.StringCmd

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

func (*Pipeline) RPush added in v0.11.0 

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

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

func (*Pipeline) Raw added in v0.11.0 

func (p *Pipeline) Raw() redis.Pipeliner

Raw 返回底层裸 redis.Pipeliner——不做任何键转换。 仅当 Pipeline 未覆盖所需命令时使用；键名（含前缀）由调用方自行负责。

func (*Pipeline) SAdd added in v0.11.0 

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

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

func (*Pipeline) SIsMember added in v0.11.0 

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

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

func (*Pipeline) SMembers added in v0.11.0 

func (p *Pipeline) SMembers(ctx context.Context, key string) *redis.StringSliceCmd

SMembers 获取集合所有成员。

func (*Pipeline) SRem added in v0.11.0 

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

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

func (*Pipeline) Set added in v0.11.0 

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

Set 设置 key 的值。

func (*Pipeline) SetNX added in v0.11.0 

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

SetNX 仅当 key 不存在时设置。

func (*Pipeline) ZAdd added in v0.11.0 

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

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

func (*Pipeline) ZCard added in v0.11.0 

func (p *Pipeline) ZCard(ctx context.Context, key string) *redis.IntCmd

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

func (*Pipeline) ZRange added in v0.11.0 

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

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

func (*Pipeline) ZRangeWithScores added in v0.11.0 

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

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

func (*Pipeline) ZRem added in v0.11.0 

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

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

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.