Spring FrameworkでのUriComponentsBuilderの使い方を初心者向けに解説！
山崎講師
こんにちは。ゆうせいです。
Webアプリケーションを開発していると、URLを動的に組み立てたい場面ってよく出てきますよね？
たとえば、「検索結果ページにページ番号とカテゴリをつけたURLを作りたい」とか、「ユーザーIDを含むAPIのURLを生成したい」といったケースです。
そんなときに活躍するのが、Spring Frameworkが提供している便利なクラス、UriComponentsBuilder（ウリ・コンポーネンツ・ビルダー）です！
今回はこのUriComponentsBuilderについて、初心者の方にもわかりやすく、サンプルコードを交えながら解説していきます。
UriComponentsBuilderって何？
URLを安全かつ柔軟に組み立てるためのツール
UriComponentsBuilderは、Spring Frameworkに含まれるユーティリティクラスで、主にURLの構築（生成）に使用します。
どんなメリットがあるの？
| メリット | 説明 |
|---|---|
| エンコードを自動でやってくれる | 文字列をURLにそのまま含めるとバグのもとですが、UriComponentsBuilderなら自動でエスケープしてくれます |
| 動的なURL構築が簡単 | クエリパラメータやパス変数を自由自在に組み立てられます |
| 読みやすい | チェーンメソッドで構築するので、コードがスッキリします |
例えるなら、「URL構築のレゴブロック」みたいなものです。小さなパーツ（パス、クエリなど）を組み合わせて、安全にURLを作れます！
基本の使い方
パターン①：クエリパラメータを含むURLを構築する
String url = UriComponentsBuilder.fromHttpUrl("https://example.com/search")
.queryParam("category", "books")
.queryParam("page", 2)
.build()
.toUriString();
System.out.println(url); // https://example.com/search?category=books&page=2
解説：
.fromHttpUrl(...)：ベースのURLを指定します.queryParam(...)：クエリパラメータを追加（複数可）.build()：URIコンポーネントを構築.toUriString()：完成したURLを文字列として取得
パターン②：パス変数を使った動的なURL構築
String url = UriComponentsBuilder.fromPath("/user/{id}/profile")
.buildAndExpand(12345)
.toUriString();
System.out.println(url); // /user/12345/profile
解説：
{id}のような「テンプレート変数」をbuildAndExpand(...)で置き換えます。- 実際の値をあとから埋め込むことで、動的なURLが簡単に作れます。
数式っぽく表すと？
URLを組み立てる操作を簡単な記号で表すと、次のようになります：
- ベースURL：
U - パス追加：
P1,P2... - クエリパラメータ追加：
Q1,Q2...
記号での表現：
URL = U + P1 + P2 + ... + ?(Q1 & Q2 & ...)
日本語での言い換え：
URL = ベースURL ＋ パス成分の連結 ＋ クエリパラメータの連結
Spring MVCのControllerと組み合わせる例
@GetMapping("/redirect")
public String redirectToUser() {
String redirectUrl = UriComponentsBuilder.fromPath("/user/{id}")
.buildAndExpand(42)
.toUriString();
return "redirect:" + redirectUrl;
}
これは、「/redirect」にアクセスしたら、「/user/42」にリダイレクトするという例です。
よくあるミスと注意点
| ミス | 解説 |
|---|---|
toUriString()し忘れ | 組み立てただけではStringにならないので、必ずtoUriString()を使ってください |
queryParam()の値にnullが入る | クエリに"null"という文字列が入ってしまうので、事前にチェックしましょう |
fromHttpUrl()とfromPath()の混同 | fromHttpUrl()は完全なURL、fromPath()は相対パスです |
まとめ
UriComponentsBuilderはSpringでのURL生成に最適なユーティリティ。- クエリパラメータ、パス変数、テンプレート展開など、URLを「組み立てる」作業に特化しています。
- 実際のプロジェクトでは、REST APIのリンク生成、リダイレクト、外部サービスとの連携URLの生成など、幅広い用途があります。
次に学ぶべきこと
- Spring MVCと連携した
ServletUriComponentsBuilderの使い方 - RESTful APIとHATEOAS（ヘイトオース）でのリンク構築
UriComponentsBuilderのencode()メソッドとエンコードの違い- テストコードでのURL生成と検証
「URLの生成って、もっと泥臭い処理だと思っていました！」
そんな風に感じた方も多いのではないでしょうか？
でもUriComponentsBuilderを使えば、キレイで安全なURL構築が簡単にできちゃうんです。
ぜひ、あなたのプロジェクトでも使ってみてくださいね！
セイ・コンサルティング・グループの新人エンジニア研修のメニューへのリンク
投稿者プロフィール
