Express 一节说明了请求如何到达处理函数,以及 JSON 如何被解析和返回。但处理函数仍没有地方保存寿命超过单次请求或单一进程的数据。本节加入数据库:MongoDB 把数据存为文档,而 Mongoose 是 Node.js 的库,在 MongoDB 之上加入结构定义、验证与以 Promise 为基础的查询接口。例子使用 ES 模块与 async/await,它们是当前 Node.js 的标准用法;并假设 Mongoose 的版本中各项操作都返回 Promise(在当前的 Mongoose 版本中,这些调用已不再使用回调函数)。
1. 文档、集合与 _id
MongoDB 不把数据存为固定表格中的行。文档是一组字段与值的配对,写法像 JSON 对象,但以二进制编码(BSON)存储,该编码多了日期、对象标识符等类型。文档归入集合,集合位于数据库之内。同一集合中的两个文档不必有相同的字段;MongoDB 本身并不要求结构定义。
每个文档在其集合中都有唯一的 _id 字段。若应用程序没有提供,客户端库会产生一个 ObjectId,它是 12 字节的值,通常显示为 24 个十六进制字符。在 JSON 响应中,ObjectId 以字符串出现;它不是数字,也不是计数器。
文档可以包含嵌套对象与数组,所以一个文档可以容纳关系型设计要分散在多个表格的内容。例如
{ "_id": "65a1f0c2e4b0a1b2c3d4e5f6", "title": "Open Day", "venue": "LT1",
"capacity": 200, "tags": ["campus", "visit"] }
就是一个嵌入了标签的活动。
2. Mongoose 结构定义与模型
定义 8.3.1
(结构定义、模型与文档)
结构定义(schema)声明一个集合中文档的字段、类型和规则。模型是由结构定义编译出来的类,用来读写该集合。文档是一条已保存的记录,是模型的实例。结构定义存在于应用程序中,所以数据库只会强制执行 MongoDB 本身能强制的规则,例如唯一索引。
Mongoose 在应用程序而不是数据库中定义文档的形状。结构定义(schema)列出各字段的类型与规则;模型(model)是由结构定义编译出的类,用来访问一个集合。
import mongoose from "mongoose";
const eventSchema = new mongoose.Schema(
{
title: { type: String, required: true, trim: true, maxlength: 100 },
venue: { type: String, required: true },
capacity: { type: Number, required: true, min: 1 },
tags: [String],
},
{ timestamps: true }
);
export const Event = mongoose.model("Event", eventSchema);
required、min 与 maxlength 是 Mongoose 在存储文档之前执行的验证器。trim 是设置器,会去掉首尾空白。选项 timestamps: true 会加入 createdAt 与 updatedAt。名为 Event 的模型使用集合 events:Mongoose 默认把模型名称改为小写并转成复数。要留意这些规则的限制。它们由你的 Node.js 进程中的 Mongoose 执行,所以另一个写入同一集合的程序可以绕过它们。选项 unique: true 不同:它要求 MongoDB 建立唯一索引,因此唯一性由数据库保证,但它不是验证器:违反唯一性只会在写入时才被发现,并以错误码 11000 的错误出现。
在处理请求之前连接一次:
await mongoose.connect("mongodb://127.0.0.1:27017/campus");
路径 /campus 指定数据库名称。连接字符串不应放进会被提交的源代码;应从环境变量读取。
3. CRUD 操作
以下各项都返回 Promise(或可 await 的查询对象),所以都在 async 函数内以 await 使用。
新增。 Event.create(data) 先验证,再插入,并返回新文档。
const created = await Event.create({ title: "Open Day", venue: "LT1", capacity: 200 });
读取。 Event.find(filter) 返回符合条件的文档数组(没有则为空数组);Event.findById(id) 与 Event.findOne(filter) 返回一个文档或 null。筛选条件是由字段条件组成的对象,可使用 $gte、$in 等运算符;查询可再以 sort、limit 与 select 细化。
const one = await Event.findById(created._id);
const large = await Event.find({ capacity: { $gte: 100 } }).sort({ capacity: -1 }).limit(10);
const total = await Event.countDocuments({});
更新。 findByIdAndUpdate(id, update, options) 找到文档,套用 $set 等更新运算符,并返回一个文档。默认返回的是更新之前的文档,所以要传入 returnDocument: "after"。更新查询默认不执行验证器,除非要求,所以也要传入 runValidators: true。若没有文档符合,结果为 null。
const updated = await Event.findByIdAndUpdate(
created._id,
{ $set: { capacity: 250 } },
{ returnDocument: "after", runValidators: true }
);
删除。 deleteOne(filter) 删除第一个符合的文档,并返回 deletedCount 为 0 或 1 的结果。
const result = await Event.deleteOne({ _id: created._id });
4. 验证在何处执行
结构定义的规则并非对每种操作都一律适用,所以要弄清楚是哪一个调用到达数据库。
| 操作 | 结构定义的验证器会运行吗? |
|---|---|
Event.create(data) 或 new Event(data).save() | 会,在写入之前;对现有文档调用 save() 会检查被修改的路径 |
Event.insertMany(docs) | 会,逐个文档检查 |
findByIdAndUpdate、findOneAndUpdate、updateOne | 不会,除非传入 runValidators: true;传入后只检查更新内容所涉及的路径 |
| 其他程序或 MongoDB shell 的写入 | 永远不会,因为不经过 Mongoose |
由此得出两个结论。如果路由取得文档后赋值 event.capacity = -5 再调用 save(),会经过验证;但用更新查询写出同一项变更,除非设置了 runValidators,否则不会验证。此外,验证器存在于应用程序之中,所以必须对每个写入者都成立的约束(例如唯一性),应以索引的形式放在数据库中。
反例模式
结构定义的最小值并不保证已存储的数据
有人声称:既然结构定义声明了 min: 1,存储的活动容量就不可能小于 1。先创建容量为 200 的 A,它通过验证。然后执行 await Event.updateOne({ _id: A._id }, { $set: { capacity: 0 } })。这个 Promise 正常完成,modifiedCount 为 1,因为更新查询默认不执行结构定义的验证器,而 Event.findById(A._id) 现在返回容量 0。从 MongoDB shell 写入也会得到同样结果。传入 { runValidators: true },或先加载文档、赋值字段再调用 save(),Mongoose 才会拒绝该值;每个写入者都必须遵守的规则,要由数据库本身强制执行。
5. 把 CRUD 接到 Express
路由处理函数必须决定每种结果在 HTTP 中的意义:错误的输入是客户端错误,找不到文档是 404,未预期的异常是服务器错误。以下两个路由使用 Express 一节中的 express.json()。
app.get("/events/:id", async (req, res, next) => {
try {
if (!mongoose.isObjectIdOrHexString(req.params.id)) {
return res.status(400).json({ error: "invalid id" });
}
const event = await Event.findById(req.params.id);
if (!event) return res.status(404).json({ error: "not found" });
res.json(event);
} catch (err) {
next(err);
}
});
app.post("/events", async (req, res, next) => {
try {
const { title, venue, capacity } = req.body;
const event = await Event.create({ title, venue, capacity });
res.status(201).json(event);
} catch (err) {
if (err.name === "ValidationError") {
return res.status(400).json({ error: err.message });
}
next(err);
}
});
有三点要注意。第一,无效的 id 字符串会令 Mongoose 抛出 CastError;先用 isObjectIdOrHexString 检查,就能得到受控的 400,而不是 500。第二,处理函数只从 req.body 复制三个预期的字段到 create;直接传入 req.body 会让客户端设置路由无意开放的字段(批量赋值漏洞)。第三,try/catch 配合 next(err) 把未预期的错误交给 Express 的错误处理,在 Express 4 与 Express 5 中都适用。
旁注
先决定状态码,再写代码
对每种结果先问:客户端应该修改请求(4xx),还是服务器出了问题(5xx)?处理函数的各个分支就由这份清单决定。
6. 例题详解
例题 8.3.2
(追踪一个集合的创建、查询、更新与删除)
从空的 events 集合开始,令 A、B、C 为依次执行下列调用所创建的文档。
Event.create({ title: "Open Day", venue: "LT1", capacity: 200 })保存A。Event.create({ title: "Talk", venue: "LT2", capacity: 80 })保存B。Event.create({ title: "Fair", venue: "Hall", capacity: 500 })保存C。Event.create({ title: "Draft", capacity: 10 })因venue为必填而抛出ValidationError;没有保存任何内容。错误的errors对象含有venue一项。
此时 countDocuments({}) 为 3。查询 find({ capacity: { $gte: 100 } }).sort({ capacity: -1 }) 先返回 C(500),再返回 A(200);B 的 capacity 为 80,被排除。执行 findByIdAndUpdate(A._id, { $set: { capacity: 250 } }, { returnDocument: "after", runValidators: true }) 后,返回的文档 capacity 为 250,重复上述排序查询则先返回 C(500),再返回 A(250)。调用 findByIdAndUpdate(B._id, { $set: { capacity: 0 } }, { returnDocument: "after", runValidators: true }) 会因 0 低于 min: 1 而以 ValidationError 被拒绝,B 保持 80。如果没有 runValidators: true,同一个更新会悄悄存入 0。最后 deleteOne({ _id: C._id }) 的 deletedCount 为 1,再调用一次为 0,而 countDocuments({}) 为 2。
例题 8.3.3
(活动评论:嵌入还是引用)
有两种设计可以保存活动的评论。嵌入把评论放在父文档之内;引用则在另一个集合中保存父文档的 id。
// Embedding: the reviews live inside the event document.
const embeddedEventSchema = new mongoose.Schema({
title: String,
reviews: [{ author: String, rating: { type: Number, min: 1, max: 5 } }],
});
// Referencing: each review is its own document that points at an event.
const reviewSchema = new mongoose.Schema({
event: { type: mongoose.Schema.Types.ObjectId, ref: "Event", required: true },
author: String,
rating: { type: Number, min: 1, max: 5 },
});
const Review = mongoose.model("Review", reviewSchema);
const reviews = await Review.find({ event: created._id }).populate("event");
如果评论总是与活动一起读取、数量有上限,也不会被单独查询,嵌入让整个活动只需一次读取和一次原子写入。如果评论数量庞大、无限增长,或按用户读取,引用可避免文档无限增大(MongoDB 文档有 16 MiB 的大小上限),并允许单独查询。引用只是一个 ObjectId:MongoDB 不会检查被引用的活动是否存在,所以删除活动后,除非应用程序一并移除评论,否则评论可能指向不存在的活动。Mongoose 的 populate("event") 会把 id 换成活动文档,代价是多一次查询。学生与课程这类多对多关系使用引用,因为嵌入会重复保存必须保持一致的数据。
例题 8.3.4
(更新路由及其五种结果)
以下路由更新一个活动的 capacity。假设活动 A 存在,capacity 为 200,并且 express.json() 已在它之前注册。
app.patch("/events/:id", async (req, res, next) => {
try {
if (!mongoose.isObjectIdOrHexString(req.params.id)) {
return res.status(400).json({ error: "invalid id" });
}
if (typeof req.body?.capacity !== "number") {
return res.status(400).json({ error: "capacity must be a number" });
}
const event = await Event.findByIdAndUpdate(
req.params.id,
{ $set: { capacity: req.body.capacity } },
{ returnDocument: "after", runValidators: true }
);
if (!event) return res.status(404).json({ error: "not found" });
res.json(event);
} catch (err) {
if (err.name === "ValidationError") {
return res.status(400).json({ error: err.message });
}
next(err);
}
});
| 请求 | 在处理函数中的路径 | 响应 |
|---|---|---|
PATCH /events/zzz,请求体 {"capacity":50} | id 不是 ObjectId,也不是 24 个字符的十六进制字符串 | 400 invalid id |
PATCH /events/<A 的 id>,请求体 {"capacity":"many"} | typeof 检查失败;没有调用数据库 | 400 capacity must be a number |
PATCH /events/<A 的 id>,请求体 {"capacity":0} | runValidators 依 min: 1 拒绝 0;catch 把 ValidationError 映射为 400 | 400,附验证消息 |
PATCH /events/<A 的 id>,请求体 {"capacity":250} | 应用更新;returnDocument: "after" 返回新文档 | 200,capacity 为 250 |
PATCH /events/<有效但不在集合中的 id>,请求体 {"capacity":50} | 查询没有匹配项,结果为 null | 404 not found |
各项检查按成本与确定性的顺序进行:先检查 id 与请求体形状,不需要调用数据库;然后由 Mongoose 验证新值;最后由查询结果决定响应 200 还是 404。ValidationError 属于客户端错误,所以映射为 400;其他异常(例如连接中断)交给 next(err),成为服务器错误。如果没有 runValidators: true,capacity 为 0 的情况会写入 0 并响应 200,这正是验证运行位置一节警告的悄悄失败。两种 id 的情况也有意区分:格式错误的 id 不可能指向任何文档,所以客户端收到 400;格式正确却没有匹配项的 id 表示资源不存在,所以收到 404。把两者分开,客户端就知道应该修正请求,还是不要再寻找该文档。
7. 常见错误
- 忘了
await:变量得到的是 Promise 或查询对象,而不是文档,并且发出响应时操作可能尚未完成。 - 把结构定义当作数据库约束。Mongoose 验证器只在经过 Mongoose 时执行,更新验证器只在设置了
runValidators时执行。 - 把用户可控制的
req.body或req.query对象直接当作筛选条件或更新内容;运算符注入见网络安全一节。 - 没有
returnDocument: "after"却以为findByIdAndUpdate返回新文档。 - 把含内部细节的原始 Mongoose 错误直接送给客户端。
常见错误
(以 === 比较 ObjectId)
ObjectId 是对象,所以即使字符串与它是同样的 24 个十六进制字符,event._id === req.params.id 也是 false:对象与字符串永远不会严格相等。两个值相同但各自独立的 ObjectId 对象,用 === 比较也不相等,因为它比较的是对象身份。应使用 event._id.equals(otherId),或比较 String(event._id) 与 String(otherId)。
常见错误
(把 unique 当作验证器)
声明 unique: true 是要求 MongoDB 建立唯一索引,并不会加入验证器。若已有两个标题相同的活动,建立索引会失败,重复项仍然存在。其后的 create 重复某个值时,驱动程序报告的是错误码 11000 的重复键错误,而不是 ValidationError,所以上面的 POST 路由会把它交给 next(err),响应 500。应检查 err.code === 11000,并以客户端错误响应,通常是 409。
8. 练习
快速检查
(编写结构定义)
为学生写一个 Mongoose 结构定义:姓名必填且至多 50 个字符,学习年级为 1 至 4 之间的整数,电子邮件必须唯一。指出其中哪一条规则由数据库保证。
解答
const studentSchema = new mongoose.Schema({
name: { type: String, required: true, maxlength: 50 },
year: { type: Number, min: 1, max: 4,
validate: { validator: Number.isInteger, message: "year must be an integer" } },
email: { type: String, required: true, unique: true },
});
required、maxlength、min、max 以及自定义验证器都由 Mongoose 在保存前执行。只有 unique: true 要求 MongoDB 创建唯一索引,所以只有 email 的唯一性由数据库保证:写入第二个相同邮箱的文档时,会出现重复键错误(错误码 11000)。
快速检查
(删除与排序)
集合 events 含有 A(capacity 200)、B(80)、C(500)。执行 deleteOne({ capacity: { $lt: 100 } }),再执行 find({}).sort({ capacity: 1 }) 之后,返回哪些文档、顺序如何?deletedCount 是多少?
解答
过滤条件只匹配 B(80),所以删除 B,deletedCount 为 1。其余文档按 capacity 升序排列为 A(200)、C(500)。
快速检查
(过时的响应)
某路由执行 await Event.findByIdAndUpdate(id, { capacity: 0 }),响应显示活动仍是旧的 capacity,但数据库现在存的是 0。解释原因并修正调用。
解答
findByIdAndUpdate 默认返回更新之前的文档,所以响应显示旧的 capacity。验证器默认也不会在更新时运行,所以结构定义中的 min: 1 没有拒绝 0。修正后的调用为 await Event.findByIdAndUpdate(id, { $set: { capacity: 0 } }, { returnDocument: "after", runValidators: true }),此时 capacity 为 0 会以 ValidationError 被拒绝;如果使用有效的 capacity(例如 120),则返回更新后的文档。
快速检查
(嵌入还是引用)
一名 Student 有至多 5 个兴趣字符串,并且属于恰好一个由数百名学生共用的 Program。分别为这两种关系选择嵌入或引用,并说明理由。
解答
兴趣:嵌入为字符串数组。列表很小且有上限,属于该学生,并与学生一起读取。专业(Program):使用引用,在学生文档中保存该专业的 ObjectId。许多学生共用同一个专业,嵌入会把专业数据复制到数百个文档,任何改动都要逐一重复;使用引用则只需更新一个专业文档。
快速检查
(save 与更新查询)
某路由执行 const event = await Event.findById(id); event.capacity = -5; await event.save();。规则 min: 1 会适用吗?相比之下,Event.updateOne({ _id: id }, { capacity: -5 }) 会怎样?
解答
会适用。save() 会验证被修改的路径 capacity,所以该调用以 ValidationError 被拒绝,已保存的文档不变。updateOne 默认不运行结构定义的验证器,会悄悄写入 -5。如果在其选项中传入 { runValidators: true },它就会验证被更新的路径并拒绝,与例题中的更新相同。