使用 fetchLater() 实现全会话分析:Modern Web Guidance 中 full-session-analytics 验收标准与实现详解

原创2026-11-12 11:38:421,861 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

使用 fetchLater() 实现全会话分析:Modern Web Guidance 中 full-session-analytics 验收标准与实现详解

在 Web 分析场景里,真正困难的不是“采集指标”,而是“把会话最后一段、也就是用户关闭标签页或跳转离开时的数据可靠地送达服务端”。本指南以 Modern Web Guidance 仓库中的 guides/performance/full-session-analytics/expectations.md 为骨架,逐条拆解 fetchLater() 方案的验收标准,并结合同目录的 guide.md、demo.html 与自动化 grader.ts,说明每一条要求为什么成立、如何在代码中落地、以及如何被仓库的评测流水线验证。读完后你应能独立写出一个既不阻塞交互、又不破坏 bfcache 的会话级埋点实现。

一、这份 expectations.md 定义了什么样的“合格实现”

guides/performance/full-session-analytics/expectations.md 只有五条,但每一条都对应一个可被自动化断言的外部可观察行为:

编号 验收要求 本质约束
1 fetchLater() 以 URL 字符串为第一个参数,可选地传 DeferredRequestInit 作为第二个参数 调用签名正确
2 fetchLater() 是唯一的 beacon 发送 API,不得使用 fetch()、sendBeacon()、XMLHttpRequest 或 new Image() 发送通道单一化
3 只发送一次 beacon,且发生在用户离开页面之后 延迟交付与去重
4 当调用抛出 QuotaExceededError、RangeError 或 TypeError 时必须被妥善处理 异常可恢复
5 除非项目只支持 Chromium,否则必须把 fetchLater() polyfill 打进产物 兼容性兜底

这五条构成了一个“最小但完备”的契约:正确的 API、唯一的通道、正确的时机、可控的失败、可用的降级。下面的章节按此顺序展开,并补充仓库中对应的实现证据与测试证据。

二、验收点 1:调用签名与 DeferredRequestInit

第一条要求很直白:第一个参数必须是 URL 字符串,第二个参数是可选的 DeferredRequestInit 对象。仓库中的参考实现位于 demo.html:

fetchLater(ANALYTICS_ENDPOINT, {
  method: 'POST',
  headers: {'content-type': 'application/json'},
  body: JSON.stringify(sessionData),
  signal: fetchLaterController.signal,
});

从仓库示例与 polyfill 代码可以归纳出 DeferredRequestInit 在本项目中被使用的字段:

字段 作用 仓库中的使用位置
method 请求方法,分析上报通常为 POST demo.html、guide.md 示例
headers 自定义请求头,例如 content-type: application/json 同上
body 序列化后的负载,通常是 JSON 字符串 同上
signal AbortSignal,用于在数据更新时撤销待发请求 同上,配合 AbortController
activateAfter 毫秒数,到达时间后即发送;不设置则保留到页面离开 polyfill 的定时器分支(demo.html 第 90-92 行)

需要注意 activateAfter 属于“分批发送”变体,同仓库的 batch-analytics-events 指南 专门用它做去抖;而在“全会话分析”这个用例里,故意不传 activateAfter,让浏览器把请求一直挂到会话结束,从而拿到最完整的时长与指标。这正是两个用例的核心差异。

guides/performance/full-session-analytics/guide.md 的 frontmatter 也声明了该指南依赖的 Web 特性:

web-feature-ids:
  - fetchlater
  - aborting

也就是说,AbortController/AbortSignal 的行为同样是本用例的一等公民,而非可选优化。

三、验收点 2:fetchLater() 必须是唯一的 sendBeacon 通道

第二条明确禁止 fetch()、sendBeacon()、XMLHttpRequest 和 new Image()。原因写在 guide.md 里:在 unload 事件里创建 <img> 像素点是“出了名的不可靠”,在移动端尤其如此,而且注册 unload 监听会让页面失去 bfcache 资格,反而拖累性能。

这一条在测试中被具体化为若干字符串与语法检查,见 grader.ts:

const usesXhr = code.includes('XMLHttpRequest');
const usesImage = code.includes('new Image');
const directFetch = code.includes('fetch(ANALYTICS_ENDPOINT');
const directSendBeacon = code.includes('sendBeacon(ANALYTICS_ENDPOINT');
const hasForbiddenUsage = usesXhr || usesImage || directFetch || directSendBeacon;
expect(hasForbiddenUsage).toBeFalsy();

这里有一个容易踩坑的细节:polyfill 内部确实会调用 fetch(url, ...) 和 navigator.sendBeacon(url, init.body),但它检查的是 fetch(ANALYTICS_ENDPOINT 这种“业务代码直接拿端点常量发请求”的写法。所以正确的姿势是:业务侧只出现 fetchLater(...),原始的 fetch/sendBeacon 只能存在于 polyfill 的实现体内。guide.md 也用大写强调:

Your own code MUST call fetchLater() directly — never call fetch(), sendBeacon(), or other beacon APIs yourself.

仓库里还可以找到一个反面样例 negative-demo.html,它同时使用了 fetch(且 body 是 ReadableStream)、XMLHttpRequest、navigator.sendBeacon 以及 unload 中的 new Image(),几乎把四条禁令全部违反,可用于对照理解“为什么这样写是错的”。注意这个反例还叠加了一个隐性错误:fetchLater() 不接受 ReadableStream 作为 body,而 guide.md 的 Best Practices 也明确写了“DO NOT use a ReadableStream object for the request body, as that will error”。

四、验收点 3:只发一次,且发生在用户离开之后

第三条是整个方案的技术核心:全会话只投递一个 beacon,并且投递时机在用户离开页面之后。guide.md 给出的实现范式是“每次数据变化就中止上一次、重新排队一次”:

  1. 排期请求:数据一就绪就调用 fetchLater(),把负载排入队列;
  2. 按需更新负载:用户产生更多数据或状态变化时,abort() 掉上一次排期,用最新的完整快照重新调用;
  3. 交给浏览器:用户离开或关闭标签页时,浏览器可靠地发送“最后一次” fetchLater() 的负载。

参考实现(guide.md):

const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';

const sessionData = {
  duration: 0,
  id: crypto.randomUUID(),
};

let fetchLaterController = null;

function queueBeacon() {
  // Abort any pending beacons before creating a new one.
  if (fetchLaterController) {
    fetchLaterController.abort();
  }
  fetchLaterController = new AbortController();

  // Update session duration to the current page time.
  sessionData.duration = performance.now();

  // Schedule a fetch for the data payload to be sent later.
  // IMPORTANT: wrap the call in a try/catch to handle quota errors.
  try {
    fetchLater(ANALYTICS_ENDPOINT, {
      method: 'POST',
      headers: {'content-type': 'application/json'},
      body: JSON.stringify(sessionData),
      signal: fetchLaterController.signal,
    });
  } catch (error) {
    // Handle errors as needed.
  }
}

// Update the session data and queue a new beacon every 10 seconds.
setInterval(queueBeacon, 10000);

为什么“10 秒重排一次”最终只会有一次网络请求?因为 AbortController.abort() 会把前一次排期的请求撤销,浏览器手中始终只留最新的一份。仓库的端到端测试正是这样断言的(grader.ts):

  • 强制删除原生 fetchLater,让 polyfill 接管,从而“确定性地”测试延迟逻辑;
  • 对 navigator.sendBeacon 与 window.fetch 打补丁,一旦提前发往 /analytics/endpoint 就置 __prematureFlush = true;
  • 页面加载后 300ms 内断言没有任何提前发送,且 analyticsRequests === 0;
  • 然后通过 Object.defineProperty(document, 'visibilityState', ...) 把可见性改为 hidden 并派发 visibilitychange;
  • 最终 expect.poll(() => analyticsRequests).toBe(1)。

这段测试也解释了 polyfill 的一个关键行为差异:原生 API 依靠浏览器的 unload 处理,而 polyfill 用 visibilitychange(页面变为隐藏)作为“用户离开”的近似信号。guide.md 特意说明这是内部实现细节,业务代码不需要监听任何页面生命周期事件。

demo.html 在 guide.md 的基础上做了两点工程化增强,值得直接借鉴:

  • 把 duration 换算成秒(Math.round(performance.now() / 1000)),便于阅读,日志里也按秒展示;
  • 启动时立即调用一次 queueBeacon(),再挂 setInterval(queueBeacon, 10000),避免首屏 10 秒内离开导致零数据。

五、验收点 4:QuotaExceededError、RangeError、TypeError 必须被处理

第四条要求调用方对三类异常做妥善处理。guide.md 的 Best Practices 给出了配额数量级提示:每个 origin 目前大约是 64KB,因此要尽量压缩负载以避免超限。仓库根目录的 README.md 也把这条作为“Gotchas & Quirks”的示例,说明这是被刻意记录的平台限制,而不是实现瑕疵。

对应到代码,正确的结构就是把 fetchLater() 包在 try/catch 中,并对错误做区分或至少做降级处理。grader.ts 会用正则确认存在真正的 try → fetchLater → catch 结构(grader.ts):

const tryCatchRegex = /try\s*\{[\s\S]*?fetchLater\s*\([\s\S]*?\}[\s\S]*?catch\s*(?:\(|\{)/;
expect(tryCatchRegex.test(code)).toBeTruthy();

实践上,三类错误的成因可以这样理解(这是基于 API 语义与仓库示例的归纳):

  • QuotaExceededError:待发请求总字节数超过 origin 配额;
  • RangeError:例如 activateAfter 传入负数或非法数值范围;
  • TypeError:例如 body 类型不被接受(ReadableStream 即属此类)或参数结构非法。

因此建议在 catch 中至少做三件事:把错误上报到本地日志或降级通道、裁剪 payload 后重试、必要时直接放弃本次排期而不是无限重试。demo.html 的做法是把错误写进页面日志,便于在演示与调试时观察:

} catch (error) {
  logMessage(`Quota error or failure queuing beacon: ${error.message}`);
}

六、验收点 5:polyfill 必须进包(除非只支持 Chromium)

第五条是一个交付要求:除非项目明确只支持 Chromium 系浏览器,否则 fetchLater() 的 polyfill 必须被打进 bundle。guide.md 用 {{ BASELINE_STATUS("fetchlater") }} 宏来表述 Baseline 状态,并在其后写明:如果 fetchLater() 达不到你的 Baseline 目标,就必须提供降级策略;但考虑到可靠性与性能收益,只要浏览器支持就应使用原生 API。

这个宏不是装饰。仓库的 src/core/macros.ts 定义了 BASELINE_STATUS 的渲染逻辑:它会调用 getStatusMessage(featureId, bcdKey),找不到状态时直接抛 MacroError;在 DevSite 构建目标下则输出 {{ macros.BaselineStatus('fetchlater') }} 交由上层展开。状态数据来自 src/core/baseline.ts,其中 getFeatureStatus() 会解析 feature id、归一化 baseline: 'low' | 'high' | false,mapBaseline() 再映射为 “Newly available / Widely available / Limited availability”。此外 src/core/guide-validation.ts 会检查文档里是否硬编码了 Baseline 可用性结论,一旦发现就报错并提示改用宏——这保证了所有指南的兼容性声明都能随上游数据自动更新,而不会写死过期信息。

推荐的最小 polyfill(同时出现在 guide.md 与 demo.html 中):

globalThis.fetchLater ??= function fetchLater(url, init = {}) {
  let timeoutHandle;
  let activated = false;

  function sendNow() {
    if (!(init.signal && init.signal.aborted)) {
      // Use fetch keepalive if the browser supports it or if custom fetch
      // parameters are specified (e.g. custom headers or methods).
      // Otherwise fall back to `navigator.sendBeacon()`.
      if (
        'keepalive' in Request.prototype ||
        init.method !== 'POST' ||
        init.headers
      ) {
        fetch(url, Object.assign({}, init, {keepalive: true}));
        activated = true;
      } else {
        activated = navigator.sendBeacon(url, init.body);
      }
    }
    destroy();
  }

  function destroy() {
    document.removeEventListener('visibilitychange', sendNow);
    clearTimeout(timeoutHandle);
  }

  if (document.visibilityState === 'hidden') {
    // If the beacon was created while the page is already hidden, send data
    // ASAP but wait until the next microtask to allow all sync code to run.
    queueMicrotask(sendNow);
  } else {
    document.addEventListener('visibilitychange', sendNow);

    if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
      timeoutHandle = setTimeout(sendNow, init.activateAfter);
    }
  }

  if (init.signal) {
    init.signal.addEventListener('abort', destroy);
  }

  return {
    get activated() {
      return activated;
    },
  };
};

逐层拆解这段代码,可以看清它与原生 API 的对应关系:

  • globalThis.fetchLater ??=:只在不支持时安装,原生实现存在时完全不介入,符合“能在原生就用原生”的原则;
  • init.signal && init.signal.aborted:发送前二次校验,避免“已 abort 但监听器仍在”导致的竞态;
  • 'keepalive' in Request.prototype || init.method !== 'POST' || init.headers:sendBeacon() 只适合简单的 POST 字符串/Blob 且不能自定义请求头;一旦使用了自定义 header、非 POST 方法,或环境支持 keepalive,就改用 fetch(url, {keepalive: true}) 保证离页后仍可完成传输;
  • document.visibilityState === 'hidden' 分支里的 queueMicrotask(sendNow):如果排期发生时页面已经隐藏,就让它在本轮同步代码执行完后立刻发送;
  • activateAfter 分支:仅在显式传入合法非负数时才设置 setTimeout,这解释了为什么“全会话分析”不传该字段就能把请求一直留到离开;
  • 返回 { get activated() {...} }:为分批发送场景提供“是否已真正发出”的可观测信号(本用例不依赖它,但 polyfill 与 batch-analytics-events 指南保持接口一致)。

grader.ts 对该条的检查同时接受“标准 polyfill 赋值”与“等价的自定义兜底赋值”两种写法(grader.ts):

const hasPolyfill =
  code.includes('globalThis.fetchLater ??=') ||
  /(?:globalThis|window)\.fetchLater\s*(?:\?\?=|\|\|=|=)/.test(code);
expect(hasPolyfill).toBeTruthy();

这也意味着:单纯靠特性检测 + 直接调用 fetch() 降级是不被接受的,必须提供一个保持 fetchLater() 调用形态的 shim,才能同时满足“业务代码只调用 fetchLater()”与“不支持时仍能送达”这两个目标。

七、把 Core Web Vitals 接进来

同目录的 tasks/task.md 展示了该模式在真实任务中的典型描述:使用 web-vitals 库采集 Core Web Vitals,把数据发到 /path/to/analytics/endpoint,并等到用户关闭标签页或导航离开时再发送,以确保指标值已经定稿,同时避免使用破坏 bfcache 的 legacy unload 监听。

把 web-vitals 与 fetchLater() 结合时,推荐的组合方式如下(基于 guide.md 的模式与 README.md 中“<50 LOC 的轻量兜底”原则):

  1. 维护一个 sessionData 快照对象,包含 id、duration 以及各指标字段;
  2. 每个 web-vitals 回调(onLCP、onCLS、onINP 等)只做一件事:更新快照字段,然后调用一次 queueBeacon();
  3. queueBeacon() 内部先 abort() 再重建 AbortController,最后用 try/catch 包住 fetchLater();
  4. 不在 unload/beforeunload 里做任何发送动作——这正是本用例要消除的反模式。

八、这份 expectations.md 在仓库流水线中的位置

理解这五条要求的“权威性来源”很重要。按 guides/CONTRIBUTING.md 的定义,每个用例目录必须提供三个核心文件:

文件 职责
guide.md 面向 AI 编码 Agent 的自包含指导(不含外部链接、注释解释“为什么”、Baseline 兜底宏)
demo.html 独立、无控制台警告的参考实现
expectations.md 可观察、可测试的要求清单,下游据此生成自动化 grader

也就是说,expectations.md 是给机器读的合同,guide.md 是给人/Agent 读的方法论,demo.html 是可运行证据。三者必须互相对齐:guide.md 承诺的每个结果,都要在 expectations.md 里有对应条目,并由 demo.html 实际演示。

这个对齐关系在工具层也有实现:src/core/grader-coverage.ts 的 parseVerifiableExpectations() 会按行解析 expectations.md 的顶层项目符号(并把缩进子项合并进父项),extractTestTitles() 则从 grader.ts 中提取 test('...') 标题,两者用于覆盖率比对;src/grading/generate-grader.ts 展示了下游生成流程会先把 guide.md 做宏展开(replaceMacros(..., { target: 'skills-cli' })),再连同 expectations.md、task.md 一起喂给评测生成器。这也解释了为什么 expectations.md 写成“一条一个可验证断言”的扁平列表最有效——解析器只认顶层的 -/*/数字标记。

另外,src/core/grader-lint.ts 定义了 no-vacuous-boolean-expect、no-tautological-expect、no-test-skip 等规则,防止 grader 用 expect(true) 之类空断言“骗过”覆盖率检查。这与 expectations.md 强调“可观察行为”是同一套设计哲学:只接受能真正失败的断言。

九、落地自检清单

把上面的验收点转成可直接对照的清单:

  • 签名:业务代码中每一次发送都是 fetchLater(url, init),url 为字符串,init 为对象或省略;
  • 唯一通道:全仓库搜索 sendBeacon(、XMLHttpRequest、new Image()、fetch(ANALYTICS_ENDPOINT,除 polyfill 内部外应无命中;
  • 单次交付:每次更新数据前先 abort() 上一次排期,页面离开后服务端只收到一条最新负载;
  • 时机:不使用 unload/beforeunload 发送,不注册会破坏 bfcache 的监听;
  • 错误处理:fetchLater() 被 try/catch 包裹,并对 QuotaExceededError、RangeError、TypeError 有明确分支或降级;
  • 体积:payload 保持在 KB 级别,为 64KB/origin 配额留出余量,避免 body 使用 ReadableStream;
  • 兜底:polyfill 已进入 bundle,且业务代码不直接调用 fetch()/sendBeacon();
  • 兼容性声明:用 {{ BASELINE_STATUS("fetchlater") }} 这类宏表达 Baseline 状态,不在文档里硬编码兼容性结论。

完成以上各项,你的实现就同时满足了 guides/performance/full-session-analytics/expectations.md 的五条要求,也具备通过 grader.ts 中静态检查与浏览器行为测试双重的条件:静态部分验证“写法正确”,浏览器部分验证“行为正确”——300ms 内不提前发送,可见性变为 hidden 后恰好一次请求。

登录后查看全文
modern-web-guidance-src