Java | Web 基礎・HTTP・REST：HTTP 詳細 － クエリパラメータ

クエリパラメータを一言でいうと

クエリパラメータは
「同じ URL の“条件やオプション”を指定するための追加情報」
です。

/users という「ユーザー一覧」というリソースに対して、
「有効なユーザーだけ欲しい」「2 ページ目が欲しい」「名前で絞り込みたい」
といった“絞り込み・検索・ページング”の条件を渡すのに使います。

クエリパラメータの見た目と基本構造

URL のどこに書かれているか

典型的な例を一つ見てみます。

https://example.com/users?active=true&page=2

? より前が「パス」、? より後ろが「クエリパラメータ」です。
クエリパラメータは、key=value を & でつないだ形で並びます。

この例だと、

active=true
page=2

という 2 つのパラメータが付いている、ということになります。

何を表しているか

/users は「ユーザーという集合」を表すパスです。
そこに ?active=true&page=2 が付くことで、

「有効なユーザーだけ」
「2 ページ目」

という“条件・オプション”が追加されます。

つまり、
パスが「何を（どのリソースを）」
クエリが「どういう条件で」
という役割分担になっています。

Java（Spring）でのクエリパラメータの受け取り方

@RequestParam で素直に受け取る

Spring では、クエリパラメータは @RequestParam で受け取ります。

@GetMapping("/users")
public List<UserResponse> search(
        @RequestParam(required = false) Boolean active,
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "20") int size
) {
    return userService.search(active, page, size);
}

@GetMapping("/users")
public List<UserResponse> search(
        @RequestParam(required = false) Boolean active,
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "20") int size
) {
    return userService.search(active, page, size);
}

このメソッドに対して、

GET /users?active=true&page=2

が来ると、

active → true
page → 2
size → デフォルトの 20

という形で値が入ります。

ここで大事なのは、
「クエリパラメータは“オプション”であることが多い」
という感覚です。

required = false や defaultValue をうまく使って、
「指定されなかったときはどう振る舞うか」も一緒に設計します。

クエリパラメータが活躍する典型パターン

検索・絞り込み

例えば、ユーザー検索 API。

GET /users?name=alice&ageFrom=20&ageTo=30

意味は「名前に alice を含み、年齢が 20〜30 歳のユーザーを検索して」です。

Java 側では、こう受け取れます。

@GetMapping("/users")
public List<UserResponse> search(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer ageFrom,
        @RequestParam(required = false) Integer ageTo
) {
    return userService.search(name, ageFrom, ageTo);
}

@GetMapping("/users")
public List<UserResponse> search(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer ageFrom,
        @RequestParam(required = false) Integer ageTo
) {
    return userService.search(name, ageFrom, ageTo);
}

「指定されたものだけ条件に使う」という実装にすると、
柔軟な検索 API になります。

ページング・ソート

一覧 API では、ページングやソートもクエリパラメータで表現するのが定番です。

GET /users?page=3&size=50&sort=createdAt,desc

「3 ページ目」「1 ページ 50 件」「作成日時の降順」という意味です。

Spring Data を使うと、Pageable でまとめて受け取ることもできます。

パスパラメータとの違いをはっきりさせる

パスは「どのリソースか」、クエリは「どういう条件か」

/users/10
これは「ID=10 のユーザー」という“1 つのリソース”を指します。

/users?active=true
これは「ユーザーという集合のうち、有効なものだけ」という“条件付きの集合”を指します。

つまり、

パスパラメータ（/users/{id}）
→ リソースそのものを特定する情報

クエリパラメータ（?active=true）
→ そのリソースに対する条件・オプション

という役割分担です。

「ID のように、その値が変わると“別のもの”になる」ものはパス側へ。
「条件やフィルタのように、“見方が変わるだけ”」のものはクエリ側へ。

この軸を持っておくと、URL 設計がかなりきれいになります。

クエリパラメータで気をつけたいポイント

機密情報を載せない

クエリパラメータは URL にそのまま見えます。
ブラウザの履歴
アクセスログ
プロキシのログ

などに残りやすいので、
パスワードやクレジットカード番号などの機密情報を
クエリに載せるのは NG です。

ログイン情報などは、
POST のボディに載せるのが基本です。

長くなりすぎるものはボディへ

クエリパラメータは、
ブラウザやサーバーによって長さ制限があることがあります。

巨大な検索条件
複雑な JSON
大量の ID リスト

などは、
クエリではなく POST のボディに載せる設計を検討した方が安全です。

初心者向けまとめ：クエリパラメータを自分の言葉で説明するなら

あなたの言葉で整理すると、こうなります。

クエリパラメータは、
URL の ? 以降に書く key=value の組み合わせで、
「同じリソースに対して、検索条件やページング、ソートなどの“オプション”を指定するためのもの」。

パスは「どのリソースか」、
クエリは「そのリソースをどういう条件で扱うか」。

Java（Spring）では @RequestParam で受け取り、
required や defaultValue を使って、
「指定されなかったときの振る舞い」も含めて設計する。

もしよければ、
「ユーザー検索 API」を題材にして、
自分ならどんなクエリパラメータ（name, ageFrom, ageTo, page, size など）を用意するか、一緒に書き出してみよう。
その設計を自分の言葉で説明できるようになったとき、クエリパラメータはもう“ただの文字列”ではなく、“あなたがコントロールできるインターフェース”になっているはず。