JavaScript Tips | ログ・デバッグ・エラー処理：エラーオブジェクトを整形する

JavaScript JavaScript
スポンサーリンク
スポンサーリンク

エラーオブジェクト整形は「原因を最速で特定するための“読みやすい形”に変換する技術」

エラーは業務システムの中で必ず発生します。 しかし、そのエラーをどうログに残すかで、障害調査のスピードが劇的に変わります。

初心者がやりがちなミスは次の2つです。

  • console.error(e) をそのまま出す
  • エラーオブジェクトを JSON に変換しようとして失敗する

業務では、 「エラーオブジェクトを整形して読みやすくする」 というユーティリティが必須です。

ここでは、ステップバイステップで エラーオブジェクト整形の考え方 → 実装 → 強化 → 業務テンプレート までを丁寧に解説します。

エラーオブジェクト整形の目的は「原因を最速で特定すること」

エラーオブジェクトには次の情報が含まれます。

  • message：エラーの概要
  • name：エラーの種類
  • stack：どこで発生したか（最重要）
  • custom fields：APIエラーなどで追加される情報

しかし、これらをそのままログに出すと読みづらく、 障害調査が遅くなります。

そのため、 必要な情報を抽出し、読みやすい形に整形する というユーティリティが必要になります。

ステップ1：エラーオブジェクトを安全に扱うための基礎を作る

まずは「エラーかどうか」を判定する関数を作ります。

function isError(value) {
  return value instanceof Error;
}
JavaScript

これにより、 「普通のオブジェクト」と「Errorオブジェクト」を区別できます。

ステップ2：エラーオブジェクトを整形する関数を作る（最小構成）

function formatError(error) {
  if (!isError(error)) {
    return { message: String(error) };
  }

  return {
    name: error.name,
    message: error.message,
    stack: error.stack,
  };
}
JavaScript

使用例

try {
  throw new Error("DB接続に失敗しました");
} catch (e) {
  console.log(formatError(e));
}
JavaScript

出力例：

{
  "name": "Error",
  "message": "DB接続に失敗しました",
  "stack": "Error: DB接続に失敗しました\n    at ..."
}

ステップ3：APIエラーなどの「追加情報」を取り込めるようにする

業務では、APIエラーが次のような形で返ってくることがあります。

{
  "error": {
    "code": "API001",
    "detail": "Token expired"
  }
}

そのため、追加情報を取り込む処理を追加します。

function formatError(error) {
  if (!isError(error)) {
    return { message: String(error) };
  }

  const formatted = {
    name: error.name,
    message: error.message,
    stack: error.stack,
  };

  // 追加情報がある場合は取り込む
  for (const key of Object.keys(error)) {
    formatted[key] = error[key];
  }

  return formatted;
}
JavaScript

ステップ4：循環参照を安全に処理する（重要）

エラーオブジェクトを JSON に変換するとき、 循環参照があると JSON.stringify が失敗します。

そのため、安全な stringify を用意します。

function safeStringify(value) {
  try {
    return JSON.stringify(value);
  } catch {
    return "[Unserializable Object]";
  }
}
JavaScript

ステップ5：整形したエラーをログに出すユーティリティを作る

function logFormattedError(error, context = "") {
  const formatted = formatError(error);
  const ctx = context ? `[${context}] ` : "";
  console.error(`[ERROR] ${ctx}${safeStringify(formatted)}`);
}
JavaScript

使用例

try {
  JSON.parse("invalid json");
} catch (e) {
  logFormattedError(e, "JsonParser");
}
JavaScript

ステップ6：読みやすい「整形済みエラーレポート」を作る（業務で最も使われる形）

業務では、次のような「整形済みエラーレポート」が最も読みやすいです。

function buildErrorReport(error) {
  const f = formatError(error);

  return `
=== ERROR REPORT ===
Name: ${f.name}
Message: ${f.message}
Stack:
${f.stack}
====================
  `.trim();
}
JavaScript

使用例

try {
  throw new Error("ファイル読み込みに失敗しました");
} catch (e) {
  console.error(buildErrorReport(e));
}
JavaScript

ステップ7：業務で使えるエラー整形ユーティリティ（完成版）

export const ErrorFormatter = {
  isError(value) {
    return value instanceof Error;
  },

  format(error) {
    if (!this.isError(error)) {
      return { message: String(error) };
    }

    const formatted = {
      name: error.name,
      message: error.message,
      stack: error.stack,
    };

    for (const key of Object.keys(error)) {
      formatted[key] = error[key];
    }

    return formatted;
  },

  stringify(error) {
    try {
      return JSON.stringify(this.format(error));
    } catch {
      return "[Unserializable Error]";
    }
  },

  report(error) {
    const f = this.format(error);
    return `
=== ERROR REPORT ===
Name: ${f.name}
Message: ${f.message}
Stack:
${f.stack}
====================
    `.trim();
  },
};
JavaScript

ステップ8：業務での活用例

APIエラーの整形

try {
  await fetch("/api/user");
} catch (e) {
  Logger.error(ErrorFormatter.stringify(e), "UserAPI");
}
JavaScript

バッチ処理の異常終了

try {
  runBatch();
} catch (e) {
  console.error(ErrorFormatter.report(e));
}
JavaScript

外部サービスの障害

Logger.error(ErrorFormatter.stringify(e), "ExternalService");
JavaScript

深掘り：なぜ「整形」が重要なのか

1. 原因特定が圧倒的に早くなる

整形されたエラーは読みやすく、 どこで何が起きたかが一目で分かります。

2. 再現が難しい障害でもログが証拠になる

本番環境では再現できない障害が多いため、 整形されたエラーが唯一の手がかりになります。

3. チーム全体で統一されたログ形式になる

誰が見ても理解できるログは、 調査の属人化を防ぎます。

4. 監視ツールとの連携がしやすくなる

整形された JSON は外部サービスに送信しやすいです。

まとめ：エラーオブジェクト整形は「障害調査のスピードを最大化する技術」

エラーオブジェクト整形を正しく扱うことで、次のメリットが得られます。

  • 原因特定が高速化する
  • 読みやすいログが残る
  • 追加情報も取り込める
  • JSON化して外部サービスに送れる
  • チーム全体で統一されたログ形式になる

エラーは避けられません。 しかし、整形して読みやすくすることは必ずできます。

業務システムの品質を支える重要な基盤として、 ぜひエラー整形ユーティリティを活用してください。

スポンサーリンク
タイトルとURLをコピーしました