デバッグを高速化するために JSON をフォーマットする方法

API が縮小された JSON の壁を返すと、実際のバグを見つける前にデバッグが遅くなります。キーがぼやけ、欠落したカンマが長い文字列に隠れ、入れ子になった配列をスキャンできなくなります。きれいに印刷することは表面的なものではなく、不透明なトランスポート形式を目で数秒で解析できるものに変える方法です。

ブラウザのネットワーク タブ、ターミナル、またはログ ファイルから生の応答をコピーします。これを Power Tools の JSON Formatter に貼り付けます。インデント レベルを選択します。コンパクトなログの場合は 2 つのスペース、コード レビューでスニペットを共有する場合は 4 つのスペースです。フォーマッタはレンダリング時に構文を検証します。末尾のカンマまたは引用符で囲まれていないキーによって文書が壊れた場合、どの行が失敗したかを推測する代わりに、エラーの場所がすぐに表示されます。

検証エラーは、いくつかの予測可能なカテゴリに分類されます。単一の引用符が欠けていると、多くの場合、誤解を招くメッセージが数十に連鎖します。最初に報告された問題を修正し、再フォーマットします。文字列として保存された数値 (200 ではなく「200」) は有効な JSON ですが、アプリケーションでの厳密な比較が崩れる可能性があります。インデントされた出力を読むときにそれらを強調表示します。 PATCH エンドポイントでは、キーが Null であるか欠落しているかが重要です。フォーマットされた JSON により、フィールドが欠落しているのではなく、明示的に Null であることが明確になります。

ペイロードが読み取り可能になったら、上から下に読み取るのではなく、戦略的にデバッグします。エンベロープを識別する: HTTP ラッパーは、多くの場合、データ、結果、項目の下にデータを配置します。期待する形状 (配列とオブジェクト) を、到着した形状と比較します。ページネーションが関係する場合は、個々のレコードに入る前に、ページ、合計、およびカーソル フィールドを確認してください。

認証のバグには、JWT アクセス トークンが関係することがよくあります。 API が 401 または 403 を返した場合は、ベアラー トークンを (デコーダーが生の JWT を期待する場合は「Bearer」プレフィックスを付けずに) JWT Decoder ツールに貼り付けます。最初に exp クレームを検査します。期限切れのトークンは、クロックが境界を越えたために「ランダム」に見える突然の障害を説明します。サービスが発行者または対象者を検証しているかどうかは、iss と aud を確認してください。ペイロード セクションでは、サービス間でタイプが異なる場合にバックエンドが誤って読み取る可能性があるロール、テナント ID、およびカスタム クレームが明らかになります。

本番トークンを公開ペーストビンに貼り付けたり、クレームが表示された状態でチャットのスクリーンショットを作成したりしないでください。自分のマシンでブラウザベースのデコードを行うと、サードパーティのサーバーから秘密が漏洩されなくなりますが、画面とクリップボードは依然として重要です。共有ハードウェアでデバッグした後は、フィールドをクリアします。

文字列フィールドには、エスケープされた JSON または Base64 BLOB が含まれることがよくあります。外側のオブジェクトをフォーマットした後、内側の文字列をコピーして再度フォーマットします。一部の API はエラーを二重エンコードします。メッセージ フィールドにはオブジェクトの代わりに JSON 文字列が保持されます。各レイヤーをきれいに印刷すると、UI がユーザーに表示すべき実際の検証メッセージが公開されます。

ログにテキストと JSON が混在している場合 (Webhook 配信で一般的)、書式設定する前に Regex Tester を使用して JSON ブロックを分離します。 \{[\s\S]*\} などのパターンを慎重にアンカーリングすると、周囲のヘッダーからオブジェクトを抽出できます。保存されたサンプル ログに対して正規表現をテストし、同様のエントリ全体に一貫して適用します。正規表現抽出とフォーマッタを組み合わせると、タイムスタンプ プレフィックスを 1 行ずつ手動で削除する必要がなくなります。

回帰作業では、curl または Postman で正確なバイト シーケンスを再現する必要がある場合、フォーマットされた JSON を単一行に縮小します。 JSON Formatter は、その往復の縮小モードをサポートします。両方の表現をチケットに保存します。人間の読者のためにインデントされ、コピー＆ペーストの再現手順のために縮小されます。

API インシデントの個人用チェックリストを作成します。ステップ 1: 構文をフォーマットして修正します。ステップ 2: OpenAPI または TypeScript タイプに対してフィールドをマップします。ステップ 3: 認証が関係する場合は JWT をデコードします。ステップ 4: 必要に応じて、ログから埋め込みペイロードを正規表現で抽出します。ステップ 5: 失敗した最小のサブセットを文書化します。問題のあるキーのみが残るまで、無関係なブランチを削除します。

JSON オブジェクトは技術的には順序付けされていませんが、チームはインデントとキーの順序付け規則について合意することで恩恵を受けます。プル リクエストの一貫したフォーマットにより、差分ノイズが軽減されます。他の人のペイロードをレビューするときは、スクリーンショットではなく、フォーマットされた JSON を貼り付けるように依頼してください。テキストは検索できますが、画像は検索できません。

大規模な配列には特別な注意が必要です。インデックス 0 で精神的に崩壊するのは簡単です。インデックス 400 のバグはそうではありません。フォーマット後、バグレポートから特定の ID または電子メールを検索します。フォーマッタが貼り付けられた非常に大きな入力に苦労する場合は、エディターで配列を分割するか、API 所有者にページ分割されたエンドポイントをリクエストしてください。

セキュリティが重要なフィールド - パスワード、リフレッシュ トークン、 秘密キー - 偶発的なデバッグ ダンプに表示されることがあります。内部であっても、フォーマットされた出力をチケットで共有する前に編集します。フォーマッタはシークレットを削除しません。

構造には JSON Formatter、トークン クレームには JWT Decoder、乱雑なログから JSON を抽出するには Regex Tester を使用すると、慌ただしいコピー＆ペースト セッションを短い反復可能なパイプラインに変えることができます。次回、実稼働環境が不透明なボディで 500 を返すときは、空白と戦うのに何時間も費やすのではなく、問題のあるフィールドを特定するのに数分を費やすことになります。