在Redis的五种基础数据类型中，有序集合（Sorted Set）经常被用于排行榜、延迟队列、优先级队列等场景。业务上往往需要实时知道某个有序集合里究竟有多少成员，例如展示排行榜的总参与人数，或者判断延迟队列中还有多少任务等待处理。ZCARD命令就是专门用来解决这个问题的，它能够直接返回有序集合的成员数量，用法简单且性能极高。
ZCARD的基本语法与返回值
ZCARD命令的语法非常直接，只需要在命令后面跟上键名：ZCARD key。它返回一个整数，表示有序集合中成员的数量。如果传入的键不存在，Redis会把它当作空的有序集合处理，因此返回0。这个行为和很多其他Redis命令保持一致，调用方不必额外判断键是否存在。
来看一个最简单的命令行示例。先通过ZADD向有序集合写入三个成员，再用ZCARD查看数量：
ZADD rank 95 alice 88 bob 92 carol ZCARD rank
执行后返回整数3。这里需要注意，有序集合中的成员是唯一的，即便你使用ZADD重复添加同一个成员，ZCARD统计的仍是去重后的成员数。比如再执行一次ZADD rank 90 alice，虽然命令返回1表示新增或更新了1个成员，但实际上alice已经存在，只是分值被更新，ZCARD结果仍然是3。
如果对一个字符串类型的键执行ZCARD，会触发类型错误。Redis会返回类似 WRONGTYPE Operation against a key holding the wrong kind of value 的提示。因此在使用ZCARD前，通常需要确保键的类型是有序集合，或者通过业务约定避免类型冲突。
ZCARD背后的实现原理：O(1)从何而来
要理解ZCARD为什么能瞬间返回结果，需要先了解Redis有序集合的底层实现。Redis 7.0以后，有序集合的默认编码从ziplist切换为listpack，而在元素数量较多或成员长度较长时，会使用skiplist加dict的组合结构。无论哪种编码，Redis都会在集合结构体中维护一个长度字段，专门记录当前成员数量。
在小集合场景下，listpack或ziplist编码会把所有成员和分值紧凑地存储在一段连续内存中，并且在头部记录元素个数。读取这个字段不需要遍历整个列表，所以ZCARD可以直接返回。当集合变大，Redis会转换为skiplist编码，此时数据分散在跳表节点中，但skiplist结构体本身也保存了一个length属性，每次插入或删除节点时同步更新。因此ZCARD只需要读取length字段，时间复杂度为O(1)，和集合大小无关。
这也是ZCARD与ZCOUNT、ZRANGE等命令最大的区别。ZCOUNT需要根据分值范围查找边界节点，复杂度为O(log(N))；ZRANGE则需要返回具体成员，复杂度为O(log(N)+M)，其中M是返回的成员数。如果你只是想获取成员总数，调用ZCOUNT key -inf +inf虽然也能得到正确结果，但多花了不必要的查找成本。用ZRANGE key 0 -1再在客户端计算长度更不可取，因为所有成员都会通过网络传回客户端，集合非常大时可能造成内存压力和响应延迟。
各语言客户端中如何调用ZCARD
在实际项目中，开发者通常通过客户端库操作Redis。Python的redis-py提供了zcard()方法，用法与原生命令一一对应。下面这段代码展示了连接Redis、添加成员并获取数量的完整过程：
import redis
r = redis.Redis(host='localhost', port=6379, db=0)
r.zadd('rank', {'alice': 95, 'bob': 88, 'carol': 92})
count = r.zcard('rank')
print(count) # 输出 3
Go语言开发中，go-redis库是最常见的选择。它的ZCard方法返回两个值，第一个是成员数量，第二个是错误信息。代码示例如下：
package main
import (
"context"
"fmt"
"github.com/redis/go-redis/v9"
)
func main() {
ctx := context.Background()
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
})
rdb.ZAdd(ctx, "rank", redis.Z{Score: 95, Member: "alice"})
rdb.ZAdd(ctx, "rank", redis.Z{Score: 88, Member: "bob"})
count, err := rdb.ZCard(ctx, "rank").Result()
if err != nil {
panic(err)
}
fmt.Println(count) // 输出 2
}
Java开发者使用Jedis或Lettuce也很方便。以Jedis为例，zcard方法返回long类型，不需要额外转换。调用前要确保连接池正确初始化，并在使用后关闭连接或归还到池中。整体来说，ZCARD在各个客户端中的封装都非常简单，没有复杂的参数，也不涉及序列化问题。
实战应用与常见误区
排行榜是ZCARD最典型的使用场景之一。假设一个游戏需要展示当前参与排位赛的玩家总数，就可以在玩家提交成绩时使用ZADD更新有序集合，然后通过ZCARD读取总人数。由于ZCARD是O(1)操作，即使玩家数量达到百万级别，也能在极短时间内返回，不会对Redis主线程造成阻塞。这个特性让它非常适合高并发下的实时计数。
延迟队列也是另一个高频场景。通常用有序集合的成员保存任务ID，分值保存任务执行时间戳。消费者线程可以先通过ZCARD判断队列中是否有待处理任务，再决定是否调用ZRANGEBYSCORE获取到期任务。不过要注意，ZCARD返回的是总任务数，包括已经到期和尚未到期的任务，不能直接认为所有任务都已可执行。如果需要只统计到期任务，应该用ZCOUNT key -inf now，其中now是当前时间戳。
一个常见的误区是，有人会担心ZCARD在键不存在或键类型不是有序集合时抛异常。其实键不存在时Redis统一返回0，不需要提前判断。另一个误区是把ZCARD当成条件计数来使用，实际上它只能统计全部成员。如果你需要按分值区间统计，ZCOUNT才是正确的命令。还有一部分开发者习惯用ZRANGE取出所有成员再取数组长度，这在大集合中会带来巨大性能浪费，应当避免。
最后需要强调，ZCARD虽然简单，但在集群模式下依然安全可靠。因为Redis Cluster按槽分配键，同一个键的数据只会落在单个节点上，ZCARD天然具备单键操作的原子性。事务、Lua脚本中也都可以放心使用，不会出现计数不一致的问题。掌握这些细节，能够帮助你在合适的场景下用最小的成本获取有序集合的规模信息。
