MongoDB 从零到能用：文档、CRUD、聚合与 Node.js 实战

很多数据库教程停在“插入一条数据、查询一条数据”。真正开始写业务后，马上会遇到更多问题：字段怎么设计？数组怎么查？分页怎么写？索引到底有没有生效？应用代码如何安全地复用数据库连接？

这篇文章用一个商品目录 Demo 串起 MongoDB 的核心能力：从启动数据库开始，依次完成文档建模、增删改查、数组和嵌套对象查询、分页、聚合、索引，再用 Node.js 官方驱动写一个可以直接运行的示例。

示例使用 MongoDB 8.0、mongosh 和 Node.js。MongoDB 的命令可以在 MongoDB Shell、Compass 的命令区域或应用驱动中使用。

一、MongoDB 到底存什么

MongoDB 是文档数据库。数据以 BSON 文档保存，BSON 可以理解成“比 JSON 多了一些类型支持的二进制 JSON”。一条商品数据大致长这样：

{  _id: ObjectId("66b000000000000000000001"),  name: "机械键盘",  price: 399,  stock: 42,  category: "键盘",  tags: ["办公", "RGB", "蓝牙"],  specs: {    layout: "87键",    connection: ["USB-C", "Bluetooth"]  },  createdAt: ISODate("2026-09-15T08:00:00Z")}

这里有普通字段、数组、嵌套对象和日期，数据结构比一张扁平的表更贴近商品详情页。

和 MySQL 的概念对应关系

MongoDB 不要求先执行 CREATE TABLE。第一次向集合写入文档时，数据库可以自动创建数据库和集合：

shop（数据库）└── products（集合）    ├── document    ├── document    └── document

“无固定 Schema”不等于“字段可以随便写”。它表示数据库不会强迫同一个集合中的每条文档完全相同。业务字段仍然应该保持稳定，必要时配合应用层校验或 MongoDB 的 JSON Schema 校验，避免同一字段一会儿存数字、一会儿存字符串。

二、启动 MongoDB

1. Docker 启动本地实例

学习和开发阶段，用 Docker 最省事：

docker run -d \  --name mongodb \  -p 27017:27017 \  -v mongodb-data:/data/db \  mongo:8.0

参数含义：

-d                 后台运行--name mongodb     容器名称-p 27017:27017    映射 MongoDB 默认端口-v mongodb-data... 把数据保存到 Docker volumemongo:8.0         使用 MongoDB 8.0 镜像

查看容器状态：

docker psdocker logs mongodb

进入 MongoDB Shell：

docker exec -it mongodb mongosh

连接地址为：

mongodb://127.0.0.1:27017

停止和再次启动：

docker stop mongodbdocker start mongodb

这个本地 Demo 没有开启认证，只适合本机学习。生产环境不能把未认证的 MongoDB 直接暴露在公网。

2. 带账号密码的启动方式

需要演示认证时，可以重新创建一个带管理员账号的容器：

docker run -d \  --name mongodb-auth \  -p 27018:27017 \  -v mongodb-auth-data:/data/db \  -e MONGO_INITDB_ROOT_USERNAME=admin \  -e MONGO_INITDB_ROOT_PASSWORD='change-me-please' \  mongo:8.0

连接：

mongosh "mongodb://admin:change-me-please@127.0.0.1:27018/?authSource=admin"

authSource=admin 表示账号在 admin 数据库中认证。密码中包含 @、?、# 等特殊字符时，需要先进行 URI 百分号编码。

3. 使用 MongoDB Atlas

Atlas 是 MongoDB 官方托管服务。创建集群后，需要完成两项配置才能连接：

1. 1. 在 Network Access 中加入客户端 IP。
2. 2. 创建 MongoDB Database User，并使用该用户生成连接字符串。

Atlas 通常提供这样的 SRV 连接字符串：

mongodb+srv://<username>:<password>@<cluster>.mongodb.net/shop

连接字符串不要硬编码到 Git 仓库，放进环境变量更安全：

export MONGODB_URI='mongodb+srv://user:password@cluster.example.mongodb.net/shop'

三、先用 mongosh 跑通 CRUD

启动 mongosh 后，先切换到 Demo 数据库：

use shopdb

use shop 是切换数据库。只有真正写入数据后，数据库通常才会出现在 show dbs 的列表中。

1. 插入一条文档

db.products.insertOne({  name: "机械键盘",  price: 399,  stock: 42,  category: "键盘",  tags: ["办公", "RGB", "蓝牙"],  specs: {    layout: "87键",    connection: ["USB-C", "Bluetooth"]  },  createdAt: new Date()})

执行结果中会出现 insertedId。没有手动提供 _id 时，MongoDB 会自动生成一个 ObjectId：

{ acknowledged: true, insertedId: ObjectId('...') }

_id 在一个集合中必须唯一，它既可以使用自动生成的 ObjectId，也可以使用业务方提供的字符串或其他唯一值。

2. 批量插入

db.products.insertMany([  {    name: "人体工学鼠标",    price: 159,    stock: 100,    category: "鼠标",    tags: ["办公", "无线"],    specs: { dpi: 4000, connection: ["Bluetooth", "2.4G"] },    createdAt: new Date()  },  {    name: "显示器支架",    price: 299,    stock: 18,    category: "支架",    tags: ["办公", "桌搭"],    specs: { material: "铝合金", maxSize: 32 },    createdAt: new Date()  },  {    name: "USB-C 扩展坞",    price: 229,    stock: 0,    category: "扩展坞",    tags: ["办公", "USB-C"],    specs: { ports: 8, connection: ["USB-C"] },    createdAt: new Date()  }])

3. 查询文档

查询全部文档：

db.products.find()

格式化输出：

db.products.find().pretty()

精确匹配：

db.products.find({ category: "键盘" })

比较操作符：

// 价格大于等于 200db.products.find({ price: { $gte: 200 } })// 库存大于 0 且价格不超过 300db.products.find({  stock: { $gt: 0 },  price: { $lte: 300 }})

常用比较操作符：

$eq   等于$ne   不等于$gt   大于$gte  大于等于$lt   小于$lte  小于等于$in   命中数组中的任意值$nin  不命中数组中的值

OR 条件：

db.products.find({  $or: [    { category: "键盘" },    { price: { $lt: 200 } }  ]})

只返回需要的字段，称为投影：

db.products.find(  { stock: { $gt: 0 } },  { name: 1, price: 1, stock: 1, _id: 0 })

1 表示保留字段，0 表示排除字段。除 _id 外，通常不要在同一个投影中混用“保留”和“排除”两种写法。

查询一条文档：

db.products.findOne({ name: "机械键盘" })

按 _id 查询：

db.products.findOne({  _id: ObjectId("66b000000000000000000001")})

实际返回的 _id 需要替换成终端中插入结果里的值。

4. 数组和嵌套对象查询

数组字段可以直接匹配元素：

// tags 数组包含“办公”db.products.find({ tags: "办公" })// tags 同时包含“办公”和“无线”db.products.find({  tags: { $all: ["办公", "无线"] }})

嵌套对象使用点号路径：

// specs.connection 数组包含 Bluetoothdb.products.find({ "specs.connection": "Bluetooth" })// specs.dpi 大于 1000db.products.find({ "specs.dpi": { $gt: 1000 } })

查询字段是否存在：

db.products.find({ "specs.ports": { $exists: true } })

5. 排序、分页和统计

// 价格从高到低db.products.find().sort({ price: -1 })// 价格从低到高db.products.find().sort({ price: 1 })// 第 2 页，每页 2 条db.products.find()  .sort({ createdAt: -1, _id: -1 })  .skip(2)  .limit(2)

排序方向 1 表示升序，-1 表示降序。分页排序时增加 _id 作为第二排序字段，可以让相同 createdAt 的文档保持稳定顺序。

统计数量：

db.products.countDocuments({ stock: { $gt: 0 } })

不建议在数据量很大时直接 find() 后再在应用层截取。过滤、排序、分页尽量交给数据库完成。

6. 更新文档

更新一个字段：

db.products.updateOne(  { name: "机械键盘" },  { $set: { price: 369, stock: 40 } })

增加或减少数字：

db.products.updateOne(  { name: "机械键盘" },  { $inc: { stock: -1 } })

向数组中追加一个值，重复值也会追加：

db.products.updateOne(  { name: "机械键盘" },  { $push: { tags: "热卖" } })

只在数组中不存在时才追加：

db.products.updateOne(  { name: "机械键盘" },  { $addToSet: { tags: "办公" } })

从数组中移除值：

db.products.updateOne(  { name: "机械键盘" },  { $pull: { tags: "RGB" } })

更新嵌套字段：

db.products.updateOne(  { name: "机械键盘" },  { $set: { "specs.layout": "75键" } })

批量更新：

db.products.updateMany(  { category: "办公设备", stock: { $gt: 0 } },  { $set: { sale: true } })

没有 办公设备 的 Demo 文档时，这条命令不会更新任何数据，这正好说明更新条件和更新内容是两部分。

使用 upsert 可以实现“有则更新，无则插入”：

db.products.updateOne(  { name: "桌面音箱" },  {    $set: { price: 199, stock: 20, category: "音箱" },    $setOnInsert: { createdAt: new Date() }  },  { upsert: true })

7. 删除文档

// 删除一条db.products.deleteOne({ name: "桌面音箱" })// 删除所有库存为 0 的商品db.products.deleteMany({ stock: 0 })

删除前先执行同样的过滤条件查询，确认命中范围：

db.products.find({ stock: 0 }, { name: 1, stock: 1 })

清空整个集合：

db.products.deleteMany({})

删除集合和删除数据库属于更大范围的操作：

db.products.drop()db.dropDatabase()

四、用聚合管道做统计

普通 find() 适合取文档，统计和转换则使用聚合管道。管道由多个阶段组成，前一个阶段的结果交给下一个阶段：

$match → $group → $sort → $project

1. 按分类统计商品数量和平均价格

db.products.aggregate([  {    $match: { stock: { $gt: 0 } }  },  {    $group: {      _id: "$category",      productCount: { $sum: 1 },      averagePrice: { $avg: "$price" },      totalStock: { $sum: "$stock" }    }  },  {    $sort: { productCount: -1, averagePrice: 1 }  },  {    $project: {      _id: 0,      category: "$_id",      productCount: 1,      averagePrice: { $round: ["$averagePrice", 2] },      totalStock: 1    }  }])

这里的含义是：先过滤有库存的商品，再按 category 分组，计算数量、平均价格和库存总数，最后调整返回字段。

2. 统计标签使用次数

$unwind 会把数组拆成多行：

db.products.aggregate([  { $unwind: "$tags" },  {    $group: {      _id: "$tags",      count: { $sum: 1 }    }  },  { $sort: { count: -1, _id: 1 } }])

一条商品有 3 个标签，经过 $unwind 后会变成 3 个中间结果，再由 $group 统计每个标签出现了多少次。

五、索引：让查询真正跑得快

没有索引时，MongoDB 可能需要扫描集合中的大量文档。高频过滤、排序和唯一性约束，通常都应该结合索引设计。

1. 创建和查看索引

// category + price 复合索引db.products.createIndex({ category: 1, price: 1 })// name 唯一索引db.products.createIndex({ name: 1 }, { unique: true })// 查看索引db.products.getIndexes()

复合索引的字段顺序很重要。{ category: 1, price: 1 } 适合先按分类过滤、再按价格排序的查询：

db.products.find({ category: "键盘" }).sort({ price: 1 })

不能把索引理解成“越多越好”。每个索引都会占用磁盘和内存，写入时也需要同步维护。应围绕真实查询建立索引。

2. 查看执行计划

db.products.find({ category: "键盘" })  .explain("executionStats")

重点关注：

IXSCAN       使用索引扫描COLLSCAN     全集合扫描totalDocsExamined  检查过的文档数nReturned          返回的文档数

数据量很小时，索引收益可能不明显；判断索引是否合适，应在接近真实数据量的环境中观察执行计划。

3. TTL 索引

临时数据可以使用 TTL 索引自动过期。TTL 字段必须是日期类型：

db.loginTokens.createIndex(  { expiresAt: 1 },  { expireAfterSeconds: 0 })db.loginTokens.insertOne({  token: "demo-token",  expiresAt: new Date(Date.now() + 10 * 60 * 1000)})

过期清理由后台任务执行，不保证在到达时间的瞬间删除，业务上不要把它当成精确的定时器。

六、Node.js 官方驱动实战

官方 Node.js Driver 提供了 MongoClient、数据库、集合和 CRUD API。先创建一个独立目录：

mkdir mongodb-democd mongodb-demonpm init -ynpm install mongodb

创建 index.js：

const { MongoClient } = require("mongodb");const uri = process.env.MONGODB_URI || "mongodb://127.0.0.1:27017";const client = new MongoClient(uri);async function main() {  await client.connect();  const db = client.db("shop");  const products = db.collection("products");  // 只创建一次即可；重复执行会得到同名索引已存在的结果  await products.createIndex({ category: 1, price: 1 });  const insertResult = await products.insertOne({    name: `USB-C 线材-${Date.now()}`,    price: 49,    stock: 200,    category: "线材",    tags: ["办公", "USB-C"],    createdAt: new Date()  });  console.log("新商品 ID：", insertResult.insertedId.toString());  const list = await products.find({    stock: { $gt: 0 },    price: { $lte: 300 }  })    .project({ name: 1, price: 1, stock: 1, _id: 0 })    .sort({ price: 1 })    .limit(10)    .toArray();  console.table(list);  const updateResult = await products.updateOne(    { _id: insertResult.insertedId },    { $inc: { stock: -1 }, $addToSet: { tags: "热卖" } }  );  console.log("更新数量：", updateResult.modifiedCount);  const statistics = await products.aggregate([    { $match: { stock: { $gt: 0 } } },    {      $group: {        _id: "$category",        count: { $sum: 1 },        averagePrice: { $avg: "$price" }      }    },    { $sort: { count: -1 } }  ]).toArray();  console.log("分类统计：", statistics);}main()  .catch((error) => {    console.error("MongoDB 操作失败：", error);    process.exitCode = 1;  })  .finally(async () => {    await client.close();  });

运行：

node index.js

为什么要复用 MongoClient

MongoClient 内部会管理连接池。Web 服务启动时创建一个客户端，后续请求复用同一个客户端即可，不要每次接口请求都 new MongoClient()、连接、关闭。

一个简单的模块封装如下：

// db.jsconst { MongoClient } = require("mongodb");const client = new MongoClient(  process.env.MONGODB_URI || "mongodb://127.0.0.1:27017");let database;async function getDb() {  if (!database) {    await client.connect();    database = client.db("shop");  }  return database;}module.exports = { getDb, client };

业务代码中直接复用：

const { getDb } = require("./db");async function findAvailableProducts() {  const db = await getDb();  return db.collection("products")    .find({ stock: { $gt: 0 } })    .sort({ createdAt: -1 })    .limit(20)    .toArray();}

七、MongoDB 的数据建模：嵌入还是拆开

MongoDB 的关键不只是“表换成集合”，而是根据读取方式设计文档。

适合嵌入的情况

商品规格放在商品文档内部就很自然：

{  name: "机械键盘",  specs: {    layout: "87键",    switch: "茶轴"  }}

适合嵌入的典型特点：

详情页经常一起读取子数据数量有限子数据不会被多个主体共享

适合拆成独立集合的情况

订单中的商品快照、商品主数据和库存记录，生命周期可能不同：

products       商品主数据orders         订单inventory      库存和仓库信息

适合拆分的典型特点：

子数据数量可能无限增长子数据需要独立查询和更新多个业务主体共享同一份数据

MongoDB 支持 $lookup 做集合关联，但它不是把所有关系型表直接搬过来的理由。优先根据业务读取模式设计文档，再决定嵌入、引用或两者结合。

八、常见错误和排查方法

1. ECONNREFUSED 127.0.0.1:27017

通常表示 MongoDB 没启动，或者端口映射不对：

docker psdocker logs mongodbmongosh "mongodb://127.0.0.1:27017"

2. Atlas 连接超时

检查三项：

客户端 IP 是否加入 IP Access ListDatabase User 的账号密码是否正确连接字符串中的特殊字符是否做了 URL 编码

Atlas 用户账号和 MongoDB Database User 不是同一类账号，前者登录 Atlas 控制台，后者用于连接数据库。

3. 查询数字却查不到

MongoDB 会区分数字和字符串：

{ price: 399 }      // 数字{ price: "399" }    // 字符串

这两个值不是同一种类型。字段类型应在写入入口统一处理。

4. 分页越来越慢

skip() 在页数很深时需要跳过大量结果。后台管理列表通常足够使用 skip + limit；大数据量的无限滚动场景，可以改成基于排序字段的游标分页，例如记录上一页最后一个 _id，下一页使用 $lt 或 $gt 继续查询，并配套索引。

5. 把集合当成完全无规则的 JSON 仓库

字段灵活适合迭代，但字段命名、类型和必填规则仍应统一。至少在应用层保证：

price 始终是数字stock 始终是非负整数createdAt 始终是 Datename 具备唯一性或明确允许重复

九、日常命令速查

show dbs                         // 查看数据库use shop                         // 切换数据库db                               // 当前数据库show collections                 // 查看集合db.products.find()               // 查询集合db.products.countDocuments()     // 统计文档数db.products.getIndexes()         // 查看索引db.products.drop()               // 删除集合db.dropDatabase()                // 删除当前数据库

数据备份与恢复使用 MongoDB Database Tools：

mongodump --uri="mongodb://127.0.0.1:27017/shop" --out=./backupmongorestore --uri="mongodb://127.0.0.1:27017" ./backup

备份命令应根据实际部署、账号权限和存储策略调整，生产环境还需要验证恢复流程，而不是只验证备份命令能否执行。

十、学习路线

按照下面的顺序继续练习，基本可以覆盖日常开发：

1. mongosh：CRUD、数组、嵌套对象、投影、分页2. 数据建模：嵌入、引用、文档大小和读取模式3. 索引：单字段、复合、唯一、TTL、explain4. 聚合：$match、$project、$unwind、$group、$lookup5. 驱动：连接池、错误处理、事务、批量写入6. 运维：认证、权限、备份、副本集、监控

MongoDB 的官方文档：

• • MongoDB Database Manual
• • 连接 MongoDB 集群
• • Node.js 官方驱动
• • Node.js 驱动连接配置
• • MongoDB Atlas 集群连接

掌握文档结构、查询条件、更新操作、聚合管道和索引之后，MongoDB 就不再只是“会存 JSON”，而是一套可以支撑真实业务查询和统计的数据库工具。