Redis LPOS 使用 rank 和 maxlen 时怎样控制扫描范围

Redis LPOS 查的是列表中某个元素的位置。真正容易混淆的地方有三个：RANK 只决定从哪一端数第几个匹配，COUNT 决定返回多少个位置，MAXLEN 才是限制最多比较多少个列表元素。它们可以组合，但不能互相替代。

官方文档：https://redis.io/docs/latest/commands/lpos/

先把 LPOS 的三个边界分开

先把一条 Redis list 想成带有固定位置的序列。LPOS key element 只需要知道在哪个列表里找什么值，默认从头部扫描，找到第一个匹配项后返回它的零基位置。列表里没有目标时，不带 COUNT 会得到 nil。

下面这组命令故意放入多个 c，方便观察参数各自的职责：

# 准备一个包含重复值的列表，位置从 0 开始计数
redis-cli RPUSH lpos:demo a b c 1 2 3 c c

# 默认只返回从头部找到的第一个 c 的位置
redis-cli LPOS lpos:demo c

# COUNT 只影响返回多少个匹配位置，不改变列表内容
redis-cli LPOS lpos:demo c COUNT 2

在这个例子中，结果分别可以理解为位置 2 和位置集合 [2,6]。如果要返回所有匹配位置，用 COUNT 0，而不是随便填一个很大的数量。带了 COUNT 却没有命中时，返回的是空数组。

RANK 决定从哪一侧开始找，返回位置仍是原索引

RANK 的正负号改变的是“匹配序号从哪一端开始计算”，不是返回索引的坐标系。RANK 1 表示从头部遇到的第一个匹配，RANK 2 表示第二个；RANK -1 表示从尾部遇到的第一个匹配，RANK -2 表示从尾部遇到的第二个。

# 正 rank 从头部数第二个 c
redis-cli LPOS lpos:demo c RANK 2

# 负 rank 从尾部数第一个 c，结果仍用从头部开始的零基索引
redis-cli LPOS lpos:demo c RANK -1

# 从尾部开始找两个匹配位置，返回顺序也体现尾部到头部的搜索方向
redis-cli LPOS lpos:demo c RANK -1 COUNT 2

这组命令的典型结果是 6、7 和 [7,6]。不要把 7 误读成“倒序下标”；它仍然是列表从头数的原始位置，只是搜索过程从尾部开始。

MAXLEN 把扫描窗口限制在 list 前后端

MAXLEN 约束的是比较次数上限。正向搜索时，它从列表头部向后比较；负向搜索时，它从尾部向前比较。比如 MAXLEN 3 表示最多比较三个元素，目标值位于窗口之外，即使列表后面确实存在该值，也不会继续扫描。

它不是 LRANGE，不会生成一个新列表，也不是 COUNT，不会限制最终返回几个位置：

# 最多比较头部的 3 个元素，目标若在第 4 个位置之后就不再继续
redis-cli LPOS lpos:demo c MAXLEN 3

# 从尾部向前最多比较 3 个元素，返回仍指向原列表的零基位置
redis-cli LPOS lpos:demo c RANK -1 MAXLEN 3

# MAXLEN 取 0 表示不限制比较数量
redis-cli LPOS lpos:demo c MAXLEN 0

工程上可以把 MAXLEN 当成“我愿意为一次查找付出的最大扫描窗口”。如果业务只关心最近写入的一小段列表，负 RANK 配合小的 MAXLEN 更贴近这个意图；如果必须保证全量命中，就不要用一个过小的上限制造假阴性。

组合 rank 和 maxlen 时怎样做回归检查

把参数放在一起时，建议先确定方向，再确定匹配序号，最后估算扫描窗口。下面这张表适合放进单元测试或命令回归清单：

还要注意列表长度变化：如果生产代码在写入端持续追加或弹出元素，原来的位置会变化，测试不能只断言一个固定数字。更稳妥的做法是固定列表内容，分别覆盖头部命中、尾部命中、重复命中和窗口外四类情况，再分别记录不带 COUNT 的 nil 与带 COUNT 的空数组。

常见问题

LPOS 的 MAXLEN 会把 Redis 列表截断吗？

不会。它只限制本次命令最多比较多少个元素，不修改 key 对应的 list。

RANK -1 返回的索引需要换算成倒序下标吗？

不需要。返回值始终是从列表头部开始的零基索引，负 rank 只影响搜索方向和匹配序号。

COUNT 0 和 MAXLEN 0 是一回事吗？

不是。COUNT 0 表示返回所有匹配位置，MAXLEN 0 表示不限制比较数量，前者影响结果数量，后者影响扫描边界。