Redis GEOSEARCH 按距离过滤时单位怎么选择

Redis GEOSEARCH 的距离单位要和业务输入保持同一套约定。附近门店通常用千米，配送半径或步行范围更适合用米；英制数据才选择英尺或英里。单位不是展示层的后缀，而是 BYRADIUS、BYBOX 过滤条件的一部分，数值与单位配错，命中集合就会直接变样。

官方地址：https://redis.io/docs/latest/commands/geosearch/

先把单位和查询形状定下来

GEOSEARCH 先接收一个来源位置，再接一个空间过滤器。来源可以是已有成员，也可以是 FROMLONLAT longitude latitude；过滤器则在 BYRADIUS radius unit 和 BYBOX width height unit 中二选一。四个单位的含义很直接：M 是米，KM 是千米，FT 是英尺，MI 是英里。

BYRADIUS 表示圆形距离范围，BYBOX 表示宽高范围。不要把矩形的宽高当成一个“半径”理解；如果产品需求说“中心点周围 5 千米”，通常先用 BYRADIUS 5 KM，而不是随意改成 BYBOX 5 5 KM。

用最小命令验证数值和单位

先放入四个距离层级不同的成员。下面是 shell 命令，反斜杠用于换行，行首注释说明每组命令的目的：

# 写入测试点：经度在前、纬度在后，故意保留一个较远成员
redis-cli GEOADD shop:geo 116.3974 39.9093 shop-near \
  116.4050 39.9140 shop-mid \
  116.4300 39.9150 shop-edge \
  116.5200 39.9500 shop-out

# 先确认成员坐标，排除经纬度写反造成的假问题
redis-cli GEOPOS shop:geo shop-near shop-mid shop-edge shop-out

以中心点搜索 5 千米内的成员，可以把单位写成 KM，再用 WITHDIST 让返回结果带上距离：

# 圆形半径为 5 千米；ASC 让近点排在前面，最多取 3 个
redis-cli GEOSEARCH shop:geo FROMLONLAT 116.3974 39.9093 \
  BYRADIUS 5 KM ASC COUNT 3 WITHDIST

如果接口已经把半径统一成米，就写成 BYRADIUS 5000 M。不要同时传“5000”和“KM”，也不要先在业务层把 5 千米转成 5000 后又保留原单位标签。参数应当是一个成对的数据：数值加单位。

用等价单位做一次交叉核对

单位选择最容易出错的地方，是调用方和 Redis 之间各自做了一次换算。可以用等价值做一次人工核对：

# 5 KM 与 5000 M 表示同一个米制半径，用于检查传参转换
redis-cli GEOSEARCH shop:geo FROMLONLAT 116.3974 39.9093 \
  BYRADIUS 5 KM ASC WITHDIST

redis-cli GEOSEARCH shop:geo FROMLONLAT 116.3974 39.9093 \
  BYRADIUS 5000 M ASC WITHDIST

两次查询的成员集合和顺序应该一致，距离数值只会因为单位不同而换一种表达。若第一条命中很多、第二条几乎为空，优先检查单位拼接、浮点转换和半径字段，而不是先怀疑 GEO 索引。

把单位边界带回接口设计

生产接口最好在入口就确定一种内部单位，例如统一使用米，并在参数对象里同时保存 radius 和 unit。转换时限制正数、设置合理上限，并拒绝未知单位；不要让每个控制器自由决定用米还是千米。

# 只允许白名单单位，避免把任意字符串拼进 Redis 命令
case "$UNIT" in
  M|KM|FT|MI) ;;                 # 通过白名单后才继续
  *) echo "unsupported distance unit" >&2; exit 2;; # 无效输入立即失败
esac

# 命令参数保持“数值 + 单位”成对出现
redis-cli GEOSEARCH shop:geo FROMLONLAT "$LON" "$LAT" \
  BYRADIUS "$RADIUS" "$UNIT" ASC WITHDIST

还要确认目标 Redis 版本支持 GEOSEARCH；官方文档标注该命令自 Redis 6.2.0 起提供。空结果并不一定是单位错误，也可能是坐标不在数据范围、半径上限过小，或者成员根本没有被 GEOADD 成功写入。

常见问题

Redis GEOSEARCH 的单位可以写小数吗？

单位标记本身使用文档规定的 M、KM、FT、MI；半径数值可以按业务精度传递。接口层应先做范围和精度约束。

为什么 5 KM 和 5000 M 的距离结果不完全一样？

先看命中集合是否一致，再看显示值的小数位、序列化和排序。若集合也明显不同，通常是转换重复、坐标不一致或两次请求使用了不同的中心点。

什么时候应该用 BYBOX？

只有需求明确是经纬度周围的矩形宽高时才用它；“附近多少千米”更符合 BYRADIUS 的圆形语义。

总结

选择 GEOSEARCH 单位时，先看业务输入的自然单位，再把数值与单位作为一个不可拆开的参数传给 BYRADIUS 或 BYBOX。用 WITHDIST 核对返回值，用 5 KM 与 5000 M 做交叉测试，再检查坐标顺序、查询形状和版本支持，距离过滤就有了可复现的判断标准。