ReportingObserver：瞭解程式碼健康狀態

Philip Walton

TL;DR

小鎮上有新的觀察員！ReportingObserver 是新的 API，可讓您瞭解網站何時使用已淘汰的 API，或何時會執行瀏覽器介入措施：

const observer = new ReportingObserver(
  (reports, observer) => {
    for (const report of reports) {
      console.log(report.type, report.url, report.body);
    }
  },
  {buffered: true}
);

observer.observe();

您可以使用回呼將報表傳送至後端或數據分析供應商，以便進一步分析。

為什麼這個實用？到目前為止，停用和介入警告僅會以控制台訊息形式顯示在開發人員工具中。尤其是，幹預機制只會由各種實際限制 (例如裝置和網路狀況) 觸發。因此，在本機開發/測試網站時，您甚至可能不會看到這些訊息。ReportingObserver 提供解決這個問題的方法。當使用者在實際環境中遇到潛在問題時，我們可以收到通知。

簡介

不久前，我撰寫了一篇網誌文章 (「觀察您的網路應用程式」)，因為我發現有許多 API 可用於監控網路應用程式中發生的「事件」。舉例來說，有幾個 API 可以觀察 DOM 相關資訊：ResizeObserver、IntersectionObserver、MutationObserver。以下是用於擷取效能評估資料的 API：PerformanceObserver。其他 API (例如 window.onerror 和 window.onunhandledrejection) 甚至會在發生問題時通知我們。

不過，這些現有 API 無法擷取其他類型的警告。當您的網站使用已淘汰的 API，或因瀏覽器介入措施而執行時，開發人員工具會先告知您相關資訊：

開發人員工具控制台警告，說明淘汰和介入措施。
開發人員工具主控台中的瀏覽器啟動警告。

您可能會自然而然地認為 window.onerror 會擷取這些警告。並沒有！這是因為 window.onerror 不會針對使用者代理程式本身直接產生的警告觸發。當執行程式碼時發生的執行階段錯誤 (JS 例外狀況和語法錯誤) 時，就會觸發此事件。

ReportingObserver 會接手處理。還能透過程式輔助方式，接收瀏覽器發出的警告 (例如淘汰和幹預通知)。您可以將這項工具做為報表工具，不用再擔心使用者在您的實際網站上遇到意外問題。

API

這個 API 與其他「觀察器」API (例如 IntersectionObserver 和 ResizeObserver) 相似。您只需給應用程式回呼 就能提供資訊回呼接收的資訊是網頁造成的問題清單：

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // → report.type === 'deprecation'
    // → report.url === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.id === 'XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload'
    // → report.body.message === 'Synchronous XMLHttpRequest is deprecated...'
    // → report.body.lineNumber === 11
    // → report.body.columnNumber === 22
    // → report.body.sourceFile === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.anticipatedRemoval === <JS_DATE_STR> or null
  }
});

observer.observe();

篩選報表

您可以預先篩選報表，只觀察特定報表類型：

const observer = new ReportingObserver((reports, observer) => {
  ...
}, {types: ['deprecation']});

緩衝報表

如要查看在建立觀測器建立前產生的報表，buffered: true 選項非常實用：

const observer = new ReportingObserver((reports, observer) => {
  ...
}, {types: ['intervention'], buffered: true});

這類情況包括使用 ReportingObserver 的程式庫延遲載入。觀察器會在較晚時間加入，但不會錯過任何在頁面載入期間發生的事件。

停止觀察

有！以下是 disconnect 方法：

observer.disconnect(); // Stop the observer from collecting reports.

範例

範例：向數據分析供應商回報瀏覽器介入措施：

const observer = new ReportingObserver(
  (reports, observer) => {
    for (const report of reports) {
      sendReportToAnalytics(JSON.stringify(report.body));
    }
  },
  {types: ['intervention'], buffered: true}
);

observer.observe();

示例：在 API 即將移除時收到通知：

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    if (report.type === 'deprecation') {
      sendToBackend(`Using a deprecated API in ${report.body.sourceFile} which will be
                     removed on ${report.body.anticipatedRemoval}. Info: ${report.body.message}`);
    }
  }
});

observer.observe();

結論

ReportingObserver 提供另一種方法，讓您探索及監控網路應用程式中的潛在問題。這甚至是瞭解程式碼集健康狀況 (或缺少健康狀況) 的實用工具。您可以將報表傳送至後端，瞭解使用者在網站上遇到的問題、更新程式碼、增加獲利！

日後作業

我希望未來 ReportingObserver 能成為實際的 API，用於擷取 JS 中的所有類型問題。想像一下，如果有一個 API 可以擷取應用程式中所有發生錯誤的情況：

我也很高興看到有工具將 ReportingObserver 整合到工作流程中。Lighthouse 就是這類工具的範例，當您執行「避免已淘汰的 API」稽核時，它會標示瀏覽器淘汰情形：

Lighthouse 稽核工具可使用 ReportingObserver，稽核使用已淘汰的 API。
針對使用已淘汰 API 的 Lighthouse 稽核結果，可以使用 ReportingObserver。

Lighthouse 目前使用開發人員工具通訊協定來擷取主控台訊息，並將這些問題回報給開發人員。建議您改用 ReportingObserver，以便取得結構完善的淘汰報表和其他中繼資料 (例如 anticipatedRemoval 日期)。

其他資源：