瀏覽器送出的請求只是一個方法、一條路徑、若干標頭,有時再加上主體。本單元說明 Express 程式如何把這樣的請求變成決定:哪個處理函式執行、JSON 主體如何成為 req.body,以及回應由哪個狀態碼、標頭和主體組成。程式碼是教學示例,並非已安裝或部署的服務。
1. 由請求到處理函式
定義 8.1.1
(路由與處理函式)
路由把一個 HTTP 方法及一個路徑模式與一個處理函式配對,處理函式即 (req, res) 或 (req, res, next) 形式的函式。Express 按註冊次序,把每個請求與已註冊的路由及中介軟件比對。傳送了回應的處理函式會結束搜尋;調用 next() 的處理函式則把請求交給下一個匹配項。
每個 HTTP 請求都帶有一個方法(例如 GET、POST 或 PATCH)及一個目標(一條路徑,後面可選擇性地附上查詢字串)。Express 會按你註冊路由的次序,逐一將每個請求與路由比對。只有當方法及路徑模式兩者都符合時,路由才會匹配:
| 請求 | app.get('/items/:id') | app.patch('/items/:id') |
|---|---|---|
GET /items/1 | 匹配 | 不匹配(方法錯誤) |
PATCH /items/1 | 不匹配(方法錯誤) | 匹配 |
GET /items | 不匹配(路徑缺少 id 區段) | 不匹配 |
方法表達的是要做甚麼,路徑則識別哪一項資源。
2. 路徑參數與查詢字串
路徑參數可用來識別某一項特定資源。在 /items/:id 中,請求 /items/42 會得到 req.params.id === '42'。這個單一區段的 :id 參數是字串,因此使用以字串作鍵的 Map 可避免數字與字串不一致的問題。不要將此推廣至所有 Express 5 參數:萬用字元參數可以包含由路徑區段組成的陣列。
查詢字串用來細化或篩選一個集合:在 /items?q=note 中,Express 會提供 req.query.q。查詢字串不參與路由匹配,因此 /items 與 /items?q=note 會到達同一個處理函式。重複的鍵,例如 ?q=a&q=b,可能產生一個陣列。使用該值之前,請先檢查 typeof req.query.q === 'string'。
一條實用規則:如果移除該值會令你指向另一項資源,就用路徑;如果它只是收窄一個列表,就用查詢字串。
反例模式
數字鍵永遠匹配不到路徑參數
有人聲稱:儲存結構可以用數字作鍵,因為請求 GET /items/1 選的是項目 1。假設儲存結構是 new Map([[1, { id: 1, name: 'Sample item' }]]),而處理函式執行 items.get(req.params.id)。對於 GET /items/1,req.params.id 是字串 '1'。Map 以 same-value-zero 規則比較鍵,不會把 '1' 與 1 視為相等,所以 items.get('1') 傳回 undefined,處理函式便回應 404,儘管項目其實存在。應像完整示例那樣保持鍵為字串;或者先確認參數是規範的整數字串,再有意識地轉換一次。
3. JSON 主體、Content-Type 與中介軟件次序
瀏覽器會在請求主體中傳送 JSON,並以 Content-Type: application/json 標示。Express 不會自動讀取主體。express.json() 中介軟件會讀取並解析主體,但只限於請求的 Content-Type 符合其 type 選項的情況,而該選項的預設值為 application/json。
有三種情況必須區分清楚:
- 類型符合,JSON 被接受。
req.body存放解析後的值。預設設定strict: true接受物件及陣列;下文的路由其後會再進行更嚴格的物件及欄位驗證。 - 類型符合,但 JSON 格式錯誤或不獲允許。 解析器會略過一般的路由處理函式,並轉交一個錯誤:狀態
400,類型'entity.parse.failed'。即使是語法有效的純量 JSON,例如42或null,也會被strict: true拒絕。 - 類型不符合或缺少類型。 若之前沒有其他主體解析器,
req.body會維持為undefined。這並非解析錯誤。下文的 POST 及 PATCH 處理函式若被執行到而類型檢查失敗,會選擇回應415 Unsupported Media Type。
次序很重要。app.use(express.json()) 必須在讀取 req.body 的路由之前註冊。錯誤處理中介軟件接受四個參數 (err, req, res, next),並在路由之後註冊。
常見錯誤
(太早註冊後備處理函式或解析器)
註冊次序就是比對次序。放在路由之前的萬用 app.use((req, res) => res.status(404).json(...)) 會令每個請求都得到 404,包括 GET /items/1,因為它最先匹配並送出回應。放在路由之後的解析器,則會令那些路由中的 req.body 為 undefined。正確次序是:先註冊解析器,然後是路由,接著是 404 後備處理函式,最後才是錯誤中介軟件。
4. 驗證、return 與 next
一個請求最多只應收到一個最終回應。處理函式必須完成回應,或將控制權向後傳遞。寫 return res.status(400).json(...) 會傳送回應並結束該函式,因此其後的語句無法嘗試傳送第二個回應。
調用 next() 的作用則不同。它會將控制權交給下一個匹配的路由或中介軟件。調用 next(err) 會略過一般中介軟件,轉往錯誤處理函式。當由你作出回應時,使用 return res...;當應由另一層作出回應時,使用 next(err)。
要安全地驗證屬性是否存在。像 body.name !== undefined 這樣的檢查,會遺漏屬性存在但其值為 undefined 的情況;而 'name' in body 亦會找到繼承自原型的屬性。Object.hasOwn(body, 'name') 及 Object.keys(body) 只考慮物件自身的屬性。此外,請先確認主體是一個普通物件。JSON 陣列可以成功解析,但在此並非有效輸入。
常見錯誤
(真值檢查不是驗證)
if (!body.name) return res.status(400)... 這類檢查會拒絕缺少的名稱和空字串,卻接受任何真值。對於請求體 {"name":42} 或 {"name":["a"]},該值是真值,檢查通過,之後調用 body.name.trim() 便丟出 TypeError,因為數字和陣列都沒有 trim 方法。Express 於是回應 500,把本屬客戶端的錯誤當作伺服器故障。應像 isValidName 那樣明確檢查類型與範圍,令這類輸入得到 400。
5. 狀態、標頭與主體
一個回應包含三部分:
- 一個狀態碼,例如
200或404; - 標頭,例如
Content-Type及Location; - 一個主體,在此為 JSON。
res.status(code) 設定狀態。res.location(url) 設定 Location。res.json(value) 將該值序列化,設定 Content-Type: application/json; charset=utf-8,並傳送回應。
6. 完整示例
以下是一個示範用的 Express 5 CommonJS 程式,需要 Node.js 18 或以上版本。本章並未安裝或執行過此程式。路由處理函式中所寫的回應是為教學而作的設計選擇;解析器失敗則遵循 Express/body-parser 的行為。
'use strict';
const express = require('express');
const app = express();
app.disable('x-powered-by');
app.set('etag', false);
// In-memory store: one process only, reset on every restart.
const items = new Map([['1', { id: '1', name: 'Sample item' }]]);
let nextId = 2; // classroom counter; assumed to stay within the safe integer range
function isPlainObject(value) {
return typeof value === 'object' && value !== null
&& Object.getPrototypeOf(value) === Object.prototype;
}
function isValidName(value) {
return typeof value === 'string'
&& value.trim().length > 0
&& value.trim().length <= 100;
}
app.use(express.json());
// GET collection, optional ?q= filter -> 200
app.get('/items', (req, res) => {
const q = typeof req.query.q === 'string' ? req.query.q.toLowerCase() : '';
const list = [...items.values()].filter((item) =>
item.name.toLowerCase().includes(q));
res.status(200).json(list);
});
// GET one -> 200 or 404
app.get('/items/:id', (req, res) => {
const item = items.get(req.params.id);
if (!item) {
return res.status(404).json({ error: 'Item not found' });
}
res.status(200).json(item);
});
// POST create -> 201, 400 or 415
app.post('/items', (req, res) => {
if (!req.is('application/json')) {
return res.status(415).json({ error: 'Content-Type must be application/json' });
}
const body = req.body;
if (!isPlainObject(body) || !Object.hasOwn(body, 'name') || !isValidName(body.name)) {
return res.status(400).json({ error: 'name must be a non-empty string (max 100)' });
}
const id = String(nextId++);
const item = { id, name: body.name.trim() };
items.set(id, item);
res.status(201).location(`/items/${id}`).json(item);
});
// PATCH update -> 200, 400, 404 or 415
app.patch('/items/:id', (req, res) => {
const item = items.get(req.params.id);
if (!item) {
return res.status(404).json({ error: 'Item not found' });
}
if (!req.is('application/json')) {
return res.status(415).json({ error: 'Content-Type must be application/json' });
}
const body = req.body;
if (!isPlainObject(body)) {
return res.status(400).json({ error: 'Body must be a JSON object' });
}
const keys = Object.keys(body);
if (keys.length !== 1 || keys[0] !== 'name') {
return res.status(400).json({ error: 'Only the name field may be updated' });
}
if (!isValidName(body.name)) {
return res.status(400).json({ error: 'name must be a non-empty string (max 100)' });
}
item.name = body.name.trim();
res.status(200).json(item);
});
// Unmatched method/path -> 404
app.use((req, res) => {
res.status(404).json({ error: 'Route not found' });
});
// Error middleware: malformed/disallowed JSON; other errors are delegated
app.use((err, req, res, next) => {
if (err.type === 'entity.parse.failed') {
return res.status(400).json({ error: 'Invalid JSON body: expected an object or array' });
}
next(err);
});
app.listen(3000);
關於此示例的一些設計說明:
req.is()會同時檢查內容類型及 HTTP 主體的分幀;它不會驗證 JSON 或必需欄位。不要僅憑沒有負載位元組就推斷回應結果。例如,一個已分幀的空 JSON 主體可以到達欄位驗證,並收到400。- 全局 JSON 解析器在每條路由之前執行。因此,即使是
PATCH /items/99,格式錯誤的 JSON 主體也會產生400;id 檢查根本不會被執行到。一旦解析成功或被略過,PATCH 處理函式會先檢查項目是否存在,因此未知的 id 會在內容檢查之前收到404。 - 其他解析器錯誤會被轉交:過大的主體會收到
413,不支援的字元集或內容編碼會收到415。Express 的預設處理函式會採用錯誤本身的4xx或5xx狀態,否則使用500。其主體並非本應用程式的 JSON 錯誤格式。
7. 解題實例
例題 8.1.2
(建立項目並讀回)
以下追蹤是人手建構的,並非從執行中的伺服器擷取。它概略展示客戶端請求及預期回應。Date 的值會有所不同,而 Node.js 的連線標頭(Connection、Keep-Alive)已被省略。內容長度計算的是 UTF-8 負載位元組,不包括主體之後為顯示而加的換行。
POST /items HTTP/1.1
Host: localhost:3000
Content-Type: application/json
Content-Length: 19
{"name":"Notebook"}
HTTP/1.1 201 Created
Location: /items/2
Content-Type: application/json; charset=utf-8
Content-Length: 28
Date: <varies>
{"id":"2","name":"Notebook"}
沿著請求走過整個程式。express.json() 看到 Content-Type: application/json,讀取 19 個位元組的主體,並把 req.body 設為 { name: "Notebook" }。路由器因方法不同而略過兩條 GET 路由,進入 POST /items 處理函式。在那裏,req.is('application/json') 為真值,主體是帶有自身 name 屬性的普通物件,isValidName 接受該字串。處理函式取得 id '2',把 nextId 增至 3,儲存項目,並以 201、Location 標頭及 JSON 主體回應。讀回狀態可確認變更:GET /items/2 以 200 傳回同一個物件,而 GET /items?q=note 傳回只含該項目的陣列,因為 'sample item' 不含 note,'notebook' 則含有。
例題 8.1.3
(每個請求由哪一層回應)
結果摘要,假設上述示範的 POST 已建立項目 2。除另有說明外,帶主體的請求均使用 Content-Type: application/json,採用一般 UTF-8 編碼,且大小在解析器的限制之內:
| 請求 | 結果 |
|---|---|
GET /items/1 | 200,連同示例項目 |
GET /items/99 | 404 {"error":"Item not found"} |
POST /items,主體為 {"name":" "} | 400 |
POST /items,主體為 {"name": | 400,連同上文的 JSON 解析器錯誤訊息 |
POST /items,主體為 42 | 400,因為嚴格 JSON 解析會拒絕純量 |
POST /items,使用 Content-Type: text/plain | 415 |
PATCH /items/2,主體為 {"name":"Diary"} | 200 |
PATCH /items/2,主體為 {"color":"red"} | 400 |
PATCH /items/99 | 404 |
PATCH /items/99,JSON 格式錯誤 | 400,在 id 檢查之前 |
按產生回應的層次把各行分組。在任何路由執行之前,錯誤中介軟件回應解析器拒絕的兩種主體:被截斷的 {"name": 及被 strict 拒絕的純量 42。其餘由路由處理函式回應:未知 id 得 404,req.is 失敗得 415,空白名稱或多餘欄位等驗證失敗則得 400。對 PATCH /items/99,id 檢查先於主體檢查,所以格式正確的主體仍得 404;格式錯誤的 JSON 根本到不了處理函式,得 400。因此,這個表格記錄的不只是一串狀態碼,還有各項檢查的次序。
例題 8.1.4
(太遲註冊解析器)
假設把程式中的兩行註冊對調,使路由排在前面。
// Faulty order: the routes are registered before the parser.
app.post('/items', createItem); // the same handler as in the full example
app.use(express.json());
客戶端發送與第一個實例相同的成功請求:POST /items,Content-Type: application/json,主體為 {"name":"Notebook"}。路由器在解析器執行之前便到達 POST /items 處理函式,所以 req.body 仍是 undefined。處理函式中的 req.is('application/json') 只檢查標頭,所以會通過,不會得 415。接著 isPlainObject(undefined) 為假,處理函式回應 400 {"error":"name must be a non-empty string (max 100)"}。同一個輸入現在失敗了,而訊息把責任推給輸入,其實問題在註冊次序。格式錯誤的主體也只會得到這個籠統的 400,而不是解析器的錯誤回應。修正方法是把 app.use(express.json()) 註冊在每一條讀取 req.body 的路由之前。
8. 客戶端:Promise、response.ok 與 DOM
fetch 在瀏覽器中會傳回一個 Promise。當回應標頭到達時,它便會兌現(resolve),即使狀態是 404 或 500 亦然。請求失敗,包括網絡錯誤、無效請求及取消,則可能令它被拒絕(reject)。在將回應視為成功之前,請先檢查 response.ok;狀態為 200–299 時它為 true。
async function createItem(name) {
const response = await fetch('/items', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name }),
});
if (!response.ok) {
throw new Error(`Create failed with status ${response.status}`);
}
return response.json(); // another Promise: the parsed body
}
response.json() 以非同步方式讀取並解析主體,而它本身也可能被拒絕,例如伺服器傳回無效 JSON 時。createItem 的調用者必須處理這兩個階段的失敗。
伺服器的 Map 與網頁的 DOM 是分屬兩個不同程式的獨立狀態。一個成功的 POST 會改變 Map,但網頁只會在客戶端程式碼其後更新 DOM 時才改變。單是編輯 DOM 並不會改變伺服器;事件處理函式需要再傳送一個請求。
兩個請求不一定按瀏覽器發出它們的次序完成。若不檢查哪項操作仍屬最新,就根據每個回應更新 DOM,可能會顯示過時的數據。在此示例中,每項伺服器變更都是同步的,但互相競爭的 PATCH 請求仍會按伺服器處理的次序覆寫同一個名稱。這裏沒有版本檢查,而重試 POST 可能會建立第二個項目。可靠的衝突處理及重試去重需要明確的設計。
重新啟動 Node 程序會重新建立只含單一示例項目的 Map,並將 nextId 重設為 2。執行兩個程序會得到兩個互相獨立的 Map。要在多個程序之間保存及協調此狀態,需要持久的共享儲存(通常是數據庫)及適當的並行控制。
9. 練習
快速檢查
(由哪個處理函式回應?)
對完整示例,說明下列請求的回應:(a) DELETE /items/1、(b) POST /items/1、(c) GET /items?q=a&q=b。
解答
(a) 沒有任何路由註冊 DELETE,請求落到最後的處理函式:404 {"error":"Route not found"}。(b) POST 只為 /items 註冊,所以 POST /items/1 同樣到達最後的處理函式,得到相同的 404。較嚴謹的 API 可能回應 405 Method Not Allowed 並附上 Allow 標頭,但本程式不是這樣。(c) 路由 GET /items 匹配。req.query.q 是陣列,所以 typeof req.query.q === 'string' 為假,q 成為空字串,以 200 傳回所有項目。
快速檢查
(選擇狀態碼)
對 POST /items,給出狀態碼及產生它的層次:(a) JSON 主體 {"name":42};(b) JSON 主體 {"name":;(c) Content-Type: text/plain,主體為 hello。
解答
(a) 路由處理函式回應 400:主體能解析,但 isValidName 拒絕數字。(b) 錯誤中介軟件回應 400:解析器以 entity.parse.failed 失敗,處理函式從未執行。(c) 路由處理函式回應 415:express.json() 略過不符合的類型,令 req.body 維持為 undefined,然後 req.is('application/json') 失敗。
快速檢查
(重複回應)
找出缺陷:app.get('/items/:id', (req, res) => { const item = items.get(req.params.id); if (!item) res.status(404).json({ error: 'Item not found' }); res.status(200).json(item); });
解答
404 分支沒有 return,所以程式繼續執行第二句 res.status(200).json(item)。客戶端已收到 404,第二次嘗試對已送出的回應設定標頭,令 Node 擲出 ERR_HTTP_HEADERS_SENT。修正方法是 return res.status(404).json({ error: 'Item not found' });,既傳送回應,又結束函式。
快速檢查
(有效輸入卻得 400)
重構之後,POST /items 帶 Content-Type: application/json 及主體 {"name":"Diary"} 傳回 400,但處理函式的程式碼沒有改動。最可能的原因是甚麼?如何確認?
解答
最可能的原因是 app.use(express.json()) 現在排在路由之後,或已被移除,所以處理函式執行時 req.body 是 undefined。isPlainObject(undefined) 為假,因而得 400。要確認,可在處理函式開頭記錄 req.body,或比對 app.use 與路由註冊的次序;修正方法是先註冊解析器。
快速檢查
(在瀏覽器中讀取 404)
瀏覽器執行 const response = await fetch('/items/99');。這個 Promise 會怎樣?response.ok 與 response.status 是甚麼?調用 response.json() 之前,程式碼必須檢查甚麼?
解答
Promise 會兌現,因為回應標頭已到達;HTTP 失敗狀態不會令它被拒絕。response.status 是 404,response.ok 是 false。程式碼應先檢查 response.ok,才把主體當作項目。這裏的主體是 {"error":"Item not found"},response.json() 能順利解析,所以若跳過檢查,會默默把錯誤物件當作數據。