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

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やクエリ文字列を入力すると、配列にまとめられたパラメータをJSONですぐに確認できます。

よくつまずくポイント
| 状況 | 原因 |
|---|---|
| チェックボックスを複数選んだのに、サーバーには値が1つしか届かない | サーバーが角括弧記法(tag[]=)だけを配列として認識するのに対し、クライアントは繰り返しキー(tag=a&tag=b)で送っているためです |
URLSearchParams.get("tag") で取り出したが、値が1つしかない | get() は常に最初の値だけを返します。すべてを受け取るには getAll("tag") を使う必要があります |
| JSONの配列値をクエリ文字列に変換したのに、サーバーが読めない | 繰り返しキー方式でシリアライズされたのに、サーバーは角括弧記法だけを配列として認識するケースです |
| 同じURLなのに、言語・フレームワークを変えると結果が変わる | クエリ文字列の配列表記に決められた標準がなく、パースルールがそれぞれ異なるためです |
まとめ
クエリ文字列で同じキーが複数回現れるときに配列としてまとめるか、どの記法を配列として認めるかは、標準ではなく言語・フレームワークごとの慣例です。
値が消えたり1つだけになったりする問題は、ほとんどがクライアントが送る記法とサーバーが期待する記法の食い違いから生じます。どちらの慣例なのか迷ったら、実際のクエリ文字列をJSONに変換して目で確かめるのがいちばん確実です。
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」タブにそのまま貼り付ければ済みます。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む