JSONフォーマットのベストプラクティス：読みやすく、妥当で、効率的
簡単な回答
人間が判読できる JSON を実現するには、スペース 2 個のインデントを使用し、末尾のコンマを付けず、二重引用符で囲んだキーを使用し、一貫したキーの順序 (アルファベット順またはドメインの意味を持つ) を使用します。本番環境のトランスポート用に JSON を縮小し、開発用にきれいに印刷します。無料の JSON フォーマッタを使用すると、この 2 つを即座に切り替えることができます。
導入
JSON 形式の選択は、可読性、ファイル サイズ、デバッグ速度に影響します。 JSON 構文は RFC 8259 によって厳密に定義されていますが、インデント、キーの順序付け、および空白の処理方法は慣例の問題です。このガイドでは、JSON がチーム間で一貫し、デバッグが容易で、ネットワーク上で効率的になるように、広く採用されているベスト プラクティスについて説明します。
ステップバイステップ
-
インデントの幅を選択してください
スペース 2 個が最も一般的な規則です (Prettier、ESLint、Google JSON スタイル ガイド)。深くネストされた構成では 4 つのスペースを使用できます。レンダリングはエディターによって異なるため、タブの使用はお勧めできません。 1 つを選択し、プロジェクト全体に適用します。
-
キーを一貫して注文する
確定的な出力のためにキーをアルファベット順に並べ替えるか (キャッシュや差分に便利)、ドメインの意味ごとにグループ化します (最初に ID、次に属性、次に関係)。ランダムなキー順序は避けてください。これにより、diff にノイズが発生し、スナップショット テストが中断されます。
-
本番環境のトランスポート用に縮小する
縮小された JSON は、必須ではない空白をすべて削除し、ペイロード サイズを 10 ～ 0% 削減します。実稼働環境では APIs から縮小された JSON を提供し、ローカル開発とデバッグ専用に整形された JSON を保持します。
-
送信前に検証する
API に送信するか、構成ファイルに書き込む前に、必ずバリデーターを通じて JSON を実行してください。単一の末尾のコンマまたは引用符で囲まれていないキーにより、JSON.parse() がスローされ、コンシューマーが中断されます。
-
フォーマッタを使用してモードを切り替える
JSON を JSON フォーマッタに貼り付けて、読み取り用に美しくしたり、転送用に縮小したりできます。このツールは構文を検証し、エラーの正確な位置を報告するため、デバッグ時間を節約します。
例
きれいに印刷された (スペース 2 個のインデント)
入力: {"id":1,"name":"Alice","active":true}
出力: {
"id": 1,
"name": "Alice",
"active": true
}
実稼働用に縮小
入力: {
"id": 1,
"name": "Alice"
}
出力: {"id":1,"name":"Alice"}
アルファベット順にソートされたキー
入力: {"zebra":1,"apple":2,"mango":3}
出力: {"apple":2,"mango":3,"zebra":1}
よくある問題
- 末尾のカンマ: {"a":1,} は無効です JSON。ほとんどのフォーマッタはそれらを取り除きますが、JSON.parse() のような厳密なパーサーは入力を拒否します。
- 一重引用符と引用符で囲まれていないキー: {'a':1} と {a:1} は有効な JavaScript ですが、JSON は無効です。キーと文字列値には常に二重引用符を使用してください。
- JSON のコメント: 標準の JSON では、// または /* */ コメントは許可されません。インラインドキュメントが必要な場合は、JSONC、JSON5、または別のスキーマファイルを使用してください。
- インデントの混合: タブとスペースを混合すると、diff ツールが壊れ、「インデントの不一致」という lint エラーが発生する可能性があります。コミットする前にフォーマッタを使用して正規化します。
ヒント
- 保存時に JSON を 2 スペースのインデントでフォーマットするようにエディターを構成します。これにより、コード レビューでのスタイルに関する議論が回避されます。
- API 応答の場合、Content-Type: application/json を設定します。 charset=utf-8 を使用し、効率を最大化するために gzip/Brotli 圧縮を使用して縮小された JSON を提供します。
- スナップショット テストで JSON をハッシュまたは比較する場合は、決定論的なキーの順序 (アルファベット順など) を使用します。ランダムな順序は誤検知の原因となります。
- 大きな JSON ペイロードをデバッグする場合は、目でスキャンするのではなく、最初にそれを整形してから、正規表現または jq を使用して関連するサブツリーを抽出します。