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 },它便會驗證被更新的路徑並拒絕,與解題實例中的更新相同。