プルリクエストには240 行の変更があり、私はちょうど2 つの値に触れていました それは私がJSONキーの並べ替えに真剣に取り組んだ瞬間でした チームメイトがキーの並べ替えを行うフォーマッターを通してコンフィグファイルを実行し、私はそれらの値のうち2 つを手で編集し、その結果得られた差分は赤と緑の読めない壁で、238 行が単に動いたキーでした 私のレビュアーは、当然のことながら、それをやり直すように私に頼みました 本当の変化はノイズの内部では見えませんでした。
私は [Toolz.dev] を実行します (/ そしてまた、LaravelとWordPressのプロジェクトを構築します, これは私が中に住んでいることを意味します package.json、 composer.json、 tsconfig.json、翻訳カタログ、およびバージョン管理にコミットされる百他のJSONファイル。 予測不可能なキー順序を持つJSONファイルは、それらのすべての1 に小さな、定期的な税金です。 安定したアルファベット順へのキーの並べ替えは修正であり、それはあなたが無駄なコードレビューを保存する最初の時間まで、見た目に見えるそれらの変更の1 つです。 このガイドでは、JSONキーを並べ替えるとき、そうでないとき、そして何も壊さずにそれを行う方法について説明します。
tl;dr: JSONソーターはオブジェクト' sキーをアルファベット順に並べ替え、結果を再シリアル化する。 key order does not change what JSON, because objects are unordered by the JSON standard, but a consistent order makes files readable and produces clean version-control diffs that show only changed values.キー順はJSONの意味を変更しない、なぜならオブジェクトはJSON規格によって順序付けされていないが、一貫した順序はファイルを読みやすくし、変更された値のみを示すクリーンなバージョン管理差分を再帰的に並べ替えてネストされたオブジェクトに到達し、配列は順序付けされているためデフォルトで配列順序を維持し、昇順または降順、pretty or JSON ソーター ブラウザで完全に実行されます.
JSONソーターとは何ですか?
JSONソータはJSONオブジェクトを取り出し そのキーをアルファベット順に並べ替えてから オブジェクトを書き戻します 値は手付かずです キーが表示されるシーケンスのみが変わり それは安全だからです RFC 8259 オブジェクトを順序付けされていないコレクションとして定義します: キーの順序を変更しても、ドキュメントの意味を変更することはできません {"name":"toolz","author":"Liton"} なる {"author":"Liton","name":"toolz"}。デフォルトでは、ソートは再帰的です。つまり、ネストされたすべてのオブジェクト内のキーも、最も深いレベルまでソートされます。
それが全体の操作であり その単純さがポイントです データを変換したり スキーマを検証したり 形式を変換したりしていません 任意の順序を持っていたものに 予測可能な順序を課しています 他のすべての利点 可読性 比較可能性 クリーンな差分は その単一の予測可能な順序から流れます。
キーを並べ替えると、私の JSON の意味が変わりますか?
いいえ、これがソートを安全にするという事実です。 JSON 標準の ECMA-404 では、オブジェクトは名前と値のペアの順序のないコレクションとして定義されています。仕様は、それらのペアの順序が重要ではないことを明示しています。準拠するパーサーは読み取ります {"a":1,"b":2} あんど {"b":2,"a":1} まったく同じデータとしてです プログラムがそうするとき config.timeout や data["name"]、それは名前によってキーを上に見ます; それは決してキーが書かれたオブジェクトのどこを気にしません。
はっきりと述べる価値のある注意点が1 つあります なぜなら 誰かがいつも尋ねるからです 極少数のシステムが JSONオブジェクトを まるで順序付けされたかのように悪用します 表示や処理のために 挿入順序に頼るのです それはフォーマットのプロパティではなく 誤用です しかし 制御していないシステムに供給しているなら 並べ替えられたファイルを 検査できないパイプラインにコミットする前に テストしてください 現実世界のJSONの圧倒的多数にとって 構成ファイル APIペイロード ロックファイル 翻訳カタログ 並べ替えキーは 意味に全く影響しない 純粋に表現上の変化です。
配列はその逆で 区別が重要です JSON配列は定義によって順序付けされ その順序には頻繁に意味が込められます ステップのシーケンス ランク付きリスト 位置1 が経度 位置2 が緯度の座標のセット 配列の順序を変えると データの言うことを静かに変えることができます そのためこのツールはデフォルトで配列の順序を保持し 明示的に要求したときにのみ配列を並べ替えます その場合でも要素が全て文字列または全ての数字である配列に対してのみです。
なぜ JSON キーを並べ替えるのですか?
見出しの理由はクリーンな差分で、私の働き方を変えたのはバージョン管理ツールですファイルを一行ずつ比較します同じデータを表す2 つのファイルがキーを異なる順序で書くとき差分は変更された値ではなく動いたキーでいっぱいになりますすべてのJSONファイルがソートされたキーで書き込まれて問題が消えるというルールを採用します: ファイルの2 つのバージョンは実際に値が違う場所でのみ異なるため、レビュー担当者は実際の変更をすぐに確認できますまさにこれが、多くのリンターやフォーマッターがソートキーオプションを提供する理由であり、ツールが好む理由です jq ソートキーフラグを出荷します.
2 つ目の理由は人間の可読性です特定の設定を探して大きな設定ファイルをスキャンしている時アルファベット順でどこを見るべきか教えてくれますファイル全体を読んでいない; キーがあるべき場所に大まかにジャンプします辞書で言うような80 キーのファイルではそれが2 秒間のルックアップとフルスキャンの違いです。
3 つ目の理由はファイル間の比較可能性です プロジェクトに10 個のJSONファイルがあり、すべて共通の構造を共有する必要がある場合、それらをすべて同じように並べ替えると、キーが欠けているか余分な位置に隠れているかではなく、分岐が隣り合って並びます。
4 つ目の理由は正規化です 一部のワークフローでは、JSON 値の安定した決定論的な表現が必要です。たとえば、JSON 値をハッシュしたり、キャッシュしたり、シリアライズされた方法に関係なく 2 つのペイロードを比較して等価性を実現したりするためです。キーの並べ替えは正規形式への 1 つのステップですが、完全な正規 JSON では空白と番号の書式も正規化されます。
JSON Sorter を使うには?
JSON を の入力ボックスに貼り付けます JSON ソーター、またはサンプルをロードして出力の形状を確認します。入力は有効な JSON でなければなりません。そうでない場合、ツールは位置とともに解析エラーを報告するため、並べ替え前に迷走カンマや閉じられていないブラケットを修正できます。
次にソートの実行方法を選択します。 a から Z までの昇順、または Z から A までの降順を選択します。デフォルトでオンになっている case を折りたたむかどうかを決定します Name、 name、そして NAME 大文字は小文字の前に生の文字順に並べ替えるので、分離されるのではなく一緒に座る ほとんど常に必要なネストされたオブジェクトに降りるか、トップレベルのみを並べ替えるかを選択する 文字列や数字の配列も並べ替えたい場合は、配列の並べ替えをオンにする; 混合配列とオブジェクトの配列は常にそのまま残されます。
最後に出力スタイルを選択します。コミットする読み取り可能なファイルについては 2 つのスペース、4 つのスペース、またはタブのインデントを使用してかなり印刷します。または、ストレージまたはトランスポート用の最小ペイロードについては 1 行に縮小します。並べ替えを実行し、結果をコピーするかダウンロードします。キー数によってキーの順序が変更された数がわかります。これは、ツールが期待した構造を確認したことを簡単に確認できます。
上昇、下降、再帰: どの設定が必要ですか?
ほとんどの場合デフォルトはあなたが望むものです昇順、再帰、大文字と小文字を区別せず、2 つのスペースでかなり印刷されていますそれはそもそもソートを動機付ける読み取り可能で差分フレンドリーなファイルを生成しますその他の設定は特定の状況に対して存在し、以下の表はそのようにして決定します。
| 設定 | デフォルト | 変更するタイミング |
|---|---|---|
| 注文 | 上昇 (A から Z) | 降順はまれです;最後に並べ替えられるように名前が付けられた最新のキーまたは最優先キーを最上部に表示したい場合に便利です |
| 再帰 | オン | トップレベルのセクションの順序を変更したい場合にのみオフになりますが、それぞれのセクション内で手動で調整された順序は保持されます |
| 大文字と小文字を無視 | オン | たとえば、大文字と小文字を区別して並べ替える別のツールに一致させるなど、厳密なコードポイント順序が必要な場合はオフにします |
| 配列を並べ替えます | オフ | タグや許可された値のリストなど、真に順序付けされていないセットである配列の場合はオンにします |
| プリティプリント | オン | 輸送または保管のためにminifyをオフにします |
人々が誤用する設定の 1 つは配列の並べ替えです。配列が順序付けされていないセットを表していると確信できる場合にのみオンにします。タグのリスト、許可されたファイル拡張子のセット、または機能フラグの袋は並べ替えが安全です。パイプライン ステップのリスト、ルート テーブル、または位置がシーケンスを意味しないもの。疑問がある場合は、配列を放置してください。順序を保持する tool' のデフォルトではデータが破損することはなく、間違った配列をサイレントに並べ替えることができるためです。
これは他のJSONツールとどのように適合しますか?
通常、並べ替えは小さなチェーンの 1 ステップです。JSON が API から縮小されて読み取り不能になって到着したら、それを実行します JSON フォーマッタ 最初にインデントして検証し、次にキーをソートしてスキャン可能にします。ソート後にトランスポート用のペイロードを準備しているときは、 JSON ミニファイア 単一行に戻し、キーがすでに並べ替えられているため、同じデータを表す 2 つの縮小ペイロードがバイトごとに同一になり、キャッシュと比較に便利です。
プレゼンテーションではなく構造作業の場合は、 JSON フラットナー ネストされたオブジェクトを点線のキーに変換し、環境変数にコンフィグを並べ替えているときにソートと自然にペアリングします。そして、完全に別の形式のデータが必要な場合は、 JSON から YAML へのコンバータ は次の停止です; 変換する前にキーを並べ替えると、予測可能で読み取り可能なフィールド順序を持つ YAML ファイルが得られます。これらがどのように組み合わされるかをより詳細に把握したい場合は、フルセットアップを でレイアウトしました Web 開発者ツールキット ガイド、そしてフォーマットのより深い仕組みは に住んでいます JSON フォーマッタ ガイド。
実際の例: package.json diff をテーミングする
この記事を始めた正確な状況を説明しましょう。なぜなら、設定の選択がなぜ重要なのかを示しているからです。私は持っていました package.json どこで dependencies ブロックはインストール順序で書かれていました。これは、パッケージが 2 年間で追加された順序とほぼ同じです。新しいチーム メンバーが editor's format-on-save を実行し、依存関係キーを並べ替え、バージョン 4 からバージョン 5 に 1 つのパッケージをバンピングするという真の変更と並行してコミットしました。
差分は災難でした。 bumped one の下のすべての依存関係は移動したように見えました。ソートによって位置がずれたため、レビュー担当者は 1 行のアップグレードであるものに対して 30 行の変更された行を確認しました。修正は、誰が正しいエディターであるかについて議論することではありませんでした。修正は、ファイルを 1 回ソートし、そのソートを "sort package.json keys," などのメッセージを含む独自の個別の変更としてコミットし、バージョンを現在安定している順序の上にバンプさせることでした。その後、将来の依存関係の変更はすべて、きれいな 1 行または 2 行の差分を生成しました。なぜなら、ファイルはすでに everyone's ツールが入れたい順序になっていたからです。
それが今私がバージョン管理に住んでいるJSONに対して従うパターンです 専用コミットで一度並べ替えてから並べ替えたままにします The JSON ソーター デフォルトでは昇順と再帰式があり、prettier' の順序が正確に生成されます。 sort オプションと jq --sort-keys produce を使うので、チームメイトがどのツールを実行してもファイルは安定しています。 最初にチェックするのは配列です: package.json 心配すべき意味のある配列はありませんが、ビルド ステップのリストのような順序付けられた配列を持つファイルには、デフォルトである配列の並べ替えが省略されているため、シーケンスは存続します。
どのツールとフォーマットがJSONキーをソートしますか?
JSONキーの並べ替えは、それがエコシステム全体に現れる十分な一般的なニーズであり、これは練習が個人的な癖ではなく音である良い兆候です。 コマンドラインプロセッサ jq 持つ a --sort-keys 旗、しばしば書かれる -S、その出力内のすべてのオブジェクトのキーをソートする。 prettierコードフォーマッタは、その設定を通じてjsonのキーをソートすることができる。 linterの多くは、ソースコード内のソートされていないオブジェクトにフラグを立てるsort-keysルールを提供する。 language standard libraries expose the same capability, for example Python' s json.dumps aを受け入れます sort_keys=True 正規のソートされた出力を生成する引数。
ブラウザベースのソーターが追加するのは、セットアップ不要のクイックケースです。 API レスポンス、ログ行、または Slack メッセージから JSON の塊があり、それをただ正しい順序で読みたい場合、ページを開いて貼り付ける方が、フォーマッターを配線したりシェルにドロップしたりするよりも高速です。ペーストアンドゴーフォーマッターがエディタープラグインと並んで存在するのと同じ理由です。ツールは、設定されたパイプラインではカバーできないアドホックニーズを満たします。
私のJSONはプライベートですか?
はい。 JSON は、JavaScript を使用して完全にブラウザーで解析、並べ替え、再シリアル化されます。サーバーにアップロードされたり、ログに記録されたり、どこにでも保存されたりすることはありません。これは、JSON にとって特に細かいことではありません。なぜなら、JSON は秘密が存在する場所だからです。トークンを運ぶ API レスポンス、接続文字列を含む構成ファイル、顧客レコードを含むペイロードなど、サーバーに配送するツールにそれらのいずれかを貼り付けることは実際のリスクであり、まさにこのツールが回避するために構築されているリスクです。
私がそうするであろうのと同じ方法で主張を検証することができます。 browser& #39; s 開発者ツールでネットワークタブを開き、ソートしながらそれを見てください; リクエストがページを離れることはありません。 or disconnect from the internet and keep sorting, because once the page has loaded, the tool works with no connection at all.クライアント側の処理は、私が構築するすべてのデフォルトであり、それに対するより広い議論を気にかけている場合は、 データ プライバシー ガイド 主張を全面的にする.
よくある質問
JSON キーを並べ替えるというのはどういう意味ですか?
JSONキーを並べ替えると、オブジェクトの名前と値のペアをアルファベット順に並べ替えるため、値を変更することはありません。 {"name":"toolz", "author":"Liton"} は {"author":"Liton", "name":"toolz"} になります。キーの順序のみが変更されるため、ドキュメントが表すデータはまったく同じままです。
キーを並べ替えると、私の JSON の意味が変わりますか?
いやー 。 JSON 規格 ECMA-404 では、オブジェクトは名前と値のペアの順序付けられていないセットであるため、キーを並べ替えても意味が変わりません。 適合するパーサーは、ソート済みバージョンとソートされていないバージョンを同じデータとして読み取ります。 この順序は、人間の可読性と、安定した差分の生成にのみ重要です。
ネストされたオブジェクトも並べ替えられていますか?
はい、デフォルトで。 再帰ソートがオンになっているため、ドキュメント内のすべてのオブジェクトのキーは、ネストのあらゆるレベルでソートされます。 再帰をオフにして、最上位キーのみをソートし、ネストされたオブジェクトを元の順序で残すことができます。
ソーターは配列を並べ替えますか?
デフォルトではありません。 配列は定義順に並べられています。配列の並べ替えは意味を変えることができるので、ツールは配列の順序を保持します。 要素がすべて文字列またはすべての数字である配列を並べ替えるオプションがあります。型を組み合わせる配列またはオブジェクトを含む配列は、常にそのままのままです。
なぜ JSON キーを並べ替えるのですか?
最も一般的な理由は、安定した差分です。すべてのファイルが同じアルファベット順でキーを書き込む場合、バージョン管理の差分は、移動したキーではなく、変更された値のみを強調表示します。 また、ソートすると、大きな構成ファイルと API 応答が、目をスキャンして比較するのがはるかに簡単になります。
大文字と小文字を区別しない並べ替えはどのように機能しますか?
大文字と小文字を区別しないソートでは、キーは小文字のように比較されるため、大文字の順に小文字の順に並べ替えるため、名前、名前、名前が区切られているのではなく、互いにグループ化されます。 オフにして、文字コード ポイントで厳密に並べ替えます。
ソートされた JSON を縮小できますか?
はい。 ミニファイド出力を選択して、ストレージまたはトランスポート用の最小のフォームである余分な空白を持たずに、並べ替えられた JSON を 1 行で取得します。 読み取り可能なファイルの場合は、代わりに 2 スペース、4 スペース、またはタブのインデントを含む Pretty Output を選択します。
私の JSON はどこかにアップロードされていますか?
いやー 。 JSON は、ブラウザーで JavaScript によって解析およびソートされ、送信、ログ、または保存されることはありません。 これは、ソート中にネットワーク タブを確認するか、オフラインにすることで確認できます。このツールは、接続なしで動作し続けます。
[Toolz.dev] のビルダーである Liton によって書かれました (/. 私はブラウザベースの開発者ツールを構築し、JSON、Laravel、および Web との連携について書いています。
