Documentation
¶
Overview ¶
Package kvstore 定义一个带 TTL 的原子键值存储接口,供需要"跨进程共享状态"的 原语(counter / cooldown / idempotency)接入分布式后端(如 Redis)。
背景:这些原语的默认实现是纯内存、单进程的——状态不跨实例、进程重启即丢。 单实例部署没问题,但多实例水平扩展时,同一 key 的状态散落在各实例内存里会 出错(配额可被绕过、幂等失效、冷却各算各的)。把状态存取抽象成 Store 接口后, 生产环境可用 Redis 等共享后端实现,让状态真正跨实例一致。
设计:接口方法都是原子操作(Incr / SetNX / TTL 等),context 感知、返回 error (网络调用会失败)。原语默认仍走内存,不配置 Store 时零开销、行为不变;配置 Store(WithStore)后所有状态操作路由到后端,store 错误经各原语的 WithOnStoreError 钩子上报并安全降级。
本包只定义接口 + 提供内存实现 Memory(供测试/单机用)。真实后端(Redis)由使用方 实现——见各方法注释里标注的对应 Redis 命令。遵循 beauty 纯标准库约定,不引入 任何后端 SDK 依赖。
Index ¶
- type Memory
- func (m *Memory) Delete(_ context.Context, key string) error
- func (m *Memory) Get(_ context.Context, key string) ([]byte, bool, error)
- func (m *Memory) GetInt(_ context.Context, key string) (int64, bool, error)
- func (m *Memory) Incr(_ context.Context, key string, delta int64, ttl time.Duration) (int64, error)
- func (m *Memory) Set(_ context.Context, key string, val []byte, ttl time.Duration) error
- func (m *Memory) SetNX(_ context.Context, key string, val []byte, ttl time.Duration) (bool, error)
- func (m *Memory) Stop()
- func (m *Memory) TTL(_ context.Context, key string) (time.Duration, bool, error)
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory 是 Store 的纯内存实现(TTL + 惰性/周期清理),用于单机与测试。 与各原语自带的内存实现等价,主要价值是"用统一 Store 接口跑通链路"。 零值不可用,用 NewMemory 构造;Stop 后 gc goroutine 退出。
type Store ¶
type Store interface {
// Incr 原子地给 key 增加 delta;key 不存在时创建并设置 ttl(已存在则不刷新 ttl)。
// 返回增加后的值。对应 Redis: INCRBY + (首次) EXPIRE。
Incr(ctx context.Context, key string, delta int64, ttl time.Duration) (int64, error)
// GetInt 读取 key 的整数值。不存在/已过期返回 (0, false, nil)。
// 对应 Redis: GET(解析为 int64)。
GetInt(ctx context.Context, key string) (int64, bool, error)
// Get 读取 key 的原始字节。不存在/已过期返回 (nil, false, nil)。对应 Redis: GET。
Get(ctx context.Context, key string) ([]byte, bool, error)
// Set 无条件写入 key=val 并设置 ttl(ttl<=0 表示不过期)。对应 Redis: SET [EX]。
Set(ctx context.Context, key string, val []byte, ttl time.Duration) error
// SetNX 仅当 key 不存在时写入 val + ttl,返回是否写入成功。
// 冷却触发、幂等占位都靠它做"抢占"。对应 Redis: SET NX [EX]。
SetNX(ctx context.Context, key string, val []byte, ttl time.Duration) (bool, error)
// TTL 返回 key 的剩余存活时间。不存在返回 (0, false, nil);永不过期返回一个
// 很大的值 + true。对应 Redis: PTTL。
TTL(ctx context.Context, key string) (time.Duration, bool, error)
// Delete 删除 key(不存在也不报错)。对应 Redis: DEL。
Delete(ctx context.Context, key string) error
}
Store 是带 TTL 的原子键值存储。所有方法应为原子操作,并发安全。 值以 []byte 存储;计数场景用 Incr(后端应保证原子自增)。
Source Files