很多人第一次接触 MongoDB都是在项目里被字段老变、表结构改不动这件事逼过来的。我最开始也一样拿着关系型数据库的思维去用建了一堆看起来像表的集合写出来的查询全表扫描数据量一上万就开始卡。后来花了些时间把文档模型、索引和执行计划这几块重新捋了一遍才发现这东西上手门槛确实低但想用得舒服完全是另一回事。这篇就按我自己带人、自己踩坑的顺序把 MongoDB 从装好到能写出一条像样的查询这条链路完整走一遍重点讲清楚每个操作为什么这么写而不是把官方文档翻译一遍。适合刚接手一个 MongoDB 项目、或者准备在下一个需求里引入它的朋友不管你是写后端还是做数据分析跟着走一遍基本能跑通。1. 先把文档模型这件事想明白别拿它当关系库用我在代码评审里见过太多次这种情况一个集合里全是{_id, type, ...}这种结构然后靠type字段去区分不同实体查的时候要写一堆if type order。这就是典型的把关系型思维硬搬过来。文档模型的核心价值在于把一次业务读取需要的数据放在一起而不是把数据拆得越细越规范。1.1 一条文档长什么样和一行记录差在哪里关系库里一行记录的所有字段都是扁平标量复杂结构必须拆表。MongoDB 的一条文档本质是一个 BSON 对象字段值可以是字符串、数字、日期也可以直接是嵌套对象或者数组。举个实际点的例子一个商品在关系库里大概要拆成商品表、SKU 表、属性表三张而在文档模型里完全可以是一条{ _id: ObjectId(...), title: 某款机械键盘, price: 399, tags: [办公, 无线, 静音], specs: { switchType: 红轴, layout: 87键, weight: 780 }, skus: [ { code: K87-W, color: 白, stock: 120 }, { code: K87-B, color: 黑, stock: 45 } ], createdAt: ISODate(2024-03-11T08:20:00Z) }读一个商品详情一条findOne就够了不需要三次 join。这就是文档模型最直接的收益读路径变短。代价是写入时可能要更新整个文档以及同一份数据在不同文档里可能出现冗余。这个取舍后面第 6 节会展开讲。这里有个细节容易被忽略_id默认是ObjectId它不是一个随机串结构上包含 4 字节时间戳、5 字节随机值、3 字节自增计数器。这意味着_id本身就带创建时间信息你甚至可以用ObjectId(...).getTimestamp()反推文档的创建时间。我在做数据排查的时候经常用这招比额外加一个createdAt字段还快。1.2 什么场景适合什么场景别硬上不是所有项目都该上 MongoDB。我自己的判断标准大概是这样场景特征更适合的选择原因字段结构频繁变化每个租户字段还不一样文档模型不需要频繁 DDL应用层控制结构读多写少一次读取要拼好几张表文档模型内嵌减少 join读放大明显强事务、多表强一致性转账类关系型跨文档事务开销大逻辑复杂大量多对多、需要灵活任意维度关联查询关系型文档模型对多对多不友好日志、埋点、内容、商品、配置文档模型结构松、写入吞吐要求高报表类复杂聚合、窗口函数关系型或专用分析库聚合管道能力有限复杂 SQL 更顺手一句话总结读模式相对固定、写模式灵活多变的结构适合文档模型。如果你的查询需求是任意维度随便组合那关系库的优化器还是更靠谱。2. 环境从零跑起来安装、启动到第一次握手装 MongoDB 这件事本身不难难的是新手容易在几个环节卡住服务没起来、端口被占、认证没配好、连上了却没权限。我把这条链路拆细一点。2.1 本地起一个实例的几种方式最省事的是容器方式一条命令搞定数据挂到本地目录删了容器数据还在docker run -d \ --name mongo-dev \ -p 27017:27017 \ -v /data/mongo:/data/db \ -e MONGO_INITDB_ROOT_USERNAMEadmin \ -e MONGO_INITDB_ROOT_PASSWORDdevpass123 \ mongo:7.0注意MONGO_INITDB_ROOT_USERNAME这个环境变量只有在数据目录为空、首次初始化时才生效。我见过有人把数据目录挂到已有数据的路径然后发现环境变量里的账号密码根本没建上连都连不进去排查半天。要么用全新的空目录要么手动进容器建用户。如果用包管理器安装Linux 上装完之后默认是mongod服务用systemctl start mongod启动配置文件一般在/etc/mongod.conf默认只监听127.0.0.1。这个默认值是有意为之的不要在没配认证的情况下把bindIp改成0.0.0.0我在一些内网环境里见过裸奔的实例任何人都能连上去删库。配置文件里几个值得改的点net: port: 27017 bindIp: 127.0.0.1 storage: dbPath: /var/lib/mongo wiredTiger: engineConfig: cacheSizeGB: 2cacheSizeGB默认会吃掉可用内存的一半减 1G。在容器里如果没设内存限制它可能按宿主机的内存来算结果被 OOM kill。容器部署时建议显式设置这个值一般给容器内存的 50% 到 60%。2.2 连接串里的每个参数都值得看一遍连接串看着简单但每个参数背后都有含义mongodb://admin:devpass123localhost:27017/appdb?authSourceadminmaxPoolSize50retryWritestrueauthSourceadmin认证库。用户建在哪个库这里就写哪个。建在admin库却连业务库时忘了加这个参数报的错是Authentication failed很容易误判成密码错。maxPoolSize连接池上限默认 100。小服务给 20 到 50 就够给太大会把数据库连接数打满。retryWritestrue遇到网络抖动或主节点切换时自动重试一次。副本集环境建议开着单机开了也无害。要注意retryWrites不是万能的它只对幂等或可重试的写操作生效而且是在驱动层重试如果第一次写其实成功了只是响应丢了重试可能造成重复写入。所以业务上需要唯一性的字段索引该建还是要建。2.3 用 mongosh 还是图形工具mongosh是官方现在的命令行客户端语法上是 JS 环境可以写循环、可以定义变量调试的时候非常顺手。图形工具比如一些可视化客户端适合看数据和临时改两条记录但复杂查询还是命令行快。一个我常用的技巧是在 mongosh 里定义几个快捷函数// 查看当前库所有集合及大小 db.getCollectionNames().forEach(function(c) { var s db.getCollection(c).stats(); print(c \t s.count \t (s.size / 1024 / 1024).toFixed(2) MB); });排查哪个集合在疯涨的时候这行比翻监控面板快多了。3. 把增删改查写成肌肉记忆操作符才是重点CRUD 谁都会写但写得好不好差别全在对操作符的理解上。我见过太多人把读出来、在应用里改、再整体写回去当成标准做法结果并发一上来就丢更新。3.1 插入单条、批量与顺序的取舍db.orders.insertOne({ orderNo: A1001, amount: 199, status: paid }); db.orders.insertMany([ { orderNo: A1002, amount: 88, status: paid }, { orderNo: A1003, amount: 320, status: unpaid } ], { ordered: false });ordered: false这个参数很关键。默认是有序插入一旦中间某条失败比如唯一索引冲突后面的全部不执行。设为false之后失败的跳过成功的照常写入返回值里会带上失败的索引列表。批量导入数据的场景基本都应该关掉有序否则一条脏数据能让整批任务中断。但要注意ordered: false下驱动可能会并发写多个分片或节点失败的那条不会自动重试你的代码需要自己处理返回值里的writeErrors。3.2 查询条件、投影和游标db.orders.find( { status: paid, amount: { $gte: 100 } }, { orderNo: 1, amount: 1, _id: 0 } ).sort({ amount: -1 }).limit(20);投影里_id: 0是为了省字节。数据量大、字段多的时候只取需要的字段能让网络传输量降一个数量级。我做过一个对比一个文档平均 4KB只投影出 3 个字段之后只有 200 字节左右20 倍差距。游标这块有个新手常犯的问题遍历大数据集时直接find()然后toArray()内存直接爆。正确做法是用游标迭代const cursor db.orders.find({ status: paid }).batchSize(500); while (cursor.hasNext()) { /* 逐条处理 */ }batchSize控制每次从服务端拉多少条默认 101 条第一批发完后就按 16MB 限制取。对于导出类任务把它设成几百到一千比较均衡。3.3 更新操作符才是核心这是我见过最多问题的地方。下面这种写法在并发下必丢更新// 错误示范读-改-写 const doc db.accounts.findOne({ _id: 1 }); db.accounts.updateOne({ _id: 1 }, { $set: { balance: doc.balance - 100 } });两个人同时读到balance 500各自减 100 写回最后是 400 而不是 300。正确姿势是用$inc让数据库做原子运算db.accounts.updateOne( { _id: 1, balance: { $gte: 100 } }, { $inc: { balance: -100 }, $set: { updatedAt: new Date() } } );条件里带上balance: { $gte: 100 }是乐观锁的思路余额不足时matchedCount为 0业务层就知道扣款失败。这样既保证了原子性又避免了超扣。几个高频操作符的语义要分清操作符作用注意点$set设置字段值字段不存在会创建$unset删除字段值是占位符写什么都行$inc数值增减字段必须存在或是数字否则报错$push数组末尾追加可配合$each批量加$addToSet数组去重追加元素多时性能下降明显$pull按条件移除数组元素支持条件表达式$setOnInsert仅插入时设置必须配合upsert: trueupsert: true是个好帮手先查后插的两步操作可以合并成一步db.users.updateOne( { openId: u_123 }, { $set: { nickname: 老王 }, $setOnInsert: { createdAt: new Date() } }, { upsert: true } );注意$set和$setOnInsert不能作用于同一个字段否则会报冲突。3.4 删除要谨慎软删除更常见物理删除deleteMany在线上环境我建议慎用尤其是没有备份的情况下。大多数业务场景用软删除更稳加一个deletedAt字段查询时带上deletedAt: null。如果确实要物理删除先查一遍确认范围// 先看会删掉多少条 db.logs.countDocuments({ createdAt: { $lt: new Date(2024-01-01) } }); // 确认无误再删分批删避免长锁 db.logs.deleteMany({ createdAt: { $lt: new Date(2024-01-01) } });单次删几十万条会长时间占用写锁更好的方式是分批每次删 5000 条循环执行中间 sleep 一小会。4. 索引和执行计划数据涨到百万级之后的分水岭前面那些操作在几千条数据的时候都飞快任何写法都能跑。等到集合上百万差别就出现了有的查询 5 毫秒有的一分半。分水岭就是索引。4.1 复合索引的最左前缀原则db.orders.createIndex({ status: 1, createdAt: -1 });这条复合索引能支持的查询是status单独查、status createdAt组合查。但单独用createdAt查走不了因为status在最左边跳不过去。这就是最左前缀原则和关系库一样。字段顺序怎么定我一般按 ESR 原则Equality等值在前Sort排序在中Range范围在后。比如查已支付订单、按时间倒序、金额大于 100db.orders.find({ status: paid, amount: { $gt: 100 } }).sort({ createdAt: -1 });理论上最理想的是{ status: 1, createdAt: -1, amount: 1 }。为什么把范围条件放最后因为范围条件一旦匹配后面的字段就无法再用索引做精确跳转了。当然实际场景里排序字段和范围字段的顺序还要结合数据分布测试不要迷信理论。4.2 用 explain 看它到底走了哪条路索引建完不代表用上了。验证方式是explaindb.orders.find({ status: paid }).sort({ createdAt: -1 }) .explain(executionStats);重点看几个字段winningPlan.stageCOLLSCAN表示全表扫描IXSCAN表示走了索引FETCH表示还要回表取文档。totalDocsExamined扫描文档数。如果远大于返回条数索引效果很差。totalKeysExamined扫描索引键数。executionTimeMillis执行耗时。一个健康的查询totalDocsExamined应该接近返回条数。如果看到nReturned: 20但totalDocsExamined: 200000说明索引方向不对或者查询条件本身不具选择性。4.3 几个让索引失效的典型写法写法问题改法{ name: /abc/ }前置通配无法走索引改成前缀匹配/^abc/或上全文索引{ age: { $ne: 30 } }不等条件选择性差尽量用等值 范围组合查询字段做了运算索引键无法参与匹配把运算挪到应用层或建表达式索引数组字段上建普通索引后按元素数查索引覆盖不到需要$size的场景考虑冗余计数字段索引字段类型混用字符串和数字类型不匹配不命中统一写入类型必要时加校验还有一个坑是索引建太多。每加一个索引写入时就要多维护一棵 B 树。我见过一个集合上建了十几个索引写入 QPS 直接腰斩。原则是先看慢查询日志找出真正高频的查询模式再针对性建索引定期用$indexStats检查索引使用次数长期为 0 的果断删掉。db.orders.aggregate([{ $indexStats: {} }]);这个命令会返回每个索引的accesses.ops一目了然。5. 聚合管道把统计逻辑从应用层搬回来以前我特别爱在应用层做统计查出一堆文档然后 for 循环累加。后来发现数据量一上来网络传输和内存占用都受不了而且代码又长又难维护。聚合管道就是把这类逻辑下推到数据库侧。5.1 管道的执行顺序决定了性能聚合管道是一串 stage 依次执行每个 stage 的输出是下一个的输入。顺序至关重要$match和$limit一定要尽早db.orders.aggregate([ { $match: { status: paid, createdAt: { $gte: ISODate(2024-01-01) } } }, { $group: { _id: $userId, total: { $sum: $amount }, cnt: { $sum: 1 } } }, { $match: { total: { $gte: 1000 } } }, { $sort: { total: -1 } }, { $limit: 50 } ]);如果把$match放在$group后面前面就要对全量数据处理一遍可能慢几十倍。能过滤的先过滤能少的先少这是写聚合管道的第一原则。另外第一个$match如果命中了索引整个管道都会受益。所以聚合查询的入口过滤条件要和索引对齐写完记得用explain看一下。5.2 分组、展开和关联$group里最常用的是$sum、$avg、$max、$min还可以用$push把分组内的值收集成数组{ $group: { _id: $category, prices: { $push: $price } } }$unwind用来把数组拆成多条处理一条订单多个商品这种结构特别方便db.orders.aggregate([ { $unwind: $items }, { $group: { _id: $items.sku, sold: { $sum: $items.qty } } }, { $sort: { sold: -1 } } ]);$lookup相当于左连接但它在大数据量下是性能杀手因为每个输入文档都要去目标集合查一次。如果目标集合的关联字段上有索引还好没有索引就是灾难。我的建议是能靠内嵌解决的关联就别用$lookup。5.3 聚合的内存限制和落盘聚合管道默认每个 stage 最多用 100MB 内存超了直接报错。大数据量分组要开启落盘db.orders.aggregate(pipeline, { allowDiskUse: true });开启之后会写临时文件速度慢一些但不会失败。生产环境跑报表类聚合这个参数基本是必开的。还有一点$group的_id如果基数特别大比如按用户 ID 分组几千万用户内存和临时文件都会吃紧。这种场景我一般会先按时间窗口切分分批聚合再合并结果比一次性硬跑靠谱。6. 数据建模和几个新手最容易翻车的地方前面都是操作层面的事真正决定项目后期好不好维护的是数据建模。这块没有标准答案但有些坑是共通的。6.1 内嵌还是引用看读写比例这是文档建模最核心的决策。判断依据其实就一句话这份子数据是不是总跟着主数据一起读而且数量有上限。适合内嵌的情况订单里的商品明细、文章里的标签、用户设置里的偏好项。这些数据量有限几十条以内且读主数据时基本都要一起读。适合引用的情况用户和订单、商品和评论。这类数据会无限增长或者需要独立查询内嵌进去会导致文档不断变大最终撞上 16MB 的单文档上限。一个真实踩过的坑某项目把用户的所有操作日志内嵌到用户文档里一开始没问题跑了一年之后单个文档涨到十几 MB更新开始报错查询也越来越慢。后来拆成独立集合按userId索引才解决。数组字段一定要问自己这个数组会不会无限增长。会就必须拆出去。6.2 无模式不等于不用设计MongoDB 不强制 schema不代表可以随便写。同一个集合里字段名一会儿userId一会儿user_id一会儿字符串一会儿数字后期查询能把你逼疯。我的做法是在应用层用统一的模型定义很多语言的驱动都支持 schema 校验同时在集合上开 validatordb.createCollection(orders, { validator: { $jsonSchema: { bsonType: object, required: [orderNo, amount, status], properties: { orderNo: { bsonType: string }, amount: { bsonType: decimal }, status: { enum: [paid, unpaid, refunded] } } } }, validationLevel: moderate });validationLevel: moderate表示已有文档不校验、新写入才校验避免上线时被历史数据卡住。这个约束看起来麻烦但能挡掉大量低级错误。金额字段我特别建议用Decimal128而不是 double浮点数累加会出现0.1 0.2 0.30000000000000004这种问题财务场景绝对不能接受。6.3 几个高频坑的快速清单坑表现处理方式单文档超 16MB写入报错object to insert too large拆集合或改用 GridFS 存大文件正则没加锚点查询越来越慢前缀匹配加^或建文本索引时间字段存字符串范围查询和排序都不准统一存Date类型skip翻大页越翻越慢改成基于上一页最后一条的_id游标翻页数组元素无上限文档膨胀拆子集合主文档存摘要唯一索引在数组字段上语义和预期不符想清楚是全数组唯一还是元素唯一skip翻页这个坑值得单独说一下。skip(100000).limit(20)并不是直接跳到第 10 万条而是先把前面 10 万条扫一遍再丢掉越往后越慢。正确做法是记住上一页最后一条的排序字段值下一页用 lastValue来查db.articles.find({ createdAt: { $lt: lastCreatedAt } }) .sort({ createdAt: -1 }).limit(20);这种方式在任何页数下耗时都稳定前提是排序字段上有索引。6.4 备份和变更这两件事别等出事再想最后提两个运维层面的事。第一是备份mongodump简单够用但要注意它是逻辑备份大库导出很慢而且导出期间的数据一致性要靠--oplog保证。数据量大的话快照方式更稳。第二是索引和字段的变更。给一个千万级集合加索引如果没有指定后台构建会阻塞写入。新版本虽然默认行为已经优化但上线前还是应该在预发环境用同等数据量压一遍记录耗时。我吃过一次亏预发只有十万条数据加索引两秒完成生产一千多万条加了四十多分钟期间接口大面积超时。自此之后任何涉及大集合的变更我都会先拿生产数据的抽样副本跑一遍估算耗时再挑低峰期执行。写了这么多其实 MongoDB 入门真正的门槛不在语法而在两个思维转变一是从表结构先行转到读取模式先行建模时先想清楚数据怎么被读二是从应用层拼装转到数据库侧完成索引、聚合、投影这些能力用好了很多逻辑根本不用搬到代码里。我自己在实际项目里的体会是但凡一个查询开始变慢第一反应应该是去看explain而不是急着加缓存。缓存能盖住问题但索引没建对缓存一失效问题还是原样回来。