GeminiDB Redis基本数据类型

String是Redis最基础、最常用的数据类型，属于二进制安全字符串，可存储字符串、数字、二进制数据（图片、文件字节流）。底层采用SDS（简单动态字符串）实现，具备自动扩容、杜绝缓冲区溢出、高效获取长度的特性。

支持三种存储形式：普通字符串、整数、浮点数，对数值型String支持原子增减操作。单Key单Value结构，无嵌套数据结构。

核心常用命令

• SET key value [EX seconds] [PX milliseconds]：设置键值对，支持设置过期时间。
• GET key：获取Key对应Value。
• SETNX key value：不存在则设置，用于分布式锁。
• INCR/INCRBY key num：数值原子自增、指定步长自增。
• DECR/DECRBY key num：数值原子自减。
• MSET/MGET key1 val1 key2 val2：批量设置、批量获取，提升并发性能。
• APPEND key value：追加字符串内容。
• STRLEN key：获取字符串长度。

业务适用场景

• 基础缓存场景：用户信息、配置信息、字典数据、接口返回结果缓存。
• 计数器场景：文章阅读量、点赞数、访问PV/UV、接口调用次数统计。
• 分布式锁：基于SETNX实现简易分布式锁。
• 限流场景：接口限流、IP限流、用户频次限制。
• 全局唯一ID：利用INCR原子自增生成有序ID。
• 短链接存储：短码与长链接映射关系存储。

使用规范与注意事项

• 禁止存储超大Value，单Value建议控制在10KB以内，避免网络IO与内存开销过大。
• 数值操作仅支持整数，浮点数不支持INCR/DECR系列命令。
• 批量操作优先使用MSET/MGET，减少网络往返次数。
• 缓存场景必须配置合理过期时间，避免内存溢出。

代码示例

以下为 String 类型高频可直接运行命令示例，覆盖缓存、计数、过期、批量操作核心场景：

# 1. 基础读写 & 过期设置
 set user:100:name "张三" ex 3600
 get user:100:name

 # 2. 批量读写
 mset user:101:name "李四" user:101:age 24
 mget user:101:name user:101:age

 # 3. 原子计数器（并发安全）
 incr article:read:100      # 阅读量+1
 incrby article:read:100 10 # 阅读量+10
 decr stock:num             # 库存-1

 # 4. 简易分布式锁（NX 互斥、EX 自动释放）
 set lock:order 1 ex 10 nx

 # 5. 字符串追加与长度
 append user:100:name "_VIP"
 strlen user:100:name

Hash是Key-Field-Value三层结构化数据类型，一个Hash Key可包含多个Field-Value键值对，底层根据元素数量自动切换编码：数量少、Value小时使用压缩列表（ziplist），效率极高；数量超过阈值后转为哈希表（hashtable）。

核心优势：适合存储结构化对象，无需序列化整个对象，可单独更新、查询单个字段，相比String存储JSON对象更灵活、性能更优。

核心常用命令

• HSET key field value：设置哈希字段值。
• HGET key field：获取单个字段值。
• HMSET/HMGET key field1 field2：批量设置、批量获取字段。
• HGETALL key：获取Hash所有字段和值。
• HDEL key field：删除指定字段。
• HLEN key：获取字段数量。
• HINCRBY key field num：哈希字段数值原子自增。
• HEXISTS key field：判断字段是否存在。

业务适用场景

• 结构化对象缓存：用户信息（ID、昵称、手机号、头像）、商品信息、订单基础信息，替代String序列化JSON。
• 高频局部更新场景：用户积分、余额、会员等级实时更新，无需更新整条数据。
• 配置分组存储：系统模块配置、渠道参数配置，一个Key管理一组配置。
• 统计维度存储：多维度数据统计，如用户日/周/月活跃度统计。

使用规范与注意事项

• 禁止使用HGETALL遍历大Hash，海量字段场景会引发阻塞、性能雪崩。
• 单个Hash字段数量建议控制在1000以内，超出建议拆分Key。
• 字段命名统一规范，避免过长Field名称占用内存。
• Hash不支持单独给Field设置过期时间，过期仅针对整个Hash Key。

代码示例

以下为 Hash 类型标准操作示例，适用于用户对象、购物车等结构化数据场景：

# 1. 单字段/多字段写入用户对象
 hset user:200 name "王五" age 25 gender "男" phone "13800000000"

 # 2. 单字段/多字段读取
 hget user:200 name
 hmget user:200 age phone

 # 3. 获取全部字段与值（小数据可用，大数据推荐 hscan）
 hgetall user:200

 # 4. 字段原子自增（年龄、积分、成长值通用）
 hincrby user:200 age 1
 hincrby user:200 score 10

 # 5. 字段删除、存在判断
 hdel user:200 gender
 hexists user:200 phone

 # 6. 购物车场景示例（field=商品ID，value=购买数量）
 hset cart:uid:1000 1001 2 1002 5

List是有序可重复、双向链表结构的字符串列表，按照插入顺序排序，支持左右两端增删元素。底层采用quicklist（快速列表）实现，结合ziplist和链表优势，读写性能极高。

核心特性：头尾操作O(1)时间复杂度，中间遍历O(n)，元素允许重复，支持分页查询、阻塞弹出。

核心常用命令

• LPUSH/RPUSH key value：左插入、右插入元素。
• LPOP/RPOP key：左弹出、右弹出元素。
• BLPOP/BRPOP key timeout：阻塞式弹出，无数据时阻塞等待。
• LRANGE key start end：范围查询列表元素，支持分页。
• LLEN key：获取列表长度。
• LTRIM key start end：裁剪列表，保留指定区间元素。
• LSET key index value：修改指定下标元素。

业务适用场景

• 简单消息队列：基于LPUSH+BRPOP实现异步任务队列、消息推送。
• 时序数据存储：用户操作日志、浏览记录、行为轨迹，按时间顺序存储。
• 排行榜基础列表：有序数据流、最新消息列表展示。
• 限流队列：滑动窗口限流、请求排队处理。
• 分页查询场景：小型有序列表分页展示。

使用规范与注意事项

• 避免使用List存储海量数据，超大列表会导致LRANGE查询性能下降。
• 中间元素查询、修改效率低，非必要不使用下标操作。
• 消息队列场景优先使用BLPOP阻塞消费，避免轮询空查浪费资源。
• 配合LTRIM裁剪列表，控制列表长度，防止数据无限堆积。

代码示例

以下为 List 类型示例，覆盖队列、栈、阻塞消费、数据截断场景：

# 1. 尾部入队（普通队列）
 rpush queue:task "task_001" "task_002" "task_003"

 # 2. 头部入队（栈结构）
 lpush stack:demo "data1" "data2"

 # 3. 弹出消费
 lpop stack:demo
 rpop queue:task

 # 4. 阻塞消费（无数据自动等待，轻量队列核心用法）
 blpop queue:task 10

 # 5. 查询全部数据
 lrange queue:task 0 -1

 # 6. 数据截断（只保留最近10条浏览记录）
 ltrim view:history:1000 0 9

Set是无序、不可重复的字符串集合，底层根据元素特性自动适配编码：整数集合（intset）或哈希表（hashtable）。所有元素唯一，自动去重，支持集合交集、并集、差集等高级运算。

核心特性：添加、删除、查询元素时间复杂度O(1)，支持批量集合运算，无重复数据，无序存储。

核心常用命令

• SADD key member：添加集合元素，自动去重。
• SMEMBERS key：获取集合所有元素。
• SREM key member：删除指定元素。
• SISMEMBER key member：判断元素是否存在于集合。
• SCARD key：获取集合元素数量。
• SPOP key：随机弹出一个元素。
• SINTER/SUNION/SDIFF key1 key2：交集、并集、差集运算。

业务适用场景

• 去重场景：用户点赞、收藏、关注去重，杜绝重复操作。
• 共同关联计算：共同好友、共同关注、共同商品推荐。
• 随机抽取场景：抽奖系统、随机推荐用户/商品。
• 黑名单/白名单：IP黑名单、违规用户名单存储与校验。
• UV统计：独立访客统计，自动去重用户ID。

使用规范与注意事项

• 禁止大规模遍历SMEMBERS大集合，会阻塞Redis主线程。
• 集合运算（交集/并集）CPU开销较高，海量数据场景需控制运算频次。
• 无序特性不支持排序查询，有序场景需使用ZSet。

代码示例

以下为 Set 集合示例，覆盖去重统计、标签、关系运算、抽奖场景：

# 1. 添加元素（自动去重）
 sadd user:tag:100 "游戏" "运动" "阅读" "游戏"

 # 2. 判断元素是否存在（标签/黑名单校验）
 sismember user:tag:100 "游戏"

 # 3. 获取所有标签、统计数量
 smembers user:tag:100
 scard user:tag:100

 # 4. 集合运算（共同好友、差异好友）
 sadd user:fans:101 1001 1002 1003
 sadd user:fans:102 1002 1003 1004
 sinter user:fans:101 user:fans:102  # 交集：共同粉丝
 sdiff user:fans:101 user:fans:102  # 差集：独有粉丝

 # 5. 随机抽奖、随机取值
 srandmember activity:user 3
 spop activity:user 1

 # 6. 删除元素
 srem user:tag:100 "阅读"

ZSet（有序集合）是唯一元素+可排序的高级集合类型，每个元素包含「member（成员）+score（分值）」两个属性，根据score自动排序，member唯一不可重复，score支持重复。

底层采用跳表（skiplist）+哈希表组合实现，兼顾有序排序和高效查询，范围查询、排序、分页性能优异，是Redis核心高级数据结构。

核心常用命令

• ZADD key score member：添加有序元素，指定分值。
• ZRANGE key start end [WITHSCORES]：正序范围查询（从小到大）。
• ZREVRANGE key start end [WITHSCORES]：倒序范围查询（从大到小）。
• ZREM key member：删除指定成员。
• ZSCORE key member：获取元素分值。
• ZINCRBY key num member：元素分值自增。
• ZCARD key：获取元素总数。
• ZRANK/ZREVRANK key member：获取元素排名。

业务适用场景

• 各类排行榜：文章热度榜、用户积分榜、商品销量榜、直播榜单。
• 延时任务：以时间戳为score，实现定时任务、延时消息。
• 权重排序场景：推荐内容权重排序、用户活跃度排序。
• 带排序的去重统计：有序UV、热门数据统计。

使用规范与注意事项

• ZSet内存开销高于Set、List，非排序场景禁止滥用。
• 避免全量遍历大ZSet，分页查询必须指定起止下标。
• score支持双精度浮点数，排序精度足够满足绝大多数业务场景。
• 海量榜单数据建议拆分Key，单ZSet元素不宜过多。

代码示例

以下为 ZSet 有序集合示例，适配排行榜、延时队列、权重排序场景：

# 1. 添加榜单数据（score 分值，member 成员）
 zadd rank:article 95 "文章A" 88 "文章B" 99 "文章C"

 # 2. 分值原子增减（实时热度更新）
 zincrby rank:article 6 "文章B"

 # 3. 查询排名、分值
 zscore rank:article "文章A"
 zrevrank rank:article "文章C"

 # 4. 降序TOP10排行榜（业务最常用）
 zrevrange rank:article 0 9 withscores

 # 5. 区间分数筛选（80~100分文章）
 zrangebyscore rank:article 80 100 withscores

 # 6. 简易延时队列（score=时间戳）
 zadd delay:task 1720000000 "task:pay:10001"

 # 7. 删除榜单元素
 zrem rank:article "文章A"

Stream是Redis5.0及以上版本推出的专业流式消息队列数据类型，是Redis官方原生消息中间件方案。底层为日志型结构化存储，消息持久化、有序、可回溯、支持消费者组、消息确认、故障重试，弥补了List队列无确认、无持久化、无法重复消费的缺陷。

核心特性：消息唯一ID、持久化存储、消费者组隔离、ACK确认、消息回溯、阻塞消费、多消费者并发消费。

核心常用命令

• XADD key * field value：向消息队列写入消息，自动生成消息ID。
• XREAD：普通消费者阻塞读取消息。
• XGROUP CREATE key groupName id：创建消费者组。
• XREADGROUP GROUP group consumer：消费者组读取消息。
• XACK key group msgId：消息消费确认。
• XPENDING：查询未确认消息、死信消息。
• XDEL key msgId：删除指定消息。
• XTRIM：裁剪队列消息，控制队列长度。

业务适用场景

• 高可靠异步消息场景：订单异步处理、物流通知、消息推送、日志收集。
• 流量削峰：秒杀、大促高并发流量缓冲，削峰填谷。
• 多消费者并发消费：任务分发、多节点并行处理业务。
• 消息回溯场景：故障恢复后重新消费历史消息。

使用规范与注意事项

• 必须配置消息ACK机制，避免消息丢失、重复消费。
• 定期清理Pending死信消息，防止消息堆积占用内存。
• 通过XTRIM限制队列最大长度，杜绝消息无限堆积。
• 简单瞬时队列可使用List，高可靠、并发消费场景必须使用Stream。

代码示例

以下为 Stream 可靠消息队列完整示例，包含生产、消费组创建、消费、ACK确认、消息裁剪：

# 1. 生产消息（* 自动生成全局唯一消息ID）
 xadd stream:order * orderId 10001 uid 2001 status 0

 # 2. 创建消费者组（从0开始消费所有历史消息）
 xgroup create stream:order cg_order 0 mkstream

 # 3. 消费者组消费消息（> 读取未消费新消息）
 xreadgroup group cg_order consumer1 count 1 block 2000 streams stream:order >

 # 4. 业务处理完成，手动ACK确认（关键，防止消息重发、堆积）
 xack stream:order cg_order 1720000000000-0

 # 5. 查看待确认消息（异常排查）
 xpending stream:order cg_order

 # 6. 裁剪消息，只保留最新1000条，防止内存溢出
 xtrim stream:order maxlen 1000

 # 7. 读取历史消息（回溯消费）
 xread count 5 streams stream:order 0