平时业务开发里大家一定都写过“附近的门店”“离我最近的停车场”这类接口。数据量小的时候一条条算经纬度距离还能扛等用户量上来你会发现数据库CPU飙高、查询越来越慢这时候就得认真认识一下MongoDB的地理空间索引Geospatial Index。这是这个系列的第28篇。我不会只贴官方文档而是把原理、用法、还有我实际踩过的坑一起讲明白读完你不仅能上手还能在系统设计时做出更靠谱的判断。这篇内容适合后端开发、全栈工程师也适合刚接触NoSQL的同学。你会搞清楚为什么坐标查询会慢、2d和2dsphere有什么区别、GeoJSON到底怎么存、$near、$geoWithin、$geoIntersects这些查询操作符分别用在什么场景以及生产环境里最容易犯的错。我会尽量用大白话解释原理再配合可直接复制的示例保证你看完就能在自己的项目里试验。地理空间索引到底解决什么问题很多同学第一次接触空间索引脑子里是懵的索引不就是B-tree吗坐标查询不就是在两个字段上查范围吗我一开始也这么想后来才发现完全不是一回事。这一章我先把“为什么要专门搞一个空间索引”讲透。1.1 没有索引时坐标查询是怎么“硬扛”的假设你的orders集合里有几百万条订单每条订单都有buyer_location字段存的是经纬度。现在要查“距离我3公里内的所有订单”最朴素的想法是什么把这几百万条数据的经纬度都取出来一条条用Haversine公式算距离筛掉距离大于3公里的最后再排序。这个方案在数据量小的时候确实能用但有几百万条数据时每一次查询都是全表扫描加实时计算性能可想而知。更麻烦的是传统关系型数据库里常见的B-tree索引对“纬度和经度两个字段同时做距离比较”支撑得很差。你可以分别给latitude建索引、给longitude建索引但查“距离某个点3公里内”的时候需要的是一个二维范围内的点而不是单纯的某个字段大于某个值、小于某个值。你可以把经纬度合在一起理解这是一个二维平面上的“点”而我们要做的是在一个圆圈或多边形里找点。B-tree擅长处理一维区间到了二维空间就力不从心了。打个比方一维索引就像查字典按拼音或者笔画把内容排好序找某个字很快。但二维空间里的“附近的人”查询相当于你在一张地图上画了个圈要快速找出圈里所有标记点。字典的排序方式帮不上忙因为“距离近”这个关系在排序表里根本没有体现。空间索引就是专门为这种“二维邻近查询”设计的结构。1.2 空间索引的核心思路把二维空间切成格子空间索引最核心的思路我理解下来就四个字空间换时间或者更具体一点——网格划分。你可以把整个地球想象成一张大纸先把它切成一个个大小相同的格子每个格子都有一个编号。一个坐标点落在哪个格子里就记下这个格子编号。当你查询“某个点附近”时不需要全图找只需要看这个点所在的格子以及周围几个格子就够了其他不相干的格子直接忽略。这个思路再往前一步就是地理哈希Geohash的概念。每个格子编号其实可以转换成一个字符串比如某市的中心区域可能对应一串类似“wx4g0”的字符串。在这个编码规则里公共前缀越长两个点离得越近。很多数据库的空间索引本质上都在做类似的事情把二维坐标降维成一维可排序的编码然后就能利用类似B-tree的结构快速检索邻近的格子。MongoDB 2dsphere索引并不是简单地套用一种算法它在内部会把地理数据转成一种名为“网格”的层级结构当某一片区域点特别密的时候格子会继续细分有点像地图缩放。你搜“附近”时数据库先定位到粗粒度格子再根据需要往细粒度格子找。这样既保证了查询速度也避免了格子太粗导致范围内候选点太多的问题。理解这个原理你就能明白为什么空间索引能大幅提升查询性能它把“计算距离”变成了“查找格子编号”。距离计算仍然是需要的但只需要对候选集计算而不是对全表计算。1.3 MongoDB里的两类空间索引2d和2dsphereMongoDB里有两种空间索引名字很像用法和能力完全不同。很多老项目踩坑就是因为把这两个搞混了。简单区分2d索引是早期版本提供的平面坐标索引2dsphere索引是后来的“正主”专门用于球面地理坐标。两者到底哪里不一样我整理了一张对比表对比项2d索引2dsphere索引适用的坐标类型legacy坐标对比如{ loc: [100.5, 30.2] }GeoJSON比如{ loc: { type: Point, coordinates: [100.5, 30.2] } }计算模型平面模型把经纬度当平面坐标球面模型基于WGS84参考椭球体距离单位弧度换算麻烦米查询结果直观支持$geoWithin支持用$center或$polygon支持用$centerSphere或$polygon支持$geoIntersects不支持支持支持$nearSphere有限支持原生支持推荐程度新项目不推荐新项目首选我个人的建议非常明确新项目、新集合一律用2dsphere。除非你是在维护一个很多年前的老系统里面的坐标数据是纯数组格式且不方便迁移才继续用2d。因为2dsphere支持GeoJSON、支持球面距离、支持几何相交查询这些都是现代地理业务需要的核心能力。实际项目里还有一个兼容性问题如果你的文档里存的是数组形式的经纬度[longitude, latitude]那建2dsphere索引前需要先把字段改成GeoJSON格式的Point对象。这个改造看着不大但在数据量大的集合上要评估好迁移成本和业务影响别在高峰期直接改线上数据。数据格式与坐标系先弄清经纬度的顺序这是个老生常谈但永远有人踩的坑。我接手过一个项目查“附近的加油站”死活查不出结果排查半天发现数据写入时经纬度顺序反了。这类问题最坑的地方在于它不是程序报错而是查询结果不符合预期不细看很难发现。所以这一章专门讲GeoJSON格式和坐标系。2.1 GeoJSON对象的基本写法2dsphere索引基于GeoJSON格式。什么是GeoJSON通俗讲它就是一套描述地理对象的JSON标准。最常见的类型是Point表示一个点写法如下{ name: 某商圈加油站, location: { type: Point, coordinates: [116.397, 39.908] } }最重要的是coordinates数组里的两个数字第一个是经度longitude第二个是纬度latitude。这个顺序是GeoJSON规范强制要求的跟很多人习惯的“纬度在前、经度在后”完全相反。你写反了MongoDB不会报错但查询结果会跑到地球另一边去。除了Point实际业务里还会用到下面几种GeoJSON类型LineString一条线由两个或更多点连成。适合存轨迹、路线。典型结构是{ type: LineString, coordinates: [[x1, y1], [x2, y2], ...] }。Polygon多边形由一组闭合的坐标点组成。第一个点和最后一个点必须是同一个点否则形状不闭合。适合定义围栏、区域。MultiPoint / MultiLineString / MultiPolygon多个点、多条线、多个多边形。GeometryCollection由多个不同类型的几何对象组成集合。这些类型不是用来凑文档字数的。我后面实战章节会提到Polygon可以做地理围栏LineString可以做路径匹配。你先记住它们的存在后面遇到具体业务就能对号入座。2.2 2dsphere索引的创建方式创建2dsphere索引一条命令就够db.places.createIndex({ location: 2dsphere })location是文档里存GeoJSON对象的字段名类型指定为2dsphere即可。创建成功后可以用getIndexes查看db.places.getIndexes()如果集合里已经有很多数据建索引会耗时比较久建议在业务低峰期操作。但是如果你的字段不是GeoJSON格式比如是普通数组[100.5, 30.2]创建2dsphere索引会报错。这时要么把数据迁移成GeoJSON格式要么改用2d索引。再说一个复合索引的细节。假设你经常这样查询查找某个分类下、某个位置附近的门店。这时可以建复合索引比如db.places.createIndex({ category: 1, location: 2dsphere })这里有一个重要原则空间索引字段在复合索引里尽量放在最后。因为MongoDB的空间查询不仅要做范围匹配还要做距离排序把非空间字段放在前面、空间字段放在后面查询计划能更高效地先通过普通字段过滤再走空间索引计算距离。顺序放反了索引可能也能用但效率不一定最优。我建议每次建完复合索引都用explain验证一下效果别想当然。2.3 坐标系与单位问题坐标系是地理数据里绕不开的概念。MongoDB 2dsphere默认使用WGS84坐标系这是一个全球通用的GPS坐标系绝大多数地图服务商和GPS设备输出的经纬度就是基于这个坐标系。也就是说你直接用手机GPS拿到的经纬度存进去不需要做任何投影转换就能直接用2dsphere做球面距离计算。距离单位上2dsphere查询结果以米为单位这非常友好。比如你要查“5公里范围内的点”直接传maxDistance: 5000即可。2d索引则是基于平面坐标计算距离单位是弧度查询的时候得手动换算弧度乘以地球半径约6371公里才能得到公里数。这个换算本身不难但很容易被忽略。有一个细节值得注意即使使用2dsphere索引MongoDB内部仍然要考虑地球不是完美球体这一事实。WGS84模型下的距离计算在绝大多数业务场景精度已经足够不要指望它在“厘米级”地理测绘场景下替代专业GIS工具。做外卖、打车、社交这类LBS业务完全够用。核心查询操作从“附近的人”到“范围圈人”索引建好了接下来就看怎么查。MongoDB提供了一组地理空间查询操作符分别解决“附近搜索”“圈内搜索”“几何相交判断”三类典型问题。我一个个讲每个都会配上可直接运行的示例。3.1 $near与$nearSphere距离邻近查询$near是使用频率最高的操作符。它的语义是从某个点出发查找附近的其他点结果默认按距离由近到远排序。注意这个排序是查询操作符自带的不需要你再orderBy。最常见的写法是配合2dsphere索引做球面查询db.places.find({ location: { $near: { $geometry: { type: Point, coordinates: [116.397, 39.908] }, $minDistance: 0, $maxDistance: 5000 } } })这段查询会找出距离坐标(116.397, 39.908) 5公里以内的所有地点结果按距离升序排列。$minDistance和$maxDistance单位都是米。如果只想查10公里范围内的把$maxDistance改成10000就行。还有一个容易忽略的点$near查询强制要求对应字段有空间索引否则会直接报错。如果发现$near跑不起来第一反应应该是检查索引。另外$nearSphere可以做球面距离查询它和$near的区别在于$nearSphere专门用于球面模型即使索引是2d也可以配合使用但$near在2d索引上是平面计算。这种查询适合哪些场景典型就是“附近的餐厅”“离我最近的门店”。返回结果自带距离排序刚好满足用户心理预期。3.2 $geoWithin矩形与圆形范围查询$geoWithin表示“在某个几何形状内部”。它不做距离排序只做包含判断。用途上后台运营圈人选人、按区域统计点位、业务规则里“判断某个点是否落在某个园区内”这类场景都会用到它。圆形范围查询这样写db.places.find({ location: { $geoWithin: { $centerSphere: [ [116.397, 39.908], 5 / 6371 ] } } })$centerSphere接收两个参数圆心坐标和半径但半径单位是弧度所以要把公里数除以地球半径6371。这里又是单位坑写错半径会差几千倍。做矩形范围查询可以用$boxdb.places.find({ location: { $geoWithin: { $box: [[116.3, 39.8], [116.5, 40.0]] } } })$box接收左下角和右上角两个点。不过实际业务中矩形用得少更多时候用多边形圈选任意形状区域。多边形查询用$polygondb.places.find({ location: { $geoWithin: { $polygon: [ [116.3, 39.8], [116.6, 39.8], [116.6, 40.1], [116.3, 40.1] ] } } })值得一提的是$geoWithin不强制要求索引。但如果你想查得快点还是建议建好2dsphere索引。没有索引时MongoDB也能完成多边形包含判断只是性能会打折扣。3.3 $geoIntersects判断几何对象是否相交$geoIntersects用于判断两个几何对象是否相交。这里的“相交”包含多种情况点落在面内、线与面交叉、面与面重叠、线与线交叉等。它跟$geoWithin最大的区别是$geoWithin判断“一个点是否在形状内”$geoIntersects判断“两个几何对象是否有交集”。来看一个典型例子用LineString存了一条配送路线想判断这条路线是否穿过某个禁行区域Polygondb.routes.find({ route: { $geoIntersects: { $geometry: { type: Polygon, coordinates: [[ [116.3, 39.8], [116.6, 39.8], [116.6, 40.1], [116.3, 40.1], [116.3, 39.8] ]] } } } })只要route字段是LineString且与这个多边形有交点就会被查出来。这类查询在“配送路线是否进入限行区”“飞行轨迹是否越过边界线”等业务中非常有用。$geoIntersects有几个限制要注意它只能用于2dsphere索引2d索引不支持查询字段和传入的$geometry都必须是GeoJSON格式。如果集合里的数据是旧版数组格式这条查询会直接报错。3.4 aggregate中的$geoNear更灵活的邻近查询如果只是简单查附近地点find加$near就够用了。但复杂业务里经常需要在距离查询的同时做分页、过滤、字段加工这时候find就有点单薄聚合框架里的$geoNear操作符会更顺手。$geoNear长这样db.places.aggregate([ { $geoNear: { near: { type: Point, coordinates: [116.397, 39.908] }, distanceField: distance, maxDistance: 5000, query: { category: 加油站 }, num: 10 } } ])这里要注意$geoNear是聚合阶段它会把结果里加一个distance字段单位同样是米。distanceField指定了该字段的名字你可以在后面的$project或$sort阶段直接引用这个距离字段。而且$geoNear里可以带query直接把“距离条件过滤”在一个阶段完成比find再手工加工方便得多。$geoNear还有一个好处支持分页时求总数。你可以用$facet或$count把“附近10公里内有多少家店”这种问题做成一个聚合查询不用再发多条命令。地理查询和普通聚合操作混在一起业务表达力强了很多。代价是必须在pipeline里第一个或靠前位置使用并且依赖空间索引。如果你要按距离排序又要做一些group、project操作$geoNear基本是标准答案。实战场景设计三个真实业务怎么用地理索引讲完语法很多人还是不知道怎么组合。我直接拆三个从项目里来的场景尽量覆盖典型需求从索引设计到查询语句一起给出来。你可以对着自己的业务找影子。4.1 场景A附近门店搜索这是最经典的需求用户打开App看到附近3公里内的门店列表按距离排序。门店数据存在shops集合里文档结构大致如下{ _id: 1, name: 某连锁咖啡店示例店, category: 咖啡, location: { type: Point, coordinates: [116.397, 39.908] }, rating: 4.5 }索引设计上因为查询条件同时有category和location我会建复合索引db.shops.createIndex({ category: 1, location: 2dsphere })查询语句db.shops.find({ category: 咖啡, location: { $near: { $geometry: { type: Point, coordinates: [116.35, 39.90] }, $maxDistance: 3000 } } }).limit(20)这个查询一次性完成了按类别过滤、按距离范围筛选、按距离排序。limit控制返回条数。如果数据量很大还可以在aggregate里用$geoNear配合$skip做分页但要注意深分页性能问题别offset太大。到这里我一定要提醒一下缓存问题。附近门店查询往往频率很高同一批用户集中在同一区域如果每次都实时跑数据库压力很大。我实际项目里的做法是用Redis缓存区域热点的门店ID列表缓存key按区域网格划分过期时间设置在分钟级别。用户移动导致网格切换时再回源查一次MongoDB。地理索引负责“查得对、查得快”缓存负责“扛得住”两者配合效果最好。4.2 场景B地理围栏与进店监测很多业务需要判断用户是否进入某个“围栏”比如商场推送、车辆进园区提醒、学生到校通知。围栏本质上是Polygon用户位置是Point判断点在多边形内最直观的做法就是用$geoIntersects或者$geoWithin。假设围栏已经存在geofences集合{ _id: 1, name: 某园区围栏, area: { type: Polygon, coordinates: [[ [116.35, 39.80], [116.45, 39.80], [116.45, 39.90], [116.35, 39.90], [116.35, 39.80] ]] } }用户上报了一条位置想知道它落在哪些围栏内可以这样查询db.geofences.find({ area: { $geoIntersects: { $geometry: { type: Point, coordinates: [116.40, 39.85] } } } })这个查询等价于“找出包含这个点的所有多边形”正好是围栏判断的语义。在实现用户进店感知时一般不会让用户端频繁去轮询数据库而是让位置上报服务在写入用户位置时顺手做一次围栏判断命中后把事件写入消息队列再由下游服务处理推送。这样做的好处是地理索引只负责“判断是否命中”不参与推送流程避免阻塞位置上报主链。围栏判断在数据量偏大时会有一些性能压力因为每个Point都要跟所有Polygon做相交计算。优化思路是先按城市、区域做索引前缀或者把围栏数据加载到内存中定期更新。MongoDB的空间索引解决“怎么算”架构层面还得考虑“算哪些”。4.3 场景C轨迹匹配与路径回放有些业务需要分析用户或车辆的轨迹比如外卖配送路径是否偏离路线、跑步轨迹是否经过某些地标。这时LineString类型就能派上用场。假设track_collection集合里存了轨迹{ _id: 100, user_id: u123, track: { type: LineString, coordinates: [ [116.30, 39.80], [116.35, 39.83], [116.40, 39.86], [116.45, 39.89] ] } }想找“经过某片区域的轨迹”直接用$geoIntersects去匹配db.track_collection.find({ track: { $geoIntersects: { $geometry: { type: Polygon, coordinates: [[ [116.38, 39.84], [116.42, 39.84], [116.42, 39.88], [116.38, 39.88], [116.38, 39.84] ]] } } } })这个查询会把区域内所有轨迹LineString捞出来。这里有个细节一条完整的轨迹可能包含几十上百个点存成一个很大的LineString文档会让MongoDB的文档体积变得很大。我建议轨迹按段存储比如每10分钟一段或者按固定点数分段这样单条文档大小可控空间索引的精度也会更好。整条超长线段的空间索引在边缘处的判断可能不够准确拆分后反而更可靠。查询性能上轨迹数量通常很大建议在user_id或时间字段上再加普通索引先缩小候选范围再用地理索引匹配避免对所有历史轨迹做空间计算。这也再次说明地理索引能和普通索引发挥协同作用复合索引设计是关键。常见坑与排查实录这章我集中整理一下实际运维和开发过程中遇到的典型问题。这些问题网上资料零散但真实项目里几乎都会碰到。5.1 经纬度写反了或类型不是GeoJSON现象数据量明明很大但$near查询返回空或者结果明显不对。排查第一步是随机查看一条文档确认location字段到底是什么格式。如果是数组[39.908, 116.397]且没有type字段那要么用2d索引要么把数据批量更新成GeoJSON格式。另一个隐蔽问题是 coordinates数组里出现字符串而不是数字比如[116.397, 39.908]。MongoDB某些版本的驱动对字符串数字容忍度较高但空间索引根本不会命中这种数据。建议写入时严格校验类型经度必须是一个-180到180之间的数字纬度是-90到90之间的数字。写个校验函数比事后清洗省心得多。5.2 索引没命中查询走了全表扫描有时候你明明建了索引但explain结果还是显示COLLSCAN。可能原因有两个。第一查询条件里用的操作符不是地理操作符比如你对location字段用了$in或者字符串比较这没法走空间索引需要改写查询。第二复合索引字段顺序安排不对前缀字段选择不当导致查询计划觉得走普通字段过滤更划算。解决办法是explain看winningPlan如果确实没走索引可以用hint强制指定。但注意hint只是临时手段根本解决还是要调整索引设计。我习惯在写完每条地理查询后都跑一次explain确认 stage 是关键字段。尤其在复合索引场景下索引顺序的影响远比想象中大。5.3 单位算错2d与2dsphere混用这是最常见的坑。$nearSphere在2dsphere索引下maxDistance单位是米同样操作在2d索引下单位是弧度。有些老项目升级时把索引从2d改成2dsphere但查询参数还是原来的“弧度值”结果本来查3公里变成只查了不到1米甚至查不到东西。反过来把米当弧度用范围瞬间变成几千公里。如果你要从2d迁移到2dsphere除了改数据格式还要把查询参数里的弧度换算成米。换算公式很简单公里数 x 1000 米数弧度数 米数 / 6371000地球平均半径。别觉得这个简单生产环境里因为单位问题导致的线上事故我至少见过三次。5.4 大数据量下的性能建议当集合里有上亿条带地理位置的数据时光靠2dsphere索引也不够。我个人的经验是分层设计先按业务维度缩小范围比如按城市、按租户ID分片或分表让每个物理分片的数据量适中。再在分片内建2dsphere索引这样单个查询的候选集就被控制住索引效率更高。距离计算尽量提前不要全表遍历后再算用$geoWithin或$near先圈一个较小的区域再做精确过滤。另外空间索引也有存储和写入开销。索引字段更新时MongoDB需要重新计算网格位置频繁更新位置信息的集合写入性能会受一定影响。对于高并发位置上报类业务可以考虑“批量写入延迟索引”的策略或者用专门的时序数据库存储裸位置数据MongoDB只存储聚合后的结果。这不是说MongoDB不行而是架构上要让最合适的工具做最合适的事。为了便于你排查我整理了一张问题速查表症状可能原因快速排查$near查询报错“no geospatial index”没建索引或索引类型错误db.集合.getIndexes()检查索引查询结果为空但数据存在经纬度顺序写反随机取一条文档看原始坐标查询范围明显偏大或偏小2d和2dsphere单位混用确认索引类型统一为米查询慢explain显示COLLSCAN查询操作符不对或复合索引顺序问题explain查看winningPlan坐标是数组但想用2dsphere字段不是GeoJSON批量更新为GeoJSON结构聚合$geoNear报错$geoNear未放在pipeline靠前位置调整pipeline顺序最后再分享一个我私人的习惯所有地理坐标字段不管前端传的是什么后端都要做一次经纬度合法性和顺序性校验统一在写入层解决格式问题。地理索引本身的用法并不复杂复杂的是数据源头脏、业务层理解错单位、索引设计不合理。把这三道关把住MongoDB的地理空间索引会是一个非常可靠且高效的组件。
