瀏覽器已經收到回應,response.ok 為真,await response.json() 也已回傳。程式現在就可以顯示 data.workshops[0].title 嗎?只有在它已確認回應確實包含這個運算式需要的數據時,才可以這樣做。JSON 解析確立的是表示形式的規則;應用程式仍須確立自己的數據規則。
本章研究解析與呈現之間的一步:把形狀未知的值轉成定義清楚的小型集合,再一致地替換畫面上的集合。例子是教學模型,並不描述任何真實服務。
1. 每一步成功,回答的問題都不同
假設示例端點 GET /api/workshops 的用途是列出工作坊及剩餘名額。考慮以下幾個階段:
| 階段 | 已確立的事實 | 仍須確立的事實 |
|---|---|---|
| Fetch 兌現 | 這次調用已取得目前腳本可以存取的回應。 | 狀態碼是否符合端點約定。 |
| HTTP 狀態符合預期 | 狀態碼符合這個端點的成功約定。 | 回應主體的表示形式和數據是否符合預期。 |
| JSON 解析兌現 | 回應主體已讀取並解析為 JSON。 | 所得值是否具備所需欄位與含義。 |
| 應用程式驗證成功 | 這個值通過了我們明確寫出的檢查。 | 畫面是否正確呈現它,以及數據對讀者的用途而言是否足夠新。 |
| DOM 替換完成 | 這個腳本已安裝新的顯示集合。 | 瀏覽器是否已繪製畫面,以及回應產生後伺服器狀態是否已改變。 |
不應默默把這些結論說得更強:狀態碼不會確立數據結構約定,而數據結構約定也不會確立時效性或權限。
例如,下列內容全部都是有效的 JSON:
null
["CSS", "DOM"]
{"workshops":"temporarily unavailable"}
但它們都不是我們即將定義的工作坊集合。解析器可以正確地接受它們,應用程式也可以正確地拒絕它們。這是兩種不同的判斷。
2. 先寫清約定,再讀取屬性
定義 5.2.1
(回應契約)
回應契約是接受一個回應所須滿足的條件的明確清單:狀態碼、媒體類型、解析後值的形狀、每個欄位的含義與範圍,以及欄位之間和記錄之間的關係。只有契約已確立某個屬性存在而且類型正確,程式才可讀取它。
本例刻意採用一個小型服務約定:
- 成功回應的狀態碼為
200,媒體類型為application/json,後面可以附上charset=utf-8等參數。 - 解析後的根值必須是非 null 物件,並且不能是陣列。它的
workshops欄位必須是最多有 50 個項目的陣列。空陣列表示目前沒有列出的工作坊。 - 每個項目都必須是非 null 物件,並且不能是陣列。它包含
id、title、capacity和seatsRemaining。 - ID 由一個大寫 ASCII 字母及其後恰好兩個十進制數字組成。同一份回應內的 ID 不得重複。這個人為訂出的格式只是示例約定,並非網頁識別碼的通用規則。
- 標題必須是字串。去除開頭與結尾的空白後,長度須介乎 1 至 80 個 JavaScript 字串碼元。這是碼元數量的上限,不是可見字元的數量。
- 容量必須是 1 至 30 的整數。剩餘名額必須是 0 至容量之間的整數,兩端都包括在內。
- 可以有額外欄位,但不會把它們複製進供畫面使用的數據模型。
因此,一份有效回應可以包含:
{
"workshops": [
{"id":"D14","title":" DOM practice ","capacity":12,"seatsRemaining":0},
{"id":"F27","title":"Fetch clinic","capacity":20,"seatsRemaining":7}
],
"generatedFor":"teaching example"
}
第一個工作坊已滿,這是合法的狀態;若因為 !item.seatsRemaining 為真就拒絕它,便把零與缺少值混為一談。同樣,"7" 雖然看來像數字,仍是字串,用戶端應拒絕它,而不是默默修補服務回應。
不等式 seatsRemaining <= capacity 是欄位之間的關係:容量 8、剩餘名額 11 的記錄能通過各項整數檢查,卻違反剩餘容量的含義。唯一性則是記錄之間的關係:兩個項目可以各自格式正確,但重複的 ID 會令之後的選取、以鍵識別的數據行或更新請求產生歧義。所以,驗證既須檢查項目,也須檢查集合。
常見錯誤
(在修剪前量度標題長度)
對原始字串檢查 item.title.length,之後才修剪,是問錯了問題。" " 的長度是 3,通過 item.title.length > 0,修剪後卻是空的,列表會出現空白行。反過來,修剪後長 80 個碼元的標題若前面有空格,會被錯誤拒絕。應先修剪,再檢查長度。
3. 解碼一次,只回傳頁面實際使用的數據
以下函式是同步函式。輸入是 JSON 解析後所得的值,而不是 JSON 文字。它要麼擲出錯誤,要麼回傳一個新陣列,其中包含具有上述欄位的新記錄。
function isRecord(value) {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function decodeWorkshops(value) {
if (!isRecord(value) || !Array.isArray(value.workshops) ||
value.workshops.length > 50) {
throw new Error("Expected a workshop collection with at most 50 entries");
}
const seenIds = new Set();
return value.workshops.map((item, index) => {
if (!isRecord(item)) {
throw new Error(`Workshop ${index + 1} is not a record`);
}
if (typeof item.id !== "string" || item.id.length !== 3 ||
!/^[A-Z][0-9]{2}$/.test(item.id)) {
throw new Error(`Workshop ${index + 1} has an invalid ID`);
}
if (seenIds.has(item.id)) {
throw new Error(`Workshop ${index + 1} repeats an ID`);
}
if (typeof item.title !== "string") {
throw new Error(`Workshop ${index + 1} has no text title`);
}
const title = item.title.trim();
if (title.length === 0 || title.length > 80) {
throw new Error(`Workshop ${index + 1} has an invalid title length`);
}
if (!Number.isInteger(item.capacity) || item.capacity < 1 || item.capacity > 30 ||
!Number.isInteger(item.seatsRemaining) || item.seatsRemaining < 0 ||
item.seatsRemaining > item.capacity) {
throw new Error(`Workshop ${index + 1} has inconsistent seat counts`);
}
seenIds.add(item.id);
return {
id: item.id,
title,
capacity: item.capacity,
seatsRemaining: item.seatsRemaining
};
});
}
名稱 isRecord 只描述本例採用的有限形狀檢查。解碼函式預期收到的是一般瀏覽器中 JSON 解析後未經修改的輸出,而不是任意帶有 getter、代理物件或被修改原型的物件。
檢查次序很重要:讀取 item 的欄位前,先確立它不是 null;調用 .trim() 前,先確立 title 是字串。typeof null 的結果是 "object",陣列也屬於物件,所以輔助函式會明確排除這兩者。如果第三個項目不合格,.map() 會在回傳陣列之前擲出錯誤,沒有任何東西交給呈現函式:無效輸入不會造成只接受了部分項目的清單。這並不會撤銷任何伺服器操作。
例題 5.2.2
(找出最早失敗的假設)
每一行都視為對新輸入進行的獨立調用。對簡寫的項目例子,假設其他欄位有效,根值則為 { "workshops": [entry] }。
| 輸入或被修改的欄位 | 解碼結果 | 原因 |
|---|---|---|
根值為 null | 在根值檢查時擲出錯誤。 | 尚無理由可以讀取物件欄位。 |
根值為 { "workshops": [] } | 回傳 []。 | 這份約定容許空集合。 |
根值為 { "workshops": {} } | 在根值檢查時擲出錯誤。 | 物件不是陣列。 |
seatsRemaining: 0、capacity: 12 | 接受項目。 | 零是容許區間內的整數。 |
seatsRemaining: "0"、capacity: 12 | 在名額檢查時擲出錯誤。 | 整數驗證不會強制轉換字串。 |
seatsRemaining: 13、capacity: 12 | 在名額檢查時擲出錯誤。 | 欄位之間的不等式不成立。 |
title: " " | 在標題長度檢查時擲出錯誤。 | 去除空白後,標題沒有內容。 |
兩個其他方面有效的項目都使用 D14 | 在第二個項目擲出錯誤。 | 集合違反 ID 唯一性。 |
對上面包含兩個項目的有效回應,解碼函式會把 D14 的標題回傳為 "DOM practice",並保留剩餘名額零。頁面可以用 capacity - seatsRemaining 算出:D14 有 12 個名額已被佔用,F27 有 13 個。由於最多 50 個工作坊、容量最多 30,這些加減遠在 JavaScript 數值可精確表示的整數範圍之內。
反例模式
typeof 為 number 不等於座位數
有人聲稱:typeof item.capacity === "number" && typeof item.seatsRemaining === "number" && item.seatsRemaining <= item.capacity 足以驗證名額。取 capacity: 12.5 和 seatsRemaining: 3.25:兩者都是數字且 3.25 <= 12.5,檢查通過,已佔用名額 9.25 並不是個數。字面量 1e400 也是合法 JSON,JSON.parse 把它變成 Infinity,類型同樣是 "number";配上 seatsRemaining: 5,檢查通過,已佔用數目是 Infinity。Number.isInteger 拒絕 12.5 和 Infinity,再加上範圍檢查。
4. 把準備畫面與替換已顯示畫面分開
一種容易想到的呈現方式,是先清空舊清單,再逐一驗證並加入項目。如果第三個項目失敗,畫面上已有兩行,舊清單卻已消失,讀者無法分辨是只有兩個工作坊,還是載入到一半出了問題。
對這種小型回應,應先驗證整個值,再在尚未連接到文件的 DocumentFragment 中建立所有替換用的數據行。只有準備工作成功後,程式才替換清單的子節點。
function prepareWorkshopList(workshops) {
const fragment = document.createDocumentFragment();
if (workshops.length === 0) {
const row = document.createElement("li");
row.textContent = "No workshops are currently listed.";
fragment.append(row);
return fragment;
}
for (const workshop of workshops) {
const row = document.createElement("li");
const title = document.createElement("strong");
title.textContent = workshop.title;
const seats = document.createElement("span");
seats.textContent =
` — ${workshop.seatsRemaining} of ${workshop.capacity} seats available`;
row.dataset.workshopId = workshop.id;
row.append(title, seats);
fragment.append(row);
}
return fragment;
}
結構由程式建立,而每個標題都成為文字:例如 "<em>DOM</em>" 會保持字面字元,不會建立元素。使用 textContent 可避免在這項操作中把文字解讀為 HTML;這並不說明之後把同一個值用作 URL 或 CSS 時是否適當。
準備完成後,list.replaceChildren(fragment) 以片段的子節點替換舊子節點,片段本身隨之變空。這種做法減少應用程式層面的局部清單問題,但不保證所有 DOM 操作具有交易性。
5. 連接各個階段,但不虛構一個已存在的伺服器
把以下標記放入頁面。假設腳本在這些標記之後執行一次,並且註冊監聽器之前,前面兩個函式定義已可供使用。
<button id="reload-workshops" type="button">Reload workshops</button>
<p id="workshop-status" role="status">No list has been loaded.</p>
<ul id="workshop-list"></ul>
const reloadButton = document.querySelector("#reload-workshops");
const status = document.querySelector("#workshop-status");
const list = document.querySelector("#workshop-list");
async function readWorkshops(response) {
if (response.status !== 200) {
throw new Error("Unexpected workshop response status");
}
const mediaType = (response.headers.get("Content-Type") ?? "")
.split(";")[0].trim().toLowerCase();
if (mediaType !== "application/json") {
throw new Error("Expected a JSON media type");
}
const value = await response.json();
return decodeWorkshops(value);
}
reloadButton.addEventListener("click", async () => {
reloadButton.disabled = true;
status.textContent = "Loading; any displayed list is from an earlier load.";
try {
const response = await fetch("/api/workshops", {
headers: { Accept: "application/json" }
});
const workshops = await readWorkshops(response);
const fragment = prepareWorkshopList(workshops);
list.replaceChildren(fragment);
status.textContent = `Loaded ${workshops.length} workshops.`;
} catch {
status.textContent =
"Could not load a usable list. Any displayed list is from an earlier load.";
} finally {
reloadButton.disabled = false;
}
});
這個端點是例子的假設。Accept 標頭只表達偏好,不能強迫伺服器回傳有效 JSON。我們依據嚴格約定核對所宣告的 Content-Type,接著由解析檢查實際語法,所以以 text/plain 傳送的有效 JSON 會被刻意拒絕。
本例要求恰好是 200,而不是採用 response.ok,因為這份約定承諾該狀態碼及一份回應主體。204 是成功狀態,卻沒有工作坊的表示數據;沒有內容也不等同於 { "workshops": [] },後者是明確的空集合。這是特定端點的設計決定。
按鈕在等待期間停用,所以本程式一次只處理一個載入。這不是通用的競態控制:如果其他程式碼也能發起載入,可用請求序號避免較早的回應覆蓋較新的結果。
留意失敗時的策略。載入期間,以及回應、解析或驗證任何一步失敗之後,舊清單都會保留,狀態文字說明它來自較早的載入;若把它標示為最新便會誤導讀者。成功取得的空集合則以空清單訊息替換舊數據行。失敗與成功的空結果不應看起來一樣。
例題 5.2.3
(四種回應走過 readWorkshops)
每一行都是對 readWorkshops 的獨立調用;之後由點擊處理函式決定畫面顯示甚麼。
| 回應 | 在載入程式中的路徑 | 畫面結果 |
|---|---|---|
200、application/json; charset=utf-8,內容 {"workshops":[]} | 狀態碼與媒體類型通過,解析成功,解碼函式回傳 [] | 空清單訊息替換舊數據行;狀態文字為 Loaded 0 workshops. |
200、text/html 錯誤頁 | 媒體類型檢查在讀取內容前擲出錯誤 | 舊數據行保留;狀態文字說明沒有可用清單 |
204、沒有內容 | 狀態碼檢查擲出錯誤 | 舊數據行保留;狀態文字說明沒有可用清單 |
200、application/json,內容 {"workshops":"temporarily unavailable"} | 解析成功;解碼函式的根值檢查擲出錯誤 | 舊數據行保留;狀態文字說明沒有可用清單 |
只有第一行會改變顯示的集合。其餘三行都讓舊數據行保持原樣,因為各自在不同階段失敗:狀態碼、媒體類型、解碼後的形狀。依次細看便知道這些階段為何要分開:HTML 頁面根本到不了 response.json(),而第四份內容是完全正確的 JSON,卻仍不是工作坊集合。
例題 5.2.4
(第二次重新載入含有錯誤記錄)
假設第一次載入已成功完成,清單包含 D14 和 F27。
- 讀者按下重新載入。按鈕停用,兩個舊數據行仍在,而狀態文字說明它們來自較早的載入。
- Fetch 取得
200 application/json回應,其workshops陣列包含三筆記錄。 - JSON 解析成功。前兩筆記錄通過解碼函式,但第三筆為
capacity: 6、seatsRemaining: 9。 - 解碼函式擲出錯誤,因此
readWorkshops拒絕;控制流程離開正在等待的調用並進入catch。prepareWorkshopList和replaceChildren都沒有執行。 - 舊數據行仍是
D14和F27。狀態文字指出未能載入可用清單,而finally重新啟用按鈕,容許再次嘗試。
結論並非「伺服器列出了兩個工作坊」,而是「替換用結果未能符合已訂明的約定,所以本頁仍顯示之前成功取得的結果」。介面應向讀者交代的,正是這項證據。
現在只把第二份回應改為 { "workshops": [] }。驗證會回傳空陣列,準備階段會建立空清單訊息,替換操作會移除兩個舊工作坊數據行。狀態文字是 Loaded 0 workshops.,並沒有發生失敗。
6. 選定一種解讀方式,只讀取回應主體一次
讀取回應主體會消耗它。因此,對一般回應而言,以下除錯次序是錯的:
const debugText = await response.text();
const data = await response.json(); // the same body has already been consumed
第二次調用通常會因為主體已經使用而拒絕。應預先選定讀取策略;如果確實需要先取得文字,就只讀一次,再對該字串調用 JSON.parse,然後驗證。這改變了解析錯誤發生的位置,卻沒有免除驗證的需要。
7. 驗證函式證明了甚麼,尚未證明甚麼
decodeWorkshops 成功回傳後,保證輸出具有上述標題、身份及名額性質,足以支持可預期的顯示與有界運算。但它不證明伺服器所報名額真實或仍是最新,也不證明讀者有權預約;預約請求必須由伺服器驗證並授權,容量也由伺服器強制執行。用戶端的數量是資訊,不是鎖。
溫習時,依次追蹤四種表示:回應物件、解析值、已驗證集合、準備好的 DOM。在每個轉換處,說明正在檢查哪個假設,以及失敗時如何處理。這樣,屬性讀取、算術與可見更新便各有正確的理由,而不是單憑某一份順利回應的樣本形狀來猜測。
練習
快速檢查
(根值的形狀)
解析後的值是 JSON 陣列 [{ "id": "D14", "title": "DOM practice", "capacity": 12, "seatsRemaining": 0 }]。decodeWorkshops 會接受嗎?由哪個檢查決定?為何在該檢查之前不讀取任何屬性?
解答
會擲出錯誤。isRecord 排除陣列,所以 !isRecord(value) 為真,函式在計算 value.workshops 之前就擲出錯誤。約定要求根值是含有 workshops 陣列的物件;陣列根值是有效的 JSON,卻不是這個集合。
快速檢查
(零的陷阱)
同事寫了 if (!item.seatsRemaining) throw new Error("missing seats");。舉出兩個被這行處理錯誤的輸入,並改用約定要求的檢查。
解答
0 是假值,所以 seatsRemaining: 0 的已滿工作坊被拒絕,但約定容許這種情況。字串 "7" 是真值,因此通過檢查,但約定要求的是數值。正確的檢查是 Number.isInteger(item.seatsRemaining) && item.seatsRemaining >= 0 && item.seatsRemaining <= item.capacity,並在 capacity 本身通過驗證之後才執行。
快速檢查
(內容正確,標示錯誤)
伺服器以 200 回應,Content-Type: text/plain,內容為 {"workshops":[]}。頁面顯示甚麼?舊清單會保留嗎?
解答
readWorkshops 在媒體類型檢查時擲出錯誤,所以從未調用 response.json()。點擊處理函式的 catch 把狀態文字設為失敗訊息,舊數據行保留,並標明來自較早的載入。內容本來是有效的空集合,但這份約定同時要求所宣告的媒體類型必須是 application/json。
快速檢查
(標題中的標記)
某個項目的標題是 "<b>Hi</b>"。解碼函式會接受嗎?讀者在清單中看到甚麼?
解答
解碼函式會接受:它是字串,去除空白後長度為 9,在 1 至 80 之內。驗證檢查的是形狀和範圍,不是標記。prepareWorkshopList 把它指定給 textContent,所以讀者看到的是字面字元 <b>Hi</b>,不會建立粗體元素。形狀驗證與輸出處理回答的是不同問題。
快速檢查
(重複的 ID)
兩個其他方面有效的項目都使用 ID D14。哪一項檢查會失敗?在哪個項目?有甚麼會交給呈現函式?
解答
第一個項目通過,其 ID 被加入 seenIds。到第二個項目時 seenIds.has(item.id) 為真,解碼函式擲出「Workshop 2 repeats an ID」。沒有任何東西交給呈現函式,點擊處理函式的 catch 執行,舊數據行保留。唯一性是記錄之間的關係,所以只有記得先前項目的檢查才能發現它。