@PathVariableの使い方を解説！URLパラメータをSpringで取得する方法
新人
「SpringでURLの中にある値を使いたいんですけど、どうやって取り出せばいいんでしょうか？」
先輩
「それなら、@PathVariableを使うと簡単にURLの中の値を取得できるよ。」
新人
「@PathVariableってどういうものなんですか？」
先輩
「じゃあ、まずはREST APIのURLの仕組みから説明していこう。」
1. REST APIにおけるURLの仕組みとは？
SpringでREST APIを開発するとき、よく使われるのが「URLの中に変数を含める形式」です。例えば、「ユーザーIDが123の情報を取得したい」とき、URLを次のように書くことがあります。
GET /users/123
このように、URLの一部を「動的な値」にすることで、特定のユーザーや商品などの情報を柔軟に取得できます。この仕組みは「パスパラメータ」や「URLパスの変数化」と呼ばれています。
このようなURLの値をコントローラで受け取るために使うのが、@PathVariableというアノテーションです。
2. Springにおける@PathVariableの役割とは？
Springでは、@PathVariableを使うことで、URLの中に含まれた値をJavaのメソッドの引数として受け取ることができます。これは、REST APIを構築する上で非常に重要な機能です。
例えば、次のようなコードで、URLの中の{id}部分を取得できます。
@Controller
public class UserController {
@GetMapping("/users/{id}")
@ResponseBody
public String getUserById(@PathVariable String id) {
return "ユーザーID：" + id;
}
}
このコードでは、@PathVariableを使って、/users/123のようなURLから123を受け取り、それをidという引数にセットしています。
実行すると、ブラウザで次のような結果が表示されます。
ユーザーID：123
このように、@PathVariableは、URLの一部をそのままJavaの変数として扱える便利な機能なのです。
また、@PathVariableを使うことで、検索ページや詳細ページなど、さまざまな画面に対応するAPIを簡単に作ることができます。
ちなみに、このサンプルコードはpleiades環境で作成したSpring Bootプロジェクトで動作確認を行っています。Gradleを使用して依存関係を管理し、@Controllerでコントローラを実装しています。
ポイント：
- @PathVariableはURLから値を受け取るためのアノテーション
- @Controllerと@ResponseBodyを併用することで、簡単なAPIを作成可能
- SpringのURLパラメータ処理では、@PathVariableが基本の書き方となる
3. @PathVariableの使い方をもっと詳しく見てみよう
@PathVariableは、Spring MVCでURLの中から値を取得するための基本的な機能です。ここでは、具体的なコード例を使って、より丁寧に解説していきます。
次のコードは、商品IDをURLから受け取り、そのIDを画面に表示するサンプルです。
@Controller
public class ProductController {
@GetMapping("/products/{productId}")
@ResponseBody
public String getProduct(@PathVariable String productId) {
return "商品ID：" + productId;
}
}
この例では、/products/のあとに続く値（たとえばabc123など）をproductIdという名前の変数に取り込み、それをそのままレスポンスとして返しています。
ブラウザやPostmanなどで次のURLにアクセスしてみてください。
http://localhost:8080/products/abc123
画面には次のような結果が表示されます。
商品ID：abc123
このように、@PathVariableを使えば、URLの一部から値を取得し、それをコントローラ内で自由に使うことができます。動的な画面遷移や詳細表示など、さまざまな場面で活用される重要な技術です。
4. 実行の流れとURLパターンの具体的な解説
Springのコントローラは、リクエストされたURLとメソッドの@GetMappingに指定されたパスを照合して処理を実行します。ここで、@PathVariableを使うと、URLの中の変数部分をJavaの引数として渡すことができるようになります。
たとえば、次のようにURLを定義しておくと、
/products/{productId}
この{productId}の部分に任意の値を入れてアクセスすることで、その値がJavaの引数に渡されます。
例えば、次のようにアクセスした場合：
http://localhost:8080/products/999
productIdには999という文字列が代入され、メソッド内で自由に利用できます。
また、URLに使うパターン名（ここではproductId）と、Javaメソッドの引数名は同じにすることで、明示的に指定しなくても値を正しく受け取ることができます。
もちろん、引数名とパターン名が異なる場合は、次のようにvalue属性を明記することで紐づけることが可能です。
@GetMapping("/products/{id}")
@ResponseBody
public String getProduct(@PathVariable("id") String productId) {
return "商品ID：" + productId;
}
このように、URLとJavaの変数の対応を明確に管理することができるのが、@PathVariableの魅力です。
5. 複数の@PathVariableを使う場合の記述例
Springでは、@PathVariableを複数使ってURLの中から複数の値を取り出すことも可能です。これにより、より細かいリソース指定や複雑な画面遷移にも対応できます。
以下は、カテゴリIDと商品IDの2つの値をURLから取得するサンプルコードです。
@Controller
public class ProductController {
@GetMapping("/categories/{categoryId}/products/{productId}")
@ResponseBody
public String getProductDetail(@PathVariable String categoryId, @PathVariable String productId) {
return "カテゴリID：" + categoryId + "、商品ID：" + productId;
}
}
この例では、次のようなURLでアクセスすることができます。
http://localhost:8080/categories/book/products/456
このときの出力結果は以下のようになります。
カテゴリID：book、商品ID：456
このように複数の@PathVariableを使うことで、より多様なAPI設計が可能となります。
複数の値をURLに含めることで、対象のデータを正確に指定できるようになり、実務でもよく使われる形式です。たとえば、ECサイトや予約システムなどでも、カテゴリや日付、ユーザーIDなどを組み合わせて情報を取得するシーンが頻繁にあります。
また、pleiadesでのSpringプロジェクトでは、@Controllerと@ResponseBodyを組み合わせておくと、簡単に動作確認ができるので、初心者の方にもおすすめの開発スタイルです。
6. よくあるミスとその対処法
@PathVariableを使う際に初心者がつまずきやすいポイントとして、URLのパターンと実際のアクセスパスが一致していないというケースがあります。この場合、Springはそのリクエストを処理できず、404エラーが発生します。
たとえば、コントローラで次のようにURLを定義していたとします。
@GetMapping("/members/{id}")
@ResponseBody
public String getMember(@PathVariable String id) {
return "会員ID：" + id;
}
この状態でブラウザから次のURLにアクセスした場合：
http://localhost:8080/members/
エラーが発生します。というのも、{id}に対応する値がURLに含まれていないため、Springはこのリクエストを無効と判断してしまうのです。
このような問題を避けるには、@PathVariableを指定したら、URLのパスにも必ず対応する値を含めるように注意しましょう。
次に多いのが型の不一致エラーです。Javaでは、URLから受け取る値はすべて文字列として扱われますが、コード上でintやlongなどにマッピングするときには注意が必要です。
次のようなコードを見てください。
@GetMapping("/orders/{orderId}")
@ResponseBody
public String getOrder(@PathVariable int orderId) {
return "注文ID：" + orderId;
}
このとき、URLにabcなどの数値でない値を指定すると、アプリケーションはエラーで停止します。
http://localhost:8080/orders/abc
対処法としては、@PathVariableの型をStringにしておき、必要があればメソッド内で明示的に変換処理を加えるという方法があります。また、型変換時の例外処理を追加することで、ユーザーに適切なメッセージを表示することも可能です。
@GetMapping("/orders/{orderId}")
@ResponseBody
public String getOrder(@PathVariable String orderId) {
try {
int id = Integer.parseInt(orderId);
return "注文ID：" + id;
} catch (NumberFormatException e) {
return "注文IDは数値で入力してください";
}
}
このようにすれば、不正な入力にも対応できる柔軟なAPI設計になります。
7. @PathVariableの応用例と実務での利用シーン
@PathVariableは、単にURLの中の値を取り出すだけでなく、リソースの階層構造を表現するためにも活用されます。
たとえば、次のような構成を考えてみましょう。
/users/{userId}/posts/{postId}/comments/{commentId}
このようなパスを使えば、「どのユーザーの、どの投稿の、どのコメントか」というような構造的な情報をURLにそのまま組み込むことができます。
@Controller
public class CommentController {
@GetMapping("/users/{userId}/posts/{postId}/comments/{commentId}")
@ResponseBody
public String getComment(@PathVariable String userId,
@PathVariable String postId,
@PathVariable String commentId) {
return "ユーザーID：" + userId + "、投稿ID：" + postId + "、コメントID：" + commentId;
}
}
このコードでは、3つの@PathVariableを使ってURLの中の値をそれぞれ取り出しています。
http://localhost:8080/users/77/posts/88/comments/99
実行すると、次のような出力が表示されます。
ユーザーID：77、投稿ID：88、コメントID：99
このようなURLパスの構造化は、RESTfulなAPI設計において非常に重要です。@PathVariableを使うことで、直感的かつ階層的なリソースの管理ができるようになります。
実務では、顧客管理システムや商品管理システムなどでも、/customers/{id}や/products/{productId}/detailsといった形式で@PathVariableがよく使われています。
また、複数の@PathVariableを組み合わせることで、シンプルなURL設計ができるという点でも利便性が高く、SEOの観点でもURLに意味を持たせることが可能になります。
補足ポイント：
- URLの中の値を取り出す方法として@PathVariableは定番
- Spring URLパスの変数化により、柔軟なリソース設計が可能
- 型の扱いやパスの不一致には注意が必要
このように、@PathVariableは基本から応用まで広く活用できる強力な仕組みです。特に実務の現場では、APIの構造設計と直結する要素のため、しっかりと理解しておくと今後の開発でも大いに役立ちます。
