Redis GEOSEARCH 怎么按距离筛选附近点：半径单位、排序与边界结果核对

做“离用户最近的门店”时，Redis GEOSEARCH 的命令看着短，真正容易出错的却是坐标顺序和结果解释：经度、纬度写反，查询仍可能返回结果；把千米误写成米，范围会悄悄缩小一千倍；只看返回列表，又很难发现排序或边界漏点。下面用一组固定门店数据，把命令、返回值和核对方法压缩成一条可复查的路径。

GEOSEARCH 的正确落点是：先用经度、纬度写入同一个 GEO key，再明确选择 BYRADIUS 或 BYBOX、单位和排序；上线前用 WITHDIST 返回距离，并用边界点、反向坐标和重复查询三组数据验收。

先定业务负载：附近门店和地图框选不是同一种查询

Redis 的 GEO 数据适合“候选点初筛”，例如外卖系统先找配送范围内的站点，门店列表再到数据库补营业状态、库存和会员价。它不是完整的地理分析引擎，也不应该把营业时间、库存锁定和价格判断全部塞进 GEOSEARCH。

如果需求是“以用户为中心，找 3 千米内的门店”，使用圆形半径；如果需求是“地图当前视口内的仓库”，使用矩形框。两者返回的点集可能不同，这是查询模型不同，不是 Redis 丢数据。

最小数据集：先把经度、纬度和成员名固定下来

下面的坐标是示例数据，成员名使用稳定的业务 ID。写入时先把数据清空只适用于本地实验；线上不要为验证一个查询删除共享 key。

DEL shop:geo
GEOADD shop:geo 116.397128 39.916527 shop:001
GEOADD shop:geo 116.407526 39.904030 shop:002
GEOADD shop:geo 116.384120 39.913818 shop:003
GEOADD shop:geo 116.420200 39.915000 shop:004

ZRANGE shop:geo 0 -1 WITHSCORES

这里最值得单独检查的是第一行坐标：116.397128 是经度，39.916527 是纬度。Redis 接受的是经度在前、纬度在后的地理坐标；如果应用对象字段名是 lat、lng，拼接命令时要明确写成 lng lat，不要直接把对象字段顺序传进去。

圆形范围：BYRADIUS 配单位，再决定是否返回距离

以天安门附近的示例坐标为中心，查询 3 千米内的门店：

GEOSEARCH shop:geo
  FROMLONLAT 116.397128 39.916527
  BYRADIUS 3 km
  WITHCOORD WITHDIST
  ASC

命令行里可以写成一行，换行只是为了阅读。FROMLONLAT 后面仍然是经度、纬度；BYRADIUS 3 km 表示半径 3 千米。若业务字段保存的是米，应用层可以传 3000 m，但不要让同一个接口一会儿传米、一会儿传千米而不在参数名中体现。

WITHDIST 会把每个成员与中心点的距离带回来，ASC 则把近点排在前面。生产接口最好直接把这个距离转成明确字段，例如 distance_km，不要让客户端猜当前单位。

矩形范围：BYBOX 解决视口查询，但排序仍要显式写

地图拖动时，前端通常能给出视口宽、高。此时可以用矩形查询：

GEOSEARCH shop:geo
  FROMLONLAT 116.397128 39.916527
  BYBOX 6 4 km
  WITHDIST WITHCOORD
  ASC

这里的 6 4 km 表示以中心点为基准的矩形宽高，不是半径。视口需求用它更贴近用户看到的地图，但“距离最近”仍然需要 ASC，否则返回顺序不能作为推荐顺序使用。

如果接口要返回固定数量，追加 COUNT 20。需要注意，限制返回数量不是把所有点查出来之后再由客户端排序的替代品；应先明确 Redis 端的排序语义，再在响应中记录是否还有下一批数据。

方案取舍：GEOSEARCH 只做空间初筛，业务过滤放在后面

附近查询通常有三层条件：空间范围、距离排序、业务可用性。第一层交给 GEOSEARCH，第二层用 WITHDIST ASC，第三层再批量查询门店状态。这样可以避免把“已打烊门店”误当成 Redis 地理索引异常。

• 只需要附近候选点：返回成员名即可，减少响应体。
• 需要展示“距离”：必须使用 WITHDIST，并固定单位。
• 需要地图标记：追加 WITHCOORD，但不要把 Redis 返回坐标当成业务地址。
• 需要强一致库存或营业状态：先取候选 ID，再查数据库或缓存中的实时状态。

三组验收：边界、单位和排序一次查清

第一组测试专门放边界点。准备一个已知距离接近 3 千米的成员，分别用 3 km 和略小于 3 千米的半径查询，记录它是否按预期从结果中进出。不要只用一个明显在中心附近的点，那只能证明命令能返回数据。

第二组测试检查单位。让同一请求分别使用 3000 m 和 3 km，两次成员集合应该一致；如果一个结果很多、一个结果为空，优先检查请求参数序列化和单位字段。

第三组测试检查排序与坐标反转。带上 WITHDIST 后，解析出的距离应当单调不下降；把中心点的经纬度故意交换，结果应该明显变化。这个反向测试能抓住“字段顺序写反但仍有返回”的隐蔽问题。

# 近到远，并返回距离
GEOSEARCH shop:geo FROMLONLAT 116.397128 39.916527 BYRADIUS 3 km WITHDIST ASC

# 对照：单位等价性
GEOSEARCH shop:geo FROMLONLAT 116.397128 39.916527 BYRADIUS 3000 m WITHDIST ASC

生产边界：坐标失真、数据过期和结果分页要单独处理

GPS 坐标并不总是可靠。定位权限关闭、基站定位漂移或前端传入默认值时，GEOSEARCH 仍可能给出看似合理的点。接口入口应检查经度是否在 -180 到 180、纬度是否在 -90 到 90，并拒绝明显的默认坐标。

门店关闭、仓库搬迁和配送范围变化也不能靠 GEO key 自己解决。成员删除或坐标更新要和门店状态变更绑定；候选结果拿到后再做一次状态核对。对于大量结果，使用 COUNT 控制单次返回，避免把整个城市的点一次性拉到应用层。

如果产品需要跨页浏览附近点，先确认用户接受“查询期间新点可能进入前面”的实时语义。GEOSEARCH 本身不是快照分页协议，不能只给一个 offset 就承诺稳定分页。

常见问题

GEOSEARCH 的坐标为什么经常写反？

因为很多地图 SDK 的对象字段习惯先写纬度。Redis 命令要求经度在前、纬度在后，建议在适配层显式使用 lng, lat 两个变量名。

BYRADIUS 和 BYBOX 应该怎么选？

以用户为中心按距离找附近点用 BYRADIUS；地图视口或矩形区域筛选用 BYBOX。不要把矩形宽高当成圆形半径解释。

为什么返回了附近点，却没有按最近顺序排列？

范围命中和排序是两件事。查询里追加 ASC，并用 WITHDIST 返回距离，客户端再把距离字段映射到明确单位。

Redis GEOSEARCH 能直接过滤营业中的门店吗？

它主要负责空间检索。营业状态、库存和权限等业务条件应在拿到成员 ID 后再批量核对，避免地理索引和业务状态互相污染。

落地清单：把空间查询写成可检查的接口契约

接口文档至少写清中心点字段顺序、允许的范围、半径单位、圆形还是矩形、排序方向、距离字段单位和业务状态的二次过滤位置。上线前固定一组边界数据，把“3 km 与 3000 m 等价”“距离单调不下降”“经纬度交换会改变结果”写成自动化测试，后续改客户端参数时才不会靠肉眼排查。