Redis GEO 半径查询怎么做稳定分页：距离排序、游标边界与结果校验

附近门店查询看起来只是一个半径过滤：给 Redis 一个经纬度和 3 公里范围，再按距离取几条结果。真正接上“加载更多”后，问题会变成距离相同如何排序、门店坐标更新后游标是否还能继续用，以及 Redis 返回的距离如何和业务排序统一。一个可维护的做法是让 Redis 负责地理范围筛选和距离计算，应用层用“距离 + 门店编号”组成稳定的复合游标。

Redis GEOSEARCH 的职责边界先划清

门店上线时，可以把门店编号作为 member 写进 Redis GEO 集合。下面的 key 只放门店位置，不把营业状态、库存和门店名称硬塞进 GEO 数据结构：

GEOADD shop:geo 121.4737 31.2304 shop-1001
GEOADD shop:geo 121.4801 31.2287 shop-1002
GEOADD shop:geo 121.4689 31.2351 shop-1003

查询附近 3 公里的门店时，Redis 可以直接返回 member 和距离：

GEOSEARCH shop:geo FROMLONLAT 121.4737 31.2304 BYRADIUS 3 km ASC WITHDIST

Redis 只负责地理查询条件和距离排序，业务接口还要决定同距离时的次序、是否过滤闭店门店，以及下一页从哪里继续。把这些规则写在接口层，后续换成数据库或搜索服务时更容易复核。

为什么只保存 distance 会漏门店

假设第一批结果的距离是 0.42、0.77、0.77、1.05 公里。如果游标只记录 lastDistance=0.77，下一次用“距离大于 0.77”查询，第二家 0.77 公里的门店会被跳过；如果改成“大于等于”，上一页最后一家又会重复出现。

更稳的规则是：先按 Redis 返回的距离从近到远；距离相同时按门店编号升序；游标保存上一条的 distance 和 shopID，下一页使用二者的联合比较。

Redis 的 GEO 查询本身并不提供“距离 + member”的通用业务游标接口，因此分页通常分两步：先取一个略大的候选窗口，再在应用层做稳定排序和游标裁剪。窗口可以从 pageSize 的 3 到 5 倍开始，用真实门店密度压测后再定。

接口返回的游标应该长什么样

{"items":[{"id":"shop-1002","distanceKm":0.77},{"id":"shop-1011","distanceKm":0.77}],"nextCursor":"eyJkIjowLjc3LCJpZCI6InNob3AtMTAxMSJ9"}

生产接口不要让客户端直接拼接 JSON 游标。服务端应校验游标版本、半径、中心点和排序规则是否与当前请求一致，避免拿着旧城区或旧半径的游标继续翻页。

用距离和门店编号完成一次可重复分页

关键不是某个框架，而是排序和裁剪顺序：先取候选、补齐门店状态，再按同一套比较器排序，最后丢弃游标之前的记录。

candidates := geoSearch(center, radius, limit*4)
items := loadOpenShops(candidates.ids)
for _, item := range items { item.distanceKm = candidates[item.id].distanceKm }
sort.Slice(items, func(i, j int) bool {
    if items[i].distanceKm != items[j].distanceKm { return items[i].distanceKm 

门店状态过滤会造成候选数量变少。若把 limit 直接当成 Redis 查询数量，前几条恰好都是闭店门店时，接口会提前返回空的下一页。候选窗口和最终页大小要分开，且要给“没有更多结果”设置明确判断。

坐标更新和实时列表该怎么取舍

GEO member 的位置发生变化后，它在结果中的相对位置可能立刻改变。用户在同一页面翻第二页时，旧游标不再代表稳定快照。附近门店展示可以接受轻微变化，游标设置短过期时间，刷新后从第一页重新开始；配送计价或门店选择则应记录请求版本，坐标版本变化就返回“列表已更新”；后台导出和对账应先生成固定批次或快照。

距离是展示值，不是计费依据。配送费、服务范围和营业状态仍应由业务服务在最终确认时重新校验，避免看到的附近门店和实际可下单条件不一致。

常见问题：Redis 附近查询分页的几个坑

GEOSEARCH 能直接返回业务排序后的下一页吗？

它能按距离排序并返回距离，但“距离 + 门店编号”的业务游标仍需要应用层统一处理。依赖单一 distance，遇到并列距离就会重复或漏读。

为什么候选数量要大于页面大小？

闭店、暂停服务、标签过滤都会淘汰候选。候选窗口太小，接口可能在还有可用门店时提前结束。

门店移动后旧游标还能用吗？

不能把它当成永久快照。可以给游标绑定中心点、半径和数据版本；版本变化时让客户端重新加载第一页。

附近门店只有几十家，还需要做游标吗？

数据量很小时可以一次取完后在服务端分页，但仍要固定同距离排序和刷新规则，否则前端每次请求仍可能看到顺序抖动。

验收清单

上线前用固定中心点造一组测试数据：两个同距离门店、一个闭店门店、一条会更新坐标的门店，再连续请求第一页和第二页。最终结果应满足：半径外门店不出现、门店不重复、不因状态过滤提前结束、游标参数改变时被拒绝、坐标版本变化时能提示刷新。验收重点就从“Redis 返回了数据”变成了“分页结果可解释、可复查”。