Redis GEO怎样按距离查询附近门店并控制结果数怎样完成一个可复用的最小示例

如果业务只是要回答“某个坐标附近有哪些门店”，Redis GEO 可以把坐标写入一个地理索引，再用 GEOSEARCH 按圆形半径查询。控制返回数量的关键是 COUNT，控制最近优先的关键是 ASC，想同时拿到距离则加上 WITHDIST。

官方地址：https://redis.io/docs/latest/develop/data-types/geospatial/

最小可复用组合是：先用 GEOADD stores:geo 经度 纬度 门店名 建索引，再用 GEOSEARCH ... FROMLONLAT ... BYRADIUS ... ASC COUNT 3 WITHDIST 查询。COUNT 3 是最多返回三条，不代表半径内一定有三条。

GEOADD 和 GEOSEARCH 分别做什么

Redis GEO 的成员可以理解为“带经纬度的门店标识”。写入时要明确四个值：索引 key、经度、纬度和成员名。查询时再提供中心点、半径和单位。门店营业时间、地址、库存等业务字段不要硬塞进 GEO 成员名，通常由成员名再关联 Hash 或数据库记录。

本篇使用 stores:geo 作为索引，使用 store:river、store:station 和 store:park 作为示例成员。经度在前、纬度在后，是后面最容易写反的地方。

先用 redis-cli 完成一个最小查询

先写入三家门店，再围绕一个查询中心点查找 5 千米内的门店。命令中的 ASC 表示距离从近到远，WITHDIST 让结果携带距离，COUNT 3 把返回条数限制为最多三条。

# 写入门店坐标：参数顺序固定为经度、纬度、成员名
GEOADD stores:geo 116.397128 39.916527 store:river
GEOADD stores:geo 116.407526 39.904030 store:station
GEOADD stores:geo 116.367777 39.900000 store:park

# 从查询中心按半径找附近门店，最多返回三条并附带距离
GEOSEARCH stores:geo FROMLONLAT 116.397128 39.916527 BYRADIUS 5 km ASC COUNT 3 WITHDIST

返回结果的具体距离会由坐标计算得出，展示形式通常是成员名与距离成对出现。不要把这个距离当成驾车路线距离；GEO 给出的是地理位置之间的距离，路线规划仍需要交给地图或路网服务。

1) 1) "store:river"
   2) "0.0000"
2) 1) "store:park"
   2) "1.4..."
3) 1) "store:station"
   2) "2.1..."

上面的输出只是字段形状示意，实际排序应以 Redis 返回为准；示例中如果距离数字与成员顺序不一致，说明示意坐标不应被当作固定运行结果。

把查询封装成可复用的 Go 函数

Go 服务中可以把“写入门店”和“按坐标查询”拆成两个函数。下面使用 github.com/redis/go-redis/v9 的命令封装，重点是让半径、单位和返回条数成为参数，同时在每次调用中保留上下文和错误处理。

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/redis/go-redis/v9"
)

// NearbyStores 写入示例门店，并返回中心点附近最多 limit 家门店。
func NearbyStores(ctx context.Context, rdb *redis.Client, lon, lat, radius float64, unit string, limit int) ([]redis.GeoLocation, error) {
    // 成员名只保存稳定标识，门店详情可在 Hash 或数据库中按 ID 补查。
    locations := []*redis.GeoLocation{
        {Name: "store:river", Longitude: 116.397128, Latitude: 39.916527},
        {Name: "store:station", Longitude: 116.407526, Latitude: 39.904030},
        {Name: "store:park", Longitude: 116.367777, Latitude: 39.900000},
    }
    if _, err := rdb.GeoAdd(ctx, "stores:geo", locations...).Result(); err != nil {
        return nil, fmt.Errorf("写入门店坐标失败: %w", err)
    }

    // COUNT 代表最多返回多少条；ASC 保证近点优先，WITHDIST 返回距离。
    result, err := rdb.GeoSearchLocation(ctx, "stores:geo", lon, lat, &redis.GeoSearchLocationQuery{
        Radius:    radius,
        RadiusUnit: unit,
        Sort:      "ASC",
        Count:     limit,
        WithDist:  true,
    }).Result()
    if err != nil {
        return nil, fmt.Errorf("查询附近门店失败: %w", err)
    }
    return result, nil
}

func main() {
    // 地址、超时和认证信息应从服务配置注入，这里只保留连接对象的形状。
    rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
    defer rdb.Close()

    stores, err := NearbyStores(context.Background(), rdb, 116.397128, 39.916527, 5, "km", 3)
    if err != nil {
        log.Fatal(err)
    }
    for _, store := range stores {
        fmt.Printf("%s %.2f km\\n", store.Name, store.Dist)
    }
}

这个示例的调用名和字段以所用 go-redis 版本为准；如果项目使用的客户端版本没有 GeoSearchLocation，可以退回客户端提供的原始命令调用，但查询语义仍然是 GEOSEARCH 的 FROMLONLAT、BYRADIUS、ASC、COUNT 和 WITHDIST。

用 COUNT 控制数量，别把它当成精确分页

COUNT 3 的含义是“最多取三条符合条件的成员”。半径内只有一条时，Redis 不会为了凑数返回范围外的门店；半径内没有成员时，结果就是空集合。

如果接口要求最近门店优先，保留 ASC；如果只关心任意一批候选而不要求按距离完整排序，可以评估 ANY，但它改变的是搜索提前结束的取舍，不应和“严格最近”混用。

生产环境最容易踩到的四个边界

• 经纬度顺序：GEOADD 和 FROMLONLAT 都是经度在前、纬度在后。把两者交换后，命令可能仍能执行，但结果会落到错误位置。
• 单位要统一：半径可以使用米、千米、英里等命令支持的单位。接口层建议固定一种单位，并在参数命名中体现，例如 radiusKm。
• 成员与详情分离：GEO 负责位置索引，门店名称、营业状态、库存和价格应在 Hash 或业务数据库中维护，避免把易变信息拼进成员名。
• 查询复杂度要匹配：附近点、半径和简单排序适合 GEO；如果要做复杂的地理过滤、全文检索或多条件搜索，应重新评估 Redis Search 或专门的空间数据库。

一张表记住这组命令

常见追问

COUNT 能保证每次返回固定三家吗？

不能。它是数量上限，结果数还受半径、坐标范围和当前索引成员影响。

GEOSEARCH 返回的是道路距离吗？

不是。它基于地理坐标计算距离，不能替代驾车、步行或骑行路线服务。

为什么查询结果看起来离中心很远？

先检查经纬度顺序和单位，再确认写入坐标与查询中心使用的是同一坐标系。最后再检查是否把半径单位从米误写成了千米。