はじめに
Spring Boot で API を作っていると、
パスパラメータ と クエリパラメータ の 2 種類のパラメータをよく使います。
「どっちを使えばいいの？」
「URL 設計の基準がわからない」
「Spring ではどう受け取るの？」
そんな疑問を持つ方も多いと思います。
この記事では、パスパラメータとクエリパラメータの違いを
やさしく・実務で役立つ形 で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
パスパラメータ（リソースを特定する）
@GetMapping("/users/{id}")
public String getUser(@PathVariable Long id) {
return "id: " + id;
}クエリパラメータ（条件を指定する）
@GetMapping("/search")
public String search(@RequestParam String keyword) {
return "keyword: " + keyword;
}同じ「パラメータ」でも、
意味も使い方もまったく違う
というのがポイントです。
パスパラメータとは
一言でいうと、
「特定のリソースを指定するためのパラメータ」
です。
例
/users/1→ ID が 1 のユーザー/items/10→ 商品 ID 10/orders/2024→ 注文番号 2024
Spring での受け取り方
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) { ... }特徴
- URL の一部として扱われる
- リソースを一意に特定する
- REST API では「主語」にあたる部分
- キャッシュされやすい
クエリパラメータとは
一言でいうと、
「検索条件やオプションを指定するためのパラメータ」
です。
例
/search?keyword=apple/users?age=20&sort=desc/items?category=book&page=2
Spring での受け取り方
@GetMapping("/search")
public List<Item> search(@RequestParam String keyword) { ... }特徴
- URL の ? 以降に書く
- 条件・フィルタ・オプションを表す
- 複数指定しやすい
- 順番は関係ない
違いを整理
| 項目 | パスパラメータ | クエリパラメータ |
|---|---|---|
| 目的 | リソースを特定 | 条件を指定 |
| URL の例 | /users/1 | /users?age=20 |
| Spring の受け取り | @PathVariable | @RequestParam |
| 意味 | 主語 | 修飾語 |
| REST 的な使い方 | 必須 | 任意 |
この表だけで、実務の 8 割は理解できます。
実務での使い分け
ユーザー ID を指定して取得 → パスパラメータ
GET /users/1ユーザー一覧を条件付きで取得 → クエリパラメータ
GET /users?age=20&sort=desc商品の詳細 → パスパラメータ
GET /items/10商品検索 → クエリパラメータ
GET /items?keyword=apple迷ったときの基準
- その値がないとリソースを特定できない → パス
- その値がなくてもリソースは存在する → クエリ
このルールでほぼ迷いません。
あわせて知っておきたいポイント
パスパラメータは階層構造に向いている
例： /users/1/orders/5
クエリパラメータは検索条件に向いている
例： /orders?from=2024-01-01&to=2024-01-31
@RequestParam はデフォルトで必須
@RequestParam(required = false)で任意にできます。
パスパラメータは型変換も自動
Long, UUID, Integer など自動で変換されます。
使うときに気をつけたいこと
パスパラメータに検索条件を入れない
NG: /users/age/20
OK: /users?age=20
クエリパラメータに ID を入れない
NG: /users?id=1
OK: /users/1
URL 設計は一貫性が大事
プロジェクト全体でルールを統一すると保守性が上がります。
まとめ
パスパラメータとクエリパラメータは、
「リソースを特定するか」「条件を指定するか」
で役割がはっきり分かれています。
- パス → 主語（リソースを特定）
- クエリ → 修飾語（条件を指定）
- Spring では @PathVariable / @RequestParam
- 迷ったら「その値が必須かどうか」で判断
難しく聞こえますが、
「パスは主語、クエリは条件」
と理解できれば十分です。
パスパラメータとクエリパラメータの違いを理解すると、
API の URL 設計が一気にきれいになります。
Controller のコードも読みやすくなり、
開発がとてもスムーズになります。
あなたの開発が、今日より少しだけ楽になりますように。
主語と条件…URL にも役割があるんだね。かわいい違いだね。
コメント