透過 ReportingObserver API 瞭解程式碼健康狀態

在正式版應用程式中找出已淘汰的 API。

ReportingObserver會在網站使用已淘汰的 API 或遇到瀏覽器介入時通知您。基本功能最初在 Chrome 69 中推出。自 Chrome 84 起，可在 worker 中使用。

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

observer.observe();

使用回呼將報表傳送至後端或數據分析供應商進行分析。

為什麼這項功能很實用？在這個 API 推出前，淘汰和介入警告只能在開發人員工具中以控制台訊息的形式顯示。尤其是介入措施，只有在裝置和網路狀況等各種實際限制下才會觸發。因此，在本機開發/測試網站時，您可能根本不會看到這些訊息。ReportingObserver 可解決這個問題。當使用者在實際環境中遇到潛在問題時，網頁程式開發人員會收到通知。

背景

不久前，我寫了一篇網誌文章 (觀察網頁應用程式)，因為我發現有許多 API 可用於監控網頁應用程式中發生的「事物」，這點非常有趣。舉例來說，有些 API 可以觀察 DOM 的相關資訊：ResizeObserver、IntersectionObserver、MutationObserver。PerformanceObserver 會擷取成效評估結果。window.onerror 和 window.onunhandledrejection 等方法甚至能讓我們知道發生錯誤。

不過，現有 API 無法擷取其他類型的警告。當網站使用已淘汰的 API 或遇到瀏覽器介入時，開發人員工具會率先通知您：

開發人員工具控制台的淘汰和介入警告。
開發人員工具控制台中由瀏覽器發出的警告。

一般人會認為 window.onerror 會擷取這些警告。不會。 這是因為 window.onerror 不會針對使用者代理程式本身直接產生的警告觸發。當程式碼執行導致執行階段錯誤 (JavaScript 例外狀況和語法錯誤) 時，就會觸發。

ReportingObserver 則會接手處理。這項 API 可讓您透過程式輔助方式，接收瀏覽器發出的警告通知，例如淘汰和介入。您可以將其做為報表工具，不必再擔心使用者在實際網站上遇到非預期的問題。

API

ReportingObserver 與其他 Observer 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();

篩選後的報表

您可以預先篩選報表，只查看特定報表類型。目前有兩種報表類型：'deprecation' 和 'intervention'。

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

緩衝報表

如要查看在建立觀察器執行個體前產生的報表，請使用 buffered: true 選項：

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

這個選項非常適合用於延遲載入使用 ReportingObserver 的程式庫等情況。雖然觀察器較晚加入，但您不會錯過網頁載入初期發生的任何事件。

停止觀察

使用 disconnect() 方法停止觀測：

observer.disconnect();

範例

向數據分析供應商回報瀏覽器介入情形

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 能成為 JavaScript 中捕捉所有類型問題的實際 API。想像一下，只要一個 API 就能捕捉應用程式中發生的所有錯誤：

其他資源：

主頁橫幅由 Sieuwert Otterloo 拍攝，取自 Unsplash。