Spring MVCの@PathVariableと@RequestParamを完全解説！初心者向けの使い分け・必須／任意・型変換・デフォルト値まで
生徒
「Spring MVCでURLのパラメータを受け取る方法って何がありますか？」
先生
「Spring MVCでは@PathVariableと@RequestParamの2つがよく使われます。それぞれ使い方や用途が少し違うんですよ。」
生徒
「違いがよくわからなくて…あと、必須か任意にできるんですか？」
先生
「もちろんです。それでは一緒に、使い分けや注意点を詳しく見ていきましょう！」
1. @PathVariableとは？URLの一部を変数として受け取る方法
@PathVariableは、URLパスの一部をパラメータとして受け取るために使用されます。例えば、/users/123というURLの「123」の部分をコントローラーで受け取りたい場合に使います。
@GetMapping("/users/{id}")
public String getUser(@PathVariable Long id) {
return "User ID: " + id;
}
この例では、URLの{id}部分がLong idにマッピングされます。
2. @RequestParamとは？クエリパラメータを受け取る方法
@RequestParamは、URLのクエリパラメータ（例：?page=2）を取得するために使われます。フォーム送信や検索機能でよく使われます。
@GetMapping("/search")
public String search(@RequestParam String keyword, @RequestParam int page) {
return "キーワード：" + keyword + " ページ：" + page;
}
/search?keyword=java&page=2というリクエストに対して、keywordとpageを受け取ります。
将来を見据えて、＋αのスキルを身につけたい方へ
JavaやLinuxを学んでいても、「このままで市場価値は上がるのか」 「キャリアの選択肢を広げたい」と感じる方は少なくありません。
AIを学ぶならアイデミープレミアム
3. 必須か任意かを指定するには？
@RequestParamはデフォルトでrequired=trueになっており、パラメータが無いとエラーになります。ただし、任意にしたい場合はrequired=falseに設定します。
@GetMapping("/search")
public String search(@RequestParam(required = false) String keyword) {
return "検索キーワード：" + keyword;
}
一方で、@PathVariableは基本的に必須ですが、バージョンによってはオプションで対応可能なケースもあります。ただし、RESTfulな設計では省略されることは少なく、使い方としては@RequestParamより柔軟性に欠けます。
4. 型変換は自動でしてくれるの？
@PathVariableや@RequestParamで受け取る値は、基本的な型（int、Long、booleanなど）であれば、Springが自動的に型変換してくれます。
@GetMapping("/age/{value}")
public String showAge(@PathVariable int value) {
return "年齢：" + value;
}
ただし、文字列を数値に変換できない場合はエラーになるため、バリデーションも重要です。
5. デフォルト値を設定する方法
@RequestParamにはデフォルト値を設定できます。これにより、値が渡されなかった場合にもエラーを避けられます。
@GetMapping("/search")
public String search(@RequestParam(defaultValue = "1") int page) {
return "ページ番号：" + page;
}
@PathVariableには直接デフォルト値を設定する方法はないため、別途コントロールロジックで対応します。
6. 実行結果を確認してみよう
/users/10 にアクセス → User ID: 10
/search?keyword=spring&page=2 にアクセス → キーワード：spring ページ：2
/search にアクセス（keywordが任意） → 検索キーワード：null
/search にアクセス（pageがデフォルト1） → ページ番号：1
7. @PathVariableと@RequestParamの使い分けのポイント
- URLの一部を使うとき：
@PathVariableを使う - 検索条件・オプション指定など：
@RequestParamが便利 - 任意／デフォルト値を使いたい：
@RequestParamのほうが柔軟 - REST API設計：リソースを特定するIDなどは
@PathVariableが適している
8. HTMLでのURL設計とコントローラーの関係
HTMLフォームやリンクからのリクエストが、Spring MVCのコントローラーにどうマッピングされるかも重要です。
<form method="get" action="/search">
<input type="text" name="keyword">
<input type="submit" value="検索">
</form>
このフォームでは、@RequestParam("keyword")で受け取ることができます。一方、リンクからリソースIDを送る場合は@PathVariableが活躍します。
<a href="/users/5">ユーザー詳細</a>
9. よくあるエラーと対処法
- MissingServletRequestParameterException：必須の
@RequestParamが不足している - TypeMismatchException：型変換に失敗（文字列→数値など）
- 404エラー：
@PathVariableのURLが一致していない
これらのエラーを防ぐには、必須・任意・デフォルト値の扱いをしっかり理解することが重要です。
まとめ
今回はSpring MVCにおける@PathVariableと@RequestParamの使い方について、初心者でも理解しやすいように解説しました。@PathVariableはURLの一部を変数として受け取り、リソースを特定する用途に向いています。一方@RequestParamは、検索条件やオプション指定に適しており、任意パラメータの設定やデフォルト値の設定が簡単に行える柔軟なアノテーションです。
特にREST API開発では、これらを正しく使い分けることが非常に重要です。例えば、ユーザーIDのように明確にリソースを表す情報は@PathVariableで受け取り、検索キーワードやページ番号のように任意で変動する情報は@RequestParamを使うことで、直感的でわかりやすいAPI設計が実現できます。
また、型変換の自動処理やバリデーションの重要性も見逃せません。Spring MVCでは基本的な型（intやbooleanなど）は自動的に変換されますが、文字列から数値への変換時にはエラーが発生する可能性があります。そのため、入力値の検証やエラーハンドリングも重要なポイントです。
実際のHTMLとコントローラーの連携においても、formタグを用いたGETリクエストでは@RequestParam、URLリンクによる詳細画面表示では@PathVariableが活躍します。これにより、フロントエンドとバックエンドの役割が明確になり、コードの見通しも良くなります。
さらに、@RequestParamのrequired属性やdefaultValueを活用することで、ユーザーがパラメータを指定しなかった場合でも柔軟に対応可能です。このような実装は、ユーザーにとって使いやすく、開発者にとってもメンテナンスしやすいアプリケーションにつながります。
最後に、よくあるエラーとしてMissingServletRequestParameterExceptionやTypeMismatchExceptionなどがあることも確認しました。こうした例外を防ぐには、パラメータの有無や型を意識した設計と適切なハンドリングが不可欠です。
ここまでで、Spring MVCのパラメータ受け取りに関する基本的な知識から実践的な使い分け、エラーハンドリングまで幅広く理解できたかと思います。ぜひ、実際のプロジェクトでも@PathVariableと@RequestParamを使いこなし、保守性の高いAPI開発を目指しましょう。
生徒
「結局、@PathVariableはどんな場面で使うといいんですか？」
先生
「リソースを一意に識別するための値、たとえばユーザーIDや商品IDをURLの一部から取り出したいときに使います。RESTfulな設計にぴったりです。」
生徒
「じゃあ、@RequestParamは検索やフィルターの条件みたいな“オプション”に使うんですね？」
先生
「その通りです！requiredやdefaultValueも設定できるので、フォームの入力やページネーションにも最適です。」
生徒
「型変換も自動でしてくれるのは便利ですね。でも、失敗しないようにバリデーションも必要ですよね？」
先生
「まさにそのとおり。開発では想定外の入力が来ることもあるので、型だけでなく中身のチェックも大事です。」
生徒
「今日の学びでAPI設計の基本がだいぶわかってきました！」
先生
「これからは実際のプロジェクトでも意識して使い分けていきましょう。理解が深まったようで何よりです。」
この記事を読んだ人からの質問
