はじめに
Spring Boot の API でクエリパラメータを受け取るときに使う
@RequestParam。
「必須にしたいときは？」
「任意にしたいときは？」
「デフォルト値を入れる方法は？」
こういった疑問は実務でとても多いです。
この記事では、@RequestParam の応用を
やさしく・実務で役立つ形 で整理していきます。
まずは基本のコードから見ていきましょう。
まずはコードを確認
@GetMapping("/search")
public String search(@RequestParam String keyword) {
return "keyword: " + keyword;
}このように、
クエリパラメータを受け取るためのアノテーション
それが @RequestParam です。
@RequestParam の基本
一言でいうと、
「URL の ? 以降の値を受け取るためのアノテーション」
です。
例：
/search?keyword=apple
必須パラメータ（required = true）
デフォルトは「必須」
@GetMapping("/search")
public String search(@RequestParam String keyword) {
return keyword;
}/search?keyword=apple は OK /search は 400 Bad Request になります。
明示的に書く場合
@RequestParam(required = true)任意パラメータ（required = false）
パラメータがなくても OK にする
@GetMapping("/search")
public String search(@RequestParam(required = false) String keyword) {
return keyword;
}/search でもエラーになりません。
値がないときは null
- keyword が指定されない → null
- keyword= のように空 → 空文字
デフォルト値を設定する（defaultValue）
パラメータがなくても値を入れたいとき
@GetMapping("/search")
public String search(@RequestParam(defaultValue = "none") String keyword) {
return keyword;
}/search → keyword = “none” /search?keyword=apple → keyword = “apple”
required = false を書かなくてもよい
defaultValue を指定すると
自動的に required = false になります。
複数パラメータを扱う
例：ページング
@GetMapping("/items")
public String list(
@RequestParam(defaultValue = "1") int page,
@RequestParam(defaultValue = "10") int size) {
return page + ":" + size;
}実務でよく使うパターンです。
List で受け取る
クエリパラメータを複数指定
/items?category=book&category=toy
Spring 側
@GetMapping("/items")
public String list(@RequestParam List<String> category) {
return category.toString();
}名前を変えて受け取る（name / value）
URL のパラメータ名とフィールド名を変えたいとき
@GetMapping("/search")
public String search(@RequestParam(name = "q") String keyword) {
return keyword;
}/search?q=apple → keyword = “apple”
実務でよくある使い分け
必須にしたいとき
- 検索キーワードが必須
- ID が必須
@RequestParam String keyword任意にしたいとき
- ソート順
- フィルタ条件
@RequestParam(required = false) String sortデフォルト値を入れたいとき
- ページング
- ソート順の初期値
@RequestParam(defaultValue = "1") int pageあわせて知っておきたいポイント
@RequestParam は GET 以外でも使える
POST / PUT でもクエリパラメータを受け取れます。
@RequestBody と併用できる
@PostMapping("/users")
public String create(
@RequestParam(required = false) String token,
@RequestBody UserRequest request
)required = false のときは null に注意
DTO に詰める場合は Optional も使えます。
@RequestParam Optional<String> keyword使うときに気をつけたいこと
必須パラメータは明確に
API の仕様としてわかりやすくなります。
デフォルト値は仕様として決める
曖昧にすると後で混乱します。
パラメータ名の統一
プロジェクト全体で揃えると保守性が上がります。
まとめ
@RequestParam は、
「クエリパラメータを柔軟に受け取るためのアノテーション」
です。
- required = true（デフォルト）
- required = false（任意）
- defaultValue（デフォルト値）
- List や Optional も使える
- name でパラメータ名を変えられる
難しく聞こえますが、
「必須か、任意か、デフォルトか」
を決めるだけで十分です。
@RequestParam を使いこなすと、
API の入り口が一気にきれいになります。
必須・任意・デフォルト値を丁寧に扱うだけで、
API の使いやすさがぐっと上がります。
あなたの開発が、今日より少しだけ楽になりますように。
パラメータにも“必須”と“おまかせ”があるなんて…かわいいね。
コメント