Micronautでクエリパラメータを受け取る方法を徹底解説！初心者向けWebAPI開発ガイド

1. クエリパラメータとは何か

1. クエリパラメータとは何か

クエリパラメータとは、Webブラウザなどがサーバーに対して追加の情報を送るための仕組みです。URLの末尾に「?」を付け、その後に「名前=値」という形式で記述します。複数の情報を送りたい場合は「&」で繋ぎます。例えば、検索エンジンで「java」と検索したときに、URLが「/search?q=java」のようになるのが典型的な例です。

プログラミングを始めたばかりの方でも、Webサイトの「検索窓」や「並び替え機能」をイメージすれば分かりやすいでしょう。ページそのものの住所（パス）は変えずに、表示する中身だけを条件によって絞り込みたいときに非常によく使われます。Micronaut（マイクロノート）はこのクエリパラメータを扱うのが非常に得意で、Javaのメソッドを呼び出すのと同じ感覚でデータを取得できます。

2. Micronautでの最も基本的な受け取り方

2. Micronautでの最も基本的な受け取り方

MicronautのHTTPサーバーでクエリパラメータを受け取る最もシンプルな方法は、コントローラーのメソッドの引数に、パラメータと同じ名前の変数を定義することです。これだけで、MicronautがURLを解析して自動的に値を代入してくれます。

例えば、名前を受け取って挨拶を返すAPIを考えてみましょう。URLが「/hello?name=太郎」だった場合、メソッドの引数名を「name」にしておけば、プログラムの中で「太郎」という文字列をそのまま使うことができます。特別な解析コードを書く必要がないため、コードが非常にスッキリします。

package com.example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/greet")
public class GreetController {

    @Get("/simple")
    public String hello(String name) {
        // 引数名がURLのパラメータ名(?name=...)と自動で紐付きます
        return "こんにちは、" + name + "さん！";
    }
}

（アクセス例：http://localhost:8080/greet/simple?name=田中）
こんにちは、田中さん！

3. クエリパラメータの構造を理解する

3. クエリパラメータの構造を理解する

クエリパラメータの仕組みを視覚的に理解することは、間違いの少ないプログラムを書くために重要です。URLは大きく分けて「スキーム」「ホスト名」「ポート番号」「パス」「クエリパラメータ」という要素で構成されています。

上記の図のように、「?」から後ろの部分がクエリパラメータです。Micronautはこの「key（キー）」の部分をJavaの変数名として探し出し、「value（値）」をその中身として届けてくれます。この流れが自動化されているおかげで、開発者はデータの取り出し処理という退屈な作業から解放され、本当に作りたい機能の開発に専念できるのです。

4. 数値や真偽値への自動型変換

4. 数値や真偽値への自動型変換

クエリパラメータとして送られてくるデータは、URL上ではすべて「文字列」として扱われます。しかし、プログラムの中では「年齢を数値として扱いたい」とか「フラグを真偽値として扱いたい」ということがよくあります。Micronautは、この「型の変換」も自動で行ってくれます。

メソッドの引数を int や boolean にしておけば、Micronautが自動的に適切な型に変換してくれます。もし数字を期待しているところに文字が送られてきた場合は、Micronautが適切にエラーとして処理してくれるため、自分で変換の失敗をチェックするコードを書く必要もありません。これはパソコン操作に慣れていない方が間違った入力をした際にも、システムが安全に反応するために役立ちます。

package com.example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/search")
public class SearchController {

    @Get("/filter")
    public String filter(int age, boolean active) {
        // ageは数値として、activeは真偽値として受け取れます
        String status = active ? "有効" : "無効";
        return "年齢: " + age + "、ステータス: " + status + " で絞り込みます。";
    }
}

（アクセス例：http://localhost:8080/search/filter?age=25&active=true）
年齢: 25、ステータス: 有効 で絞り込みます。

5. パラメータが送られなかった時の対処法

5. パラメータが送られなかった時の対処法

Webアプリケーションを運用していると、ユーザーが常にすべてのパラメータを送ってくれるとは限りません。パラメータが足りない時にプログラムがエラーで止まってしまうのを防ぐために、Micronautではいくつかの対策が用意されています。

一つは、Javaの Optional クラスを使う方法です。これを使うと「値があるかもしれないし、ないかもしれない」という状態を安全に表現できます。また、アノテーション @Nullable を付けることで、値がなくてもエラーにせずに「null」として受け取ることも可能です。これにより、検索ワードが空の時は全件表示する、といった柔軟な対応が簡単になります。

6. @QueryValueを使って名前を指定する

6. @QueryValueを使って名前を指定する

基本的には引数名とパラメータ名を合わせれば良いのですが、事情があってJavaの変数名とは違う名前のパラメータを受け取りたい場合もあります。そんな時に使うのが @QueryValue アノテーションです。これを使えば、URL上の名前とJavaプログラム内での名前を自由に紐付けることができます。

例えば、URLでは「q」という短い名前を使いたいけれど、Javaの中では「searchKeyword」という分かりやすい名前を使いたい時に便利です。また、このアノテーションの中で defaultValue を設定すれば、パラメータが送られてこなかった時の「初期値」を決めることもできます。非常に強力な機能なので、ぜひ覚えておきましょう。

package com.example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.QueryValue;

@Controller("/products")
public class ProductController {

    @Get("/list")
    public String list(
        @QueryValue(value = "category", defaultValue = "all") String cat
    ) {
        // URLに category がない場合は "all" が代入されます
        return "カテゴリ「" + cat + "」の商品一覧を表示します。";
    }
}

（アクセス例：http://localhost:8080/products/list）
カテゴリ「all」の商品一覧を表示します。

7. 複数の値を持つパラメータの受け取り方

7. 複数の値を持つパラメータの受け取り方

チェックボックスの選択結果のように、一つの名前で複数の値を送りたい場合があります（例：?tag=java&tag=kotlin）。このような場合、Micronautでは引数を List 形式にすることで、すべての値をまとめて受け取ることができます。

受け取ったリストはJavaの標準的な方法で繰り返し処理などができるため、複雑な絞り込み機能も楽に実装できます。パソコン初心者の方向けに例えると、買い物リストで「りんご、バナナ、みかん」を一気に渡されるようなものです。Micronautはこれらをバラバラにせず、一つのカゴにまとめて届けてくれるのです。

8. クエリパラメータとパスパラメータの使い分け

8. クエリパラメータとパスパラメータの使い分け

ルーティングの基本として、「パスパラメータ（/users/1）」と「クエリパラメータ（/users?id=1）」のどちらを使うべきか迷うことがあります。一般的なルールとしては、その情報が「リソースを特定するもの（住所の一部）」ならパスパラメータを、「操作を制御するもの（絞り込みや並び替え）」ならクエリパラメータを使います。

例えば、「特定のユーザーの詳細ページ」はパスパラメータが適していますが、「ユーザー一覧の中でのページ番号」や「検索ワード」はクエリパラメータが適しています。この使い分けができるようになると、WebAPIの設計が格段にプロフェッショナルらしくなります。Micronautはどちらも同じくらい簡単に扱えるので、用途に合わせて最適な方を選びましょう。

9. POJOを使ってパラメータをひとまとめにする

9. POJOを使ってパラメータをひとまとめにする

送りたいパラメータの数が5個、10個と増えてくると、メソッドの引数が非常に長くなってしまいます。これではコードが読みづらくなってしまいます。そんな時は、複数のパラメータを一つの「クラス（POJO）」にまとめて受け取ることができます。

Javaのクラスに「名前」や「年齢」などのフィールドを用意しておき、引数にそのクラスを指定するだけで、Micronautがバラバラのクエリパラメータを一つのオブジェクトに組み立ててくれます。これを「データバインディング」と呼びます。この手法を使えば、大規模な検索フォームのような複雑なデータも、驚くほどスッキリと扱うことができるようになります。

package com.example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.core.annotation.Introspected;

@Introspected // Micronautがクラスを扱えるようにする印
class SearchQuery {
    private String text;
    private int page;
    
    // getterとsetterが必要（またはrecord型を使用）
    public String getText() { return text; }
    public void setText(String text) { this.text = text; }
    public int getPage() { return page; }
    public void setPage(int page) { this.page = page; }
}

@Controller("/advanced")
public class AdvancedController {

    @Get("/search")
    public String search(SearchQuery query) {
        return "キーワード: " + query.getText() + ", ページ: " + query.getPage();
    }
}

（アクセス例：http://localhost:8080/advanced/search?text=micronaut&page=2）
キーワード: micronaut, ページ: 2

10. クエリパラメータの安全性とセキュリティ

10. クエリパラメータの安全性とセキュリティ

最後に、セキュリティについて少し触れておきます。クエリパラメータはURLの一部なので、ブラウザの履歴に残ったり、サーバーのログに記録されたりします。そのため、パスワードや個人情報、クレジットカード番号などの機密情報をクエリパラメータで送ることは絶対に避けてください。

機密情報を扱う場合は、クエリパラメータ（GETリクエスト）ではなく、リクエストボディ（POSTリクエスト）を使うのがWeb開発の常識です。Micronautで安全なアプリを作るためには、どの情報をURLに乗せ、どの情報を隠して送るべきかを正しく判断する力も重要になります。正しい知識を持って、便利で安全なWebAPI開発を楽しんでくださいね！