クエリ文字列の配列パラメータが言語ごとに変わる理由

公開ツールURLパーサー・クエリ文字列変換

目次
  1. 問題
  2. 解決
  3. よくつまずくポイント
  4. まとめ
  5. よくある質問

URLに ?tag=a&tag=b のように同じキーが複数回現れるとき、これを配列としてまとめて読むのか、最後の値だけを残すのかは、言語やフレームワークごとに決まっています。そのため、フロントエンドが送ったクエリ文字列をバックエンドが違う形で解釈してしまい、値が1つしか届かないという問題がよく起きます。この記事では、そのルールがなぜ分かれるのか、そして実際にどう解釈されているかを自分の目で確かめる方法を整理します。

まとめ ① URLのクエリ文字列そのものに「配列」というデータ型はなく、配列とみなすかどうかは各言語・フレームワークが定めた慣例にすぎません。 ② 大きく分けると、同じキーを繰り返す方式(tag=a&tag=b)と、角括弧を付けないと配列として認識しない方式(tag[]=a&tag[]=b)の2つに分かれます。 ③ どちらのルールなのかは、コードを見なくても、クエリ文字列を実際にJSONへ変換してみればすぐに確認できます。

問題

チェックボックスでタグを複数選ぶフィルタ画面を考えてみると、ブラウザはたいてい、同じ名前の値たちを tag=a&tag=b のように繰り返して送信します。

このリクエストを受け取るサーバーが、角括弧の記法だけを配列として認識する言語だった場合は話が変わってきます。角括弧なしで繰り返されたキーは配列にまとめられず、最後の値1つだけが残ります。

逆に、APIドキュメントを見て tag[]=a&tag[]=b の形で自分で組み立てて送ったのに、受け取る側が繰り返しキーだけを配列として扱う仕様だった場合は、今度は「tag[]」という名前のキー1つとして誤って読まれてしまいます。

こうした問題は、値が1つのときのテストでは見えず、複数選択や複数タグのように同じキーが何度も現れる状況でだけ表面化するので、原因の特定がとりわけ厄介です。

解決

まず押さえておきたいのは、URLのクエリ文字列そのものには「配列」というデータ型が存在しないという点です。クエスチョンマークより後ろは、ただ key=value の組が & で並んだ文字列にすぎず、これを配列としてまとめるかどうかは、それを読む側が決めた慣例です。

この慣例は大きく2つに分かれます。1つは同じキーをそのまま繰り返す方式、もう1つは角括弧を付けないと配列として認識しない方式です。

繰り返しキー方式と角括弧方式

ブラウザ標準のAPIである URLSearchParams は、繰り返されたキーを勝手に配列にまとめてはくれません。get("tag") は最初の値だけを返し、すべての値を取得するには getAll("tag") を自分で呼ぶ必要があります。

角括弧も特別扱いしません。tag[]=a&tag[]=b を渡すと、「tag」ではなく「tag[]」という名前のキー1つとして認識されます。

一方、角括弧方式を採用している言語・フレームワークは正反対に動きます。角括弧なしで tag=a&tag=b を繰り返すだけでは配列にならず最後の値1つだけが残り、配列として受け取るには tag[]=a&tag[]=b の形を使う必要があります。

手作業で確認する手順

値が消えてしまう問題は、この順番で確認していくと整理できます。まず、自分の側のコードが繰り返しキーで送っているのか、角括弧で送っているのかを確認します。

次に、サーバー側のドキュメントでクエリのパースルールがどちらなのかを照らし合わせます。両者が違うなら、クライアント側で形式を合わせるか、サーバー側に繰り返しキーを自分で配列にまとめるコードを追加する必要があります。

いちばん速い確認方法は、実際にクエリ文字列を入れて、結果が配列にまとまるかどうかを自分の目で見ることです。無料ツール「URLパーサー・クエリ文字列変換」で確認してみてください。

URLパーサー・クエリ文字列変換

URLやクエリ文字列を入力すると、配列にまとめられたパラメータをJSONですぐに確認できます。

よくつまずくポイント

状況原因
チェックボックスを複数選んだのに、サーバーには値が1つしか届かないサーバーが角括弧記法(tag[]=)だけを配列として認識するのに対し、クライアントは繰り返しキー(tag=a&tag=b)で送っているためです
URLSearchParams.get("tag") で取り出したが、値が1つしかないget() は常に最初の値だけを返します。すべてを受け取るには getAll("tag") を使う必要があります
JSONの配列値をクエリ文字列に変換したのに、サーバーが読めない繰り返しキー方式でシリアライズされたのに、サーバーは角括弧記法だけを配列として認識するケースです
同じURLなのに、言語・フレームワークを変えると結果が変わるクエリ文字列の配列表記に決められた標準がなく、パースルールがそれぞれ異なるためです

まとめ

クエリ文字列で同じキーが複数回現れるときに配列としてまとめるか、どの記法を配列として認めるかは、標準ではなく言語・フレームワークごとの慣例です。

値が消えたり1つだけになったりする問題は、ほとんどがクライアントが送る記法とサーバーが期待する記法の食い違いから生じます。どちらの慣例なのか迷ったら、実際のクエリ文字列をJSONに変換して目で確かめるのがいちばん確実です。

URLパーサー・クエリ文字列変換

URLやクエリ文字列を入力すると、配列にまとめられたパラメータをJSONですぐに確認できます。

よくある質問

tag[]=a&tag[]=b のように角括弧を入れると配列として認識されますか?

このツールはブラウザ標準の URLSearchParams をそのまま使っているため、角括弧を特別に解釈しません。tag[]=a&tag[]=b を入れると、「tag」ではなく「tag[]」という名前のキーに値が2つ入っているものとして表示されます。角括弧を配列表記として使うバックエンドと連携するときは、この違いを考慮する必要があります。

JSONの配列値をクエリ文字列に変換すると、どんな形式になりますか?

「JSON → クエリ」タブは、配列値を角括弧ではなく、同じキーを繰り返す方式でシリアライズします。たとえば {"tag": ["a", "b"]} は tag=a&tag=b になります。角括弧記法が必要なサーバーであれば、結果に自分で [] を付け足す必要があります。

「URL分解」と「クエリ → JSON」タブはどう違うのですか?

「URL分解」は protocol・host・port・pathname・hash までURL全体を分解して表示し、その中のクエリ部分もあわせてJSONで表示します。クエスチョンマークより後ろのクエリ文字列だけを持っている場合は、「クエリ → JSON」タブにそのまま貼り付ければ済みます。

この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む

関連記事

  1. 正規表現の置換 $1・$2・$&の使い方と違い正規表現の置換で$1・$2のグループ参照と$&(全体一致)が実際にどの文字列へ変わるのか、正規表現モードを切ると$がそのまま残る理由、画面の「置換回数」が数える値まで例で確認できます。
  2. 正規表現の特殊文字・フラグの意味とマッチ確認ガイド正規表現の^・$・.・*などの意味とg/i/m/s/u/yフラグの動作を整理し、正規表現テスターでマッチ数やキャプチャグループを確認する方法、ReDoSでブラウザが止まるパターンの避け方を解説します。
  3. 正規表現でメール・URLを抽出する方法とパターン集メールアドレス・URL・IP・電話番号・数値を抜き出す正規表現パターン5種と、必要な部分だけ取り出すキャプチャグループの使い方を解説します。
  4. 正規表現の記号の意味を分解して読み解く方法正規表現をキャプチャグループ・文字クラス・量指定子・アンカーに分け、各記号の意味を自分で読む方法と、自動で分解して日本語の解説を表示するツールの使い方を説明します。
  5. 空行削除の正規式と改行コード(CRLF・LF)の整え方貼り付けたテキストの不要な空行を正規式で削除・整理する方法と、Windows(CRLF)とmacOS・Linux(LF)の改行コードの違いへの対処を解説します。
  6. PDFの強制改行を削除し段落を一行に整えるPDFやメールからコピーしたテキストに紛れ込む強制改行を削除し、段落を保ったまま一行に整える方法を解説します。空白の整理や英数字の扱いもまとめました。

関連ツール