浏览器已经收到响应,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 会让之后的选取、按键标识的数据行或更新请求产生歧义。所以,验证既须检查项目,也须检查集合。
常见错误
(在修剪前度量标题长度)
对原始字符串检查长度,之后才修剪,是问错了问题。" " 的长度是 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:检查通过,但已占用名额 9.25 不是整数。1e400 是合法 JSON,JSON.parse 得到 Infinity,类型仍是 "number";配上 seatsRemaining: 5 同样通过。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 执行,旧数据行保留。唯一性是记录之间的关系,所以只有记得先前项目的检查才能发现它。