Mongoose GeoJSON 实战指南在 MongoDB 中存储与查询地理位置数据【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongooseGeoJSON 是存储地理点Point与多边形Polygon等地理对象的开放格式MongoDB 原生支持基于 GeoJSON 的地理空间查询。本文以 docs/geojson.md 为主线结合 mongoose 仓库中的 lib/query.js、lib/aggregate.js 源码与 test/geojson.test.js 测试用例系统讲解如何在 Mongoose Schema 中定义 GeoJSON 字段、复用点/多边形结构以及如何使用$geoWithin、within()、$near、$geoNear和 2dsphere 索引完成高效的地理查询。读完本文你将掌握一套可直接复制运行的地理数据建模与查询方案。一、GeoJSON 基础Point 是最简单的结构GeoJSON 中最基础的结构是点Point。下面的示例表示旧金山的大致位置注意GeoJSON 坐标数组中经度在前、纬度在后这与人们习惯的纬度, 经度书写顺序恰好相反{ type : Point, coordinates : [ -122.5, 37.7 ] }其中coordinates是一个长度为 2 的数字数组[-122.5, 37.7]依次为经度longitude与纬度latitude。GeoJSON 规范要求点坐标必须写成[经度, 纬度]的顺序Schema 定义与业务代码中都应严格遵循这一点否则查询结果会南辕北辙。二、定义 Point Schema在 Mongoose 中定义一个location字段为 GeoJSON 点的 Schemaconst citySchema new mongoose.Schema({ name: String, location: { type: { type: String, // 不要写成 { location: { type: String } } enum: [Point], // location.type 必须是 Point required: true }, coordinates: { type: [Number], required: true } } });这里的要点是内层字段名也叫type因此外层必须写成type: { type: String, enum: [Point], required: true }的形式。若写成{ location: { type: String } }Mongoose 会把它解析成普通的字符串字段而不是嵌套的{ type, coordinates }结构这是定义 GeoJSON 字段时最容易踩的坑。从 Schema 校验的角度看enum: [Point]限定了location.type只允许取值Point从数据层面保证存入的是合法 GeoJSON 点coordinates: { type: [Number], required: true }约束坐标为数字数组且必填。三、用子文档复用 pointSchema在实际项目中往往有多个集合都需要存点城市、餐厅、景点……。借助 子文档subdocuments 机制可以把pointSchema抽出来一次性定义、随处复用const pointSchema new mongoose.Schema({ type: { type: String, enum: [Point], required: true }, coordinates: { type: [Number], required: true } }); const citySchema new mongoose.Schema({ name: String, location: { type: pointSchema, required: true } });这样的好处是点结构的约束枚举、必填、坐标类型集中在一处维护location字段在多处引用时行为完全一致。在仓库的 test/geojson.test.js 中正是以这种复用的pointSchema来构造City模型的。四、定义 Polygon Schema三重嵌套数组多边形Polygon用来在地图上表示任意形状的区域。下面这个 GeoJSON 矩形近似了美国科罗拉多州的边界{ type: Polygon, coordinates: [[ [-109, 41], [-102, 41], [-102, 37], [-109, 37], [-109, 41] ]] }多边形之所以棘手是因为它的坐标是三重嵌套数组最外层是环ring的数组每个环由多个点组成每个点又是一个[经度, 纬度]数组。注意第一个点与最后一个点相同以闭合多边形。对应的 Mongoose Schema 定义const polygonSchema new mongoose.Schema({ type: { type: String, enum: [Polygon], required: true }, coordinates: { type: [[[Number]]], // 数字的数组的数组的数组 required: true } }); const citySchema new mongoose.Schema({ name: String, location: polygonSchema });核心就是type: [[[Number]]]这个三重嵌套数组类型它精确匹配 Polygon 的坐标结构。Mongoose 会按此结构对坐标数据做类型校验与序列化保证写入数据库的是规范的多边形坐标。五、地理空间查询$geoWithin 与 within() 辅助方法Mongoose 查询支持与 MongoDB 驱动完全一致的地理空间查询操作符。例如下面的脚本先存入一个location为丹佛市 GeoJSON 点的city文档再用 MongoDB 的$geoWithin操作符查询科罗拉多州多边形内的所有文档const City db.model(City, new Schema({ name: String, location: pointSchema })); const colorado { type: Polygon, coordinates: [[ [-109, 41], [-102, 41], [-102, 37], [-109, 37], [-109, 41] ]] }; const denver { type: Point, coordinates: [-104.9903, 39.7392] }; return City.create({ name: Denver, location: denver }). then(() City.findOne({ location: { $geoWithin: { $geometry: colorado } } })). then(doc assert.equal(doc.name, Denver));$geoWithin判断查询点是否位于给定几何图形内部配合$geometry传入 Polygon 即可实现区域检索。该用例在 test/geojson.test.js 中有完整验证。Mongoose 还提供了within()辅助方法它是$geoWithin的便捷写法const denver { type: Point, coordinates: [-104.9903, 39.7392] }; return City.create({ name: Denver, location: denver }). then(() City.findOne().where(location).within(colorado)). then(doc assert.equal(doc.name, Denver));从 lib/query.js 的源码注释可以看到within()定义了$within/$geoWithin参数并且从 Mongoose 3.7 起查询一律使用$geoWithin它与旧的$within100% 向后兼容。within()必须在where()之后调用并支持多种几何形式// 矩形框box左下角 右上角 query.where(loc).within().box(lowerLeft, upperRight); // 圆形circle圆心 半径 query.where(loc).within().circle(area); // 多边形polygon query.where(loc).within().polygon([10, 20], [13, 25], [7, 15]); // 球面圆形区域 query.where(loc).within().centerSphere(area); // 直接传入 GeoJSON 几何对象 query.where(loc).within({ type: LineString, coordinates: [...] }); // 综合形式 query.where(loc).within({ center: [50, 50], radius: 10, unique: true, spherical: true }); query.where(loc).within({ box: [[40.73, -73.9], [40.7, -73.988]] }); query.where(loc).within({ polygon: [[], [], [], []] });此外还有配套的intersects()几何相交判断与geometry()方法例如query.where(loc).intersects().geometry({ type: Polygon, coordinates: polyA })可用于判断两个几何图形是否重叠。若你的 MongoDB 版本过旧MongoDB 2.4 之前可以通过mongoose.Query.use$geoWithin false回退到旧的$within语法这一开关同样定义在 lib/query.js。六、距离查询$near 与 $geoNear若要做离我最近这类按距离排序的查询MongoDB 提供了$near查询操作符。Mongoose 的near()辅助方法支持多种调用形式源码见 lib/query.js// 形式一传入 { center, maxDistance, spherical } query.where(loc).near({ center: [10, 10], maxDistance: 5, spherical: true }); // 形式二路径 参数对象 query.near(loc, { center: [10, 10], maxDistance: 5 }); // 形式三兼容旧版的坐标/经纬度拆分写法 query.near([1, 1]); // 直接传坐标数组 query.near(1, 1); // 传两个数字 query.near(loc, [1, 2]); // 路径 坐标数组在 test/geojson.test.js 中可以看到$near与 2dsphere 索引的强绑定关系若 Schema 上没有 2dsphere 索引$near查询会直接报错unable to find index for $geoNear query因此测试里必须先City.init()确保索引建好再查询。在聚合管道Aggregation Pipeline场景下Mongoose 通过 lib/aggregate.js 中的Aggregate#near()封装$geoNear阶段。注意$geoNear必须是管道的第一阶段const docs await City.aggregate().near({ near: { type: Point, coordinates: [40.724, -73.997] }, distanceField: dist.calculated, // 必填距离写入的字段名 maxDistance: 0.008, query: { type: public }, includeLocs: dist.location, spherical: true });从源码可见near()内部会校验参数非空、必须包含near属性且 GeoJSON 点的coordinates必须是长度不小于 2 的纯数字数组然后生成{ $geoNear: arg }追加到管道。对应测试见 test/aggregate.test.js传入near: { type: Point, coordinates: [1, 2] }后管道被构造成[{ $geoNear: { near: { type: Point, coordinates: [1, 2] } } }]。必须牢记$near查询操作符和$geoNear聚合阶段都强制要求 2dsphere 索引否则 MongoDB 会拒绝执行查询。七、2dsphere 地理空间索引2dsphere 索引用于加速球面上的地理空间查询。在 Mongoose 中定义 GeoJSON 字段的 2dsphere 索引有两种方式。方式一字段级index选项const denver { type: Point, coordinates: [-104.9903, 39.7392] }; const City db.model(City, new Schema({ name: String, location: { type: pointSchema, index: 2dsphere // 在 City.location 上创建 2dsphere 索引 } })); return City.create({ name: Denver, location: denver }). then(() City.findOne().where(location).within(colorado)). then(doc assert.equal(doc.name, Denver));index: 2dsphere是声明式写法City.init()或模型首次使用触发自动建索引时会在location字段上创建球面地理索引。方式二Schema#index()方法citySchema.index({ location: 2dsphere });两种方式等价后者更便于把全部索引集中管理。凡是需要$geoWithin、$near、$geoNear高性能执行的字段都应提前创建 2dsphere 索引数据量增长后缺少索引的地理查询会产生全表扫描性能急剧下降。八、完整流程与测试验证将以上要点串成一条完整链路定义pointSchema→ 嵌入业务 Schema → 写入 GeoJSON 点 → 建 2dsphere 索引 → 区域/距离查询。仓库中的 test/geojson.test.js 是官方对这一整套流程的自动化验证包含四个用例测试用例验证内容对应源码位置driver query用$geoWithin$geometry查询多边形内的点test/geojson.test.jswithin helper用within()辅助方法等价实现test/geojson.test.jsindex字段级index: 2dsphere下查询可正常执行test/geojson.test.jsnear$near依赖 2dsphere 索引无索引即报错test/geojson.test.js写业务代码时可以直接把文档中的示例搬进自己的项目配合City.init()确认索引就绪后再执行地理查询即可复现全部行为。九、实践要点小结经度在前纬度在后GeoJSON 坐标恒为[经度, 纬度]切勿写反。内层type命名冲突GeoJSON 字段的内层属性名为type必须用type: { type: String, enum: [...] }的写法。Polygon 用三重嵌套数组coordinates声明为[[[Number]]]。复用优先把pointSchema/polygonSchema抽成独立 Schema通过子文档嵌入各处复用见 docs/subdocs.md。区域查询用$geoWithin/within()距离查询用$near/$geoNear二者都要求 2dsphere 索引。$geoNear必须是聚合管道第一阶段且distanceField必填。旧版 MongoDB 兼容可通过Query.use$geoWithin false回退到$withinlib/query.js。按照上述方案你可以在 Mongoose 中完整落地存储地理对象 区域筛选 距离排序的地理能力实现附近的店铺、围栏内的车辆、行政区划统计等典型业务场景。【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考