Spring MVCの@PathVariableと@RequestParamを完全解説！初心者向けの使い分け・必須／任意・型変換・デフォルト値まで

1. @PathVariableとは？URLの一部を変数として受け取る方法

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とは？クエリパラメータを受け取る方法

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を受け取ります。

3. 必須か任意かを指定するには？

3. 必須か任意かを指定するには？

@RequestParamはデフォルトでrequired=trueになっており、パラメータが無いとエラーになります。ただし、任意にしたい場合はrequired=falseに設定します。

@GetMapping("/search")
public String search(@RequestParam(required = false) String keyword) {
    return "検索キーワード：" + keyword;
}

一方で、@PathVariableは基本的に必須ですが、バージョンによってはオプションで対応可能なケースもあります。ただし、RESTfulな設計では省略されることは少なく、使い方としては@RequestParamより柔軟性に欠けます。

4. 型変換は自動でしてくれるの？

4. 型変換は自動でしてくれるの？

@PathVariableや@RequestParamで受け取る値は、基本的な型（int、Long、booleanなど）であれば、Springが自動的に型変換してくれます。

@GetMapping("/age/{value}")
public String showAge(@PathVariable int value) {
    return "年齢：" + value;
}

ただし、文字列を数値に変換できない場合はエラーになるため、バリデーションも重要です。

5. デフォルト値を設定する方法

5. デフォルト値を設定する方法

@RequestParamにはデフォルト値を設定できます。これにより、値が渡されなかった場合にもエラーを避けられます。

@GetMapping("/search")
public String search(@RequestParam(defaultValue = "1") int page) {
    return "ページ番号：" + page;
}

@PathVariableには直接デフォルト値を設定する方法はないため、別途コントロールロジックで対応します。

6. 実行結果を確認してみよう

6. 実行結果を確認してみよう

/users/10 にアクセス → User ID: 10
/search?keyword=spring&page=2 にアクセス → キーワード：spring ページ：2
/search にアクセス（keywordが任意） → 検索キーワード：null
/search にアクセス（pageがデフォルト1） → ページ番号：1

7. @PathVariableと@RequestParamの使い分けのポイント

7. @PathVariableと@RequestParamの使い分けのポイント

• URLの一部を使うとき：@PathVariableを使う
• 検索条件・オプション指定など：@RequestParamが便利
• 任意／デフォルト値を使いたい：@RequestParamのほうが柔軟
• REST API設計：リソースを特定するIDなどは@PathVariableが適している

8. HTMLでのURL設計とコントローラーの関係

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. よくあるエラーと対処法

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開発を目指しましょう。

この記事を読んだ人からの質問

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

Spring MVCで@PathVariableと@RequestParamの違いがいまいちわかりません。どう使い分ければいいですか？

@PathVariableはURLの一部（パス）から値を受け取るのに使い、@RequestParamはURLのクエリパラメータ（?以降）から値を受け取るときに使います。例えば、ユーザーIDなどリソースの特定には@PathVariable、検索やページ番号など可変的な値には@RequestParamを使い分けます。

@RequestParamの値が存在しないときにエラーになるのを防ぐ方法はありますか？

@RequestParamにはrequired属性を指定できます。required=falseにするとパラメータが無くてもエラーにならず、nullとして扱われます。さらにdefaultValueを使うことで、デフォルト値も設定可能です。