Redis的有序集合（Sorted Set，简称zset）是实际项目里用得非常多的数据结构，排行榜、延时队列、热度榜单等场景几乎都离不开它。而在操作有序集合时，我们经常需要知道这个集合里到底有多少个成员，这时候就要用到zcard命令。这个命令看起来简单到不能再简单，但围绕它还是有不少人踩过坑，比如对错误类型的键执行它导致程序报错，或者误以为它的性能和集合规模有关。这篇文章就把zcard命令彻底讲清楚。
一、Zcard命令的基本语法与用法
zcard命令的作用只有一个：返回指定有序集合的成员数量。它的语法格式如下：
ZCARD key
参数只有一个key，也就是有序集合的键名。如果这个键存在并且是有序集合类型，命令返回成员数量；如果键不存在，返回0。下面用一组实际操作来演示：
127.0.0.1:6379> ZADD ranking 100 "user:A" (integer) 1 127.0.0.1:6379> ZADD ranking 85 "user:B" 92 "user:C" (integer) 2 127.0.0.1:6379> ZCARD ranking (integer) 3 127.0.0.1:6379> ZCARD not_exist_key (integer) 0
从上面的例子可以看到，先用zadd往ranking这个有序集合里加入了三个成员，然后zcard正确返回了3。而对一个不存在的键执行zcard，返回的是0而不是报错，这一点和某些命令（比如hget对不存在的键返回nil）的表现思路是一致的，属于Redis对空值的友好处理。
在代码中使用也很直接，以Python的redis客户端为例：
import redis
r = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
# 添加成员
r.zadd('ranking', {'user:A': 100, 'user:B': 85, 'user:C': 92})
# 获取成员数量
count = r.zcard('ranking')
print(count) # 输出 3需要提醒的是，在旧版本的redis-py库中，zcard的返回值可能是字节类型，这取决于连接时是否设置了decode_responses=True。如果不设置，拿到的是b'3'这样的字节串，直接和整数做比较会出错，这是Python开发者比较容易忽略的细节。
二、为什么Zcard的时间复杂度是O(1)
很多人直觉上认为，统计一个集合的成员数量需要遍历整个集合，集合越大越慢。但zcard的官方文档明确标注时间复杂度是O(1)，也就是说无论集合里有一百个成员还是一亿个成员，执行速度都几乎一样快。这背后是Redis底层数据结构的功劳。
Redis的有序集合底层有两种编码方式：当成员数量少且元素较小时使用ziplist（紧凑列表）编码，此时结构头信息里直接记录了元素数量，读取一个字段就能拿到结果；当数据量变大时会转换为skiplist（跳表）编码，这种编码下的有序集合实际上由一个跳表加一个字典组成，而跳表节点在更新时会维护一个length字段，记录当前跳表的总节点数。zcard执行时只是读取这个字段并减去一个内部哨兵值，不需要任何遍历，所以是常数时间完成。
理解这一点很有实际意义。举个例子，一个电商系统要实时展示参与秒杀活动的人数，如果每次都用zrange把成员全部取出来再在应用层数一遍长度，随着参与人数增长到几十万，网络传输和反序列化的开销会急剧上升；而直接用zcard，无论多少人都是一次几乎零开销的调用。类似的场景还包括统计当前在线用户数、消息队列中待处理任务数等，都可以放心地把zcard当作计数器来用。
不过要注意，O(1)不代表零消耗，每次zcard仍然是一次完整的Redis命令往返，包含网络IO和命令解析。如果业务逻辑中在循环里高频调用zcard，比如一段代码循环一千次每次都查一遍数量，那瓶颈就不在Redis而在网络和调用模式上了，这种情况下应该考虑减少调用次数或者改用流水线。
三、常见误区与踩坑提醒
第一个常见误区是对非有序集合类型的键执行zcard。zcard只能作用于有序集合，如果目标键是字符串、哈希、列表或者普通集合，Redis会直接返回一个 WRONGTYPE 错误。这一点在redis-cli交互环境里表现得不明显，但在程序中就是一个会中断逻辑的异常。实际项目中这种情况往往发生在键命名复用上，比如某个键原来存的是字符串缓存，后来被改成有序集合，而某处旧代码仍然用zcard去查它。来看一个典型的报错现场：
127.0.0.1:6379> SET mykey "hello" OK 127.0.0.1:6379> ZCARD mykey (error) WRONGTYPE Operation against a key holding the wrong kind of value
第二个误区是把键不存在和集合为空混为一谈。zcard对不存在的键返回0，对存在但已被清空的键同样返回0，这两种状态从zcard的返回值上是区分不出来的。如果业务上需要区分“从未创建过”和“创建过但成员已全部移除”，就不能只依赖zcard，需要额外的标记键或者用exists命令配合判断。
第三个误区是忽视过期时间与成员数量的关系。有序集合设置了过期时间后，一旦到期整个键被删除，zcard自然返回0。有些开发者给排行榜设置了过期，却在排查“排行榜数据莫名消失”时忘了这一茬，白白浪费排查时间。另外，在使用zrem逐个删除成员时，当最后一个成员被删掉，整个键也会自动删除，此时zcard返回的0其实意味着键已经不存在了。
第四个误区是并发场景下对zcard结果的过度信任。zcard返回的是命令执行那一瞬间的快照值，在并发写入的环境下，拿到结果之后实际数量可能马上就变了。比如用zcard判断“人数是否达到上限再决定是否允许加入”这种逻辑，在并发请求下会出现超员，因为判断和加入不是原子操作。正确的做法是使用Lua脚本把判断和写入放在一个原子操作里，示例代码如下：
-- 原子性地检查人数并加入成员
local count = redis.call('ZCARD', KEYS[1])
local limit = tonumber(ARGV[2])
if count < limit then
redis.call('ZADD', KEYS[1], ARGV[1], ARGV[3])
return 1
else
return 0
end总的来说，zcard是一个语法极简但实用性很强的命令，掌握它的关键在于理解它背后O(1)的原理，同时清楚它在类型检查、键存在性判断和并发一致性上的边界。把这些细节想明白了，在排行榜、限流计数、队列监控等场景里就能用得既高效又稳妥。