Spring MVCの@RequestParamによるクエリパラメータ取得を完全解説！初心者向けに基本からやさしく理解
新人
「Spring MVCで画面を表示するところまではできたんですが、URLに付いている値をJavaで受け取る方法が分からなくなりました。」
先輩
「Webアプリでは、そのURLの後ろに付く値を受け取る場面がよくあります。Spring MVCでは@RequestParamを使うと簡単に扱えますよ。」
新人
「あの『?』の後ろに付いている値ですよね？仕組みからちゃんと知りたいです。」
先輩
「まずはSpring MVCの役割と、クエリパラメータの基本から整理していきましょう。」
1. Spring MVCとは何か（Webアプリ開発における役割）
Spring MVCとは、Javaを使ってWebアプリケーションを作成するためのフレームワークです。Spring Frameworkの中でも、ブラウザからのアクセスを受け取り、画面を表示するまでの流れを担当する仕組みとして多くの現場で利用されています。
Webアプリでは、ユーザーがブラウザからURLにアクセスすると、その情報がサーバーに送られ、Javaのプログラムが処理を行います。その結果としてHTMLが作られ、再びブラウザに返されます。Spring MVCは、この一連の流れを分かりやすく整理し、初心者でも理解しやすい形で実装できるようにしてくれます。
Pleiadesを使ってSpring MVCのプロジェクトを作成すると、Gradle構成や必要な設定が最初から用意された状態になります。依存関係の追加もPleiadesのチェック操作だけで行えるため、環境構築でつまずきにくい点が特徴です。
Spring MVCでは、画面表示やリクエスト処理を担当するクラスをコントローラと呼びます。コントローラには@Controllerアノテーションを付けることで、「このクラスがWebアプリの入り口である」ことをSpringに伝えます。
@Controller
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "hello";
}
}
このように、URLにアクセスされたときに対応する画面名を返すのが、Spring MVCにおける最も基本的な役割です。
2. クエリパラメータとは何か（URLに付く値の基本）
クエリパラメータとは、URLの末尾に付けてサーバーに情報を渡すための仕組みです。「?」以降に書かれている部分がクエリパラメータで、画面表示の条件や検索キーワードなどを伝えるために使われます。
例えば、次のようなURLを見てみましょう。
/search?keyword=spring&page=1
このURLでは、「keyword」に「spring」、「page」に「1」という値が設定されています。このように、クエリパラメータは「名前=値」の形で複数指定することができます。
初心者の方は、クエリパラメータを難しく感じがちですが、「URLに一緒に付けて送る追加情報」だと考えると理解しやすくなります。画面の表示内容を切り替えたり、条件を指定したりするために、非常によく使われる仕組みです。
Spring MVCでは、このクエリパラメータを@RequestParamを使ってJavaのメソッド引数として受け取ることができます。
@Controller
public class SearchController {
@GetMapping("/search")
public String search(@RequestParam String keyword) {
return "searchResult";
}
}
この例では、URLに付いている「keyword」の値が、そのままメソッドの引数として渡されます。URLとJavaの処理が自然につながっている点が、Spring MVCの分かりやすさです。
3. Spring MVCでパラメータを受け取る必要性
Spring MVCでクエリパラメータを受け取る必要があるのは、Webアプリがユーザーの操作に応じて動作を変えるためです。パラメータを使わなければ、画面は常に同じ内容しか表示できません。
検索条件やページ番号、表示モードなどをURLから受け取ることで、ユーザーごとに異なる画面を表示できるようになります。そのため、クエリパラメータと@RequestParamの理解は、Spring MVC初心者にとって非常に重要なポイントです。
この後の記事では、@RequestParamの詳しい使い方や注意点について、さらに具体的に解説していきます。
4. @RequestParamとは何か（基本的な役割）
@RequestParamは、Spring MVCでクエリパラメータを受け取るために用意されているアノテーションです。ブラウザから送られてきたURLの中に含まれる値を、コントローラのメソッド引数として受け取る役割を持っています。
Webアプリでは、URLに付いている情報をもとに画面の内容を切り替える場面が多くあります。そのとき、URLに含まれるクエリパラメータをJavaの処理で使える形に変換してくれるのが@RequestParamです。
例えば、ブラウザから「/sample?name=taro」というURLでアクセスされた場合、「name」に設定されている「taro」という値を、そのままJavaの変数として扱えるようになります。Spring MVCを使わずにこれを実装しようとすると、リクエスト情報を直接扱う必要があり、初心者には少し難しく感じられます。
@RequestParamを使うことで、「URLに付いている値を受け取る」という処理を、非常にシンプルな形で書けるようになります。そのため、Spring MVC初心者が最初に覚えるべき重要なアノテーションの一つと言えます。
5. @RequestParamを使った基本的な受け取り方
@RequestParamの基本的な使い方はとてもシンプルです。コントローラのメソッド引数に@RequestParamを付け、その後ろに受け取りたい変数名を書くだけで、クエリパラメータを取得できます。
まずは、URLの例から見てみましょう。次のURLでは、「name」というクエリパラメータが設定されています。
/hello?name=hanako
このURLに対応するコントローラは、次のように記述できます。
@Controller
public class SampleController {
@GetMapping("/hello")
public String hello(@RequestParam String name) {
return "hello";
}
}
このコードでは、「name」というクエリパラメータの値が、そのままnameというメソッド引数に渡されます。特別な変換処理を書く必要はなく、Spring MVCが自動的に値を設定してくれます。
初心者の方は、「URLの値がいつJavaに渡されているのか分からない」と感じることがありますが、実際にはブラウザからリクエストが送られた時点で、Spring MVCが@RequestParamを見て、自動的に値を引き渡しています。
この仕組みにより、URL → コントローラ → 画面表示という流れを、自然な形でつなげることができます。
6. クエリパラメータとメソッド引数の対応関係
@RequestParamを使う際に、初心者が最もつまずきやすいポイントが「名前の一致」です。クエリパラメータの名前と、メソッド引数の名前は、基本的に同じである必要があります。
例えば、URLが次のようになっている場合を考えてみましょう。
/search?keyword=spring
このとき、コントローラ側では「keyword」という名前で受け取る必要があります。
@Controller
public class SearchController {
@GetMapping("/search")
public String search(@RequestParam String keyword) {
return "result";
}
}
もし、メソッド引数の名前を「word」など別の名前にしてしまうと、Spring MVCはどのクエリパラメータを渡せばよいのか分からず、画面が正しく表示されなくなります。このとき初心者は、「なぜ画面が表示されないのか」と悩みがちです。
画面が表示されない原因の多くは、URLのクエリパラメータ名と、@RequestParamで受け取る引数名が一致していないことにあります。そのため、URLを書いたら、その名前をそのままJava側でも使っているかを必ず確認することが大切です。
このように、クエリパラメータとメソッド引数は一対一で対応しており、その対応関係を正しく理解することが、Spring MVCで@RequestParamを使いこなすための第一歩になります。
7. パラメータが渡らないときによくある原因
Spring MVCで@RequestParamを使っているにもかかわらず、値が取得できないときは、コードの書き方そのものよりも「前提の考え方」がずれているケースがほとんどです。エラーが出ないのに画面が正しく表示されない場合は、落ち着いて仕組みを一つずつ確認することが大切です。
まず最も多い原因が、URLにクエリパラメータ自体が付いていないケースです。@RequestParamは、あくまでURLの「?」以降に書かれている値を受け取る仕組みです。そのため、ブラウザで「/search」とだけアクセスしている場合、受け取る値が存在しません。
次に多いのが、URLに書かれているパラメータ名と、コントローラ側で受け取ろうとしている名前が一致していないケースです。Spring MVCは自動的に値を渡してくれますが、「名前が同じであること」が前提になっています。
例えば、URLが次のようになっている場合を考えてみましょう。
/search?keyword=spring
このとき、コントローラ側で次のように書いていると、値は取得できません。
@GetMapping("/search")
public String search(@RequestParam String word) {
return "result";
}
URLには「keyword」と書かれているのに、Java側では「word」という名前で受け取ろうとしているため、Spring MVCは対応関係を見つけられません。この結果、「値が渡らない」という状態になります。
このような場合は、エラーメッセージよりも、「URLとメソッド引数の名前が一致しているか」を最初に確認することが重要です。Spring MVC RequestParam 初心者の方ほど、この確認を後回しにしてしまいがちなので注意しましょう。
8. 初心者がつまずきやすい@RequestParamの注意点
@RequestParamは便利な仕組みですが、初心者が混乱しやすいポイントもいくつかあります。その多くは「Spring MVCが何を自動でやってくれているのか」を正しく理解していないことが原因です。
まず意識しておきたいのは、@RequestParamは「必ずURLに値がある前提」で動くという点です。URLにクエリパラメータが存在しない状態で@RequestParamを使うと、想定通りに画面が表示されないことがあります。
また、クエリパラメータは文字列として送られてくる、という点も重要です。数値のように見える値であっても、ブラウザから送られてくる時点では文字として扱われています。Spring MVCが自動で型変換してくれるため普段は意識しなくて問題ありませんが、「URLの値がそのままJavaに渡っている」という感覚を持っておくと理解しやすくなります。
さらに、URLの書き間違いもよくある原因の一つです。「?」や「&」の付け忘れ、全角文字の混入などがあると、クエリパラメータとして正しく認識されません。この場合、Java側のコードをどれだけ見直しても原因が見つからず、時間を無駄にしてしまうことがあります。
Spring MVCでクエリパラメータを取得するときは、「ブラウザで入力しているURL」「コントローラの@GetMapping」「@RequestParamの引数名」の三点をセットで確認する習慣を身に付けることが、つまずきを減らす近道になります。
9. @RequestParamを理解した後に学ぶべきこと
@RequestParamによるクエリパラメータ取得を理解できたら、Spring MVCの画面表示における基礎はかなり身に付いた状態と言えます。URLから値を受け取り、その内容に応じて処理や表示を変える、というWebアプリの基本的な動きが見えてくるはずです。
次の学習ステップとして意識しておきたいのが、「URLそのものの構造」を使って値を渡す方法です。Spring MVCには@PathVariableという仕組みがあり、これはURLのパス部分から値を受け取るために使われます。
@RequestParamが「URLの後ろに付く値」を扱うのに対して、@PathVariableは「URLの一部そのもの」を値として扱います。どちらも画面表示を制御するために使われますが、役割や使いどころが少し異なります。
ただし、現時点では細かい違いを無理に覚える必要はありません。「クエリパラメータは@RequestParamで受け取る」「URLの構造に埋め込まれた値は別の仕組みがある」という程度の理解で十分です。
Spring MVCでは、URL → パラメータ取得 → コントローラ処理 → 画面表示、という流れをどう設計するかが重要になります。@RequestParamを正しく使えるようになった今、その流れ全体を意識しながら、少しずつ理解を深めていくと、Webアプリ開発がより楽しく感じられるようになるでしょう。
