Javaの@PathVariableアノテーションの使い方を徹底解説！初心者でもわかるパスパラメータの基本と応用
生徒
「Spring Frameworkで@PathVariableというのを見たんですが、これってどうやって使うんですか？」
先生
「いい質問だね！@PathVariableは、URLパスから値を取得するために使うアノテーションだよ。例えば、URLの一部にIDを入れて、そのIDを取得したいときに便利なんだ。」
生徒
「それってどうやって実装するんですか？サンプルコードが見たいです！」
先生
「じゃあ、基本的な使い方を一緒に見てみよう！」
1. @PathVariableアノテーションとは？
@PathVariableは、Spring MVCでURLのパスから変数を取得するためのアノテーションです。例えば、REST APIでユーザーIDや商品IDなど、動的に変わる部分をURLから取得したいときに使います。以下の例を見てください。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
@RequestMapping("/user/{id}")
public String getUserById(@PathVariable String id) {
return "User ID: " + id;
}
}
上記の例では、/user/123のようなURLにアクセスすると、「User ID: 123」というレスポンスが返されます。{id}の部分が@PathVariableで取得できる部分です。
2. @PathVariableの基本的な使い方
まずは、簡単な例から始めましょう。以下のコードでは、URLからユーザー名を取得し、それを利用してメッセージを返しています。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GreetingController {
@RequestMapping("/greet/{name}")
public String greetUser(@PathVariable String name) {
return "Hello, " + name + "!";
}
}
実行結果例
GET /greet/John
=> Hello, John!
このように、@PathVariableを使うことで、URLのパスに含まれるデータを簡単に取得できます。
3. データ型の変換と複数の@PathVariable
@PathVariableは、様々なデータ型をサポートしています。例えば、数値型のパラメータを使いたい場合も簡単に対応できます。また、複数のパス変数を扱うこともできます。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class OrderController {
@RequestMapping("/order/{orderId}/item/{itemId}")
public String getOrderItem(@PathVariable int orderId, @PathVariable int itemId) {
return "Order ID: " + orderId + ", Item ID: " + itemId;
}
}
実行結果例
GET /order/101/item/202
=> Order ID: 101, Item ID: 202
複数の@PathVariableを使うことで、より複雑なURL構成にも対応可能です。
4. Optionalな@PathVariableの使い方
パスパラメータを必須ではなく、オプションとして扱いたい場合もあります。Springではrequired = false属性を利用して、それを実現できます。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ProductController {
@RequestMapping("/product/{productId}")
public String getProduct(@PathVariable(required = false) String productId) {
if (productId == null) {
return "No Product ID provided";
}
return "Product ID: " + productId;
}
}
この設定を使うと、/productのようなURLにアクセスした際でも、エラーにならずに処理が続行されます。
5. @PathVariableと正規表現の活用
@PathVariableでは正規表現を使って、パスパラメータのフォーマットを制限することもできます。例えば、IDが数字のみの場合に限定したいときに役立ちます。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ValidationController {
@RequestMapping("/validate/{code:[a-zA-Z]+}")
public String validateCode(@PathVariable String code) {
return "Validated Code: " + code;
}
}
実行結果例
GET /validate/ABC123
=> 404 Not Found
GET /validate/ABC
=> Validated Code: ABC
正規表現を活用することで、より精密なURLパラメータの制御が可能です。
6. パス変数名の明示指定（name/value属性）と命名のベストプラクティス
URLテンプレートの変数名とメソッド引数名が一致しない場合は、@PathVariable("...")で明示します。複数のパス変数があるときも、可読性のために明示指定が推奨です（SEO観点でも「@PathVariable 使い方」「パスパラメータ 命名」のキーワードにマッチ）。
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class ProfileController {
// URL: /users/42/profile/ja
@GetMapping("/{userId}/profile/{lang}")
public String profile(
@PathVariable("userId") Long id,
@PathVariable("lang") String localeCode) {
return "user=" + id + ", lang=" + localeCode;
}
// 変数名が長い場合も、URIは短く・引数は意味的に
// URL: /users/42/orders/777
@GetMapping("/{uid}/orders/{oid}")
public String orderDetail(
@PathVariable("uid") Long userId,
@PathVariable("oid") Long orderId) {
return "userId=" + userId + ", orderId=" + orderId;
}
}
リソース名は複数形（/users、/orders）にし、URLは短く・引数名はドメインに沿って意味的にします。
7. LocalDate・UUID・Enumなどの型を@PathVariableで受け取る（型変換の応用）
@PathVariableはプリミティブ以外にも、LocalDateやUUID、enumなど多様な型を自動変換できます。日付には@DateTimeFormatを併用しましょう（キーワード：@PathVariable 型変換、LocalDate UUID Enum）。
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.web.bind.annotation.*;
import java.time.LocalDate;
import java.util.UUID;
@RestController
@RequestMapping("/analytics")
public class AnalyticsController {
// URL: /analytics/daily/2025-08-01
@GetMapping("/daily/{date}")
public String daily(
@PathVariable
@DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date) {
return "Daily report for " + date;
}
// URL: /analytics/session/123e4567-e89b-12d3-a456-426614174000
@GetMapping("/session/{token}")
public String session(@PathVariable UUID token) {
return "Session token=" + token;
}
// Enumは文字列マッチ（大文字小文字は定義に合わせる）
enum State { OPEN, CLOSED, PENDING }
// URL: /analytics/state/OPEN
@GetMapping("/state/{state}")
public String state(@PathVariable State state) {
return "State=" + state.name();
}
}
変換に失敗した場合は400系エラーになります。想定フォーマットを明示し、必要に応じてハンドリングを用意しましょう。
8. Optionalな@PathVariableの正しい実装（複数パターン＆Optional）
パスパラメータを任意にする場合は、複数のURLパターンを同一メソッドに割り当てて@PathVariable(required = false)またはOptional<T>で受け取るのが実用的です（キーワード：Optional @PathVariable、任意 パスパラメータ）。
import org.springframework.web.bind.annotation.*;
import java.util.Optional;
@RestController
public class ProductQueryController {
// /products と /products/{productId} の両方を許可
@GetMapping({"/products", "/products/{productId}"})
public String getProduct(
@PathVariable(required = false) String productId) {
return (productId == null)
? "All products"
: "Product ID: " + productId;
}
// Optional を使うバリエーション
@GetMapping({"/catalog", "/catalog/{category}"})
public String catalog(@PathVariable Optional<String> category) {
return category
.map(c -> "Category: " + c)
.orElse("All categories");
}
}
URIテンプレート側に可否を定義するのがポイントです。単一の/path/{var}だけでは/pathはマッチしません。
まとめ
今回は、JavaのSpring Frameworkにおける@PathVariableアノテーションについて詳しく解説しました。このアノテーションを使うことで、URLパスの一部をパラメータとして取得し、効率的にAPIを設計できます。例えば、/user/{id}のように、ユーザーIDや商品IDをURLパスから取得するのが一般的な使い方です。Spring Bootを用いたWebアプリケーション開発では、この@PathVariableの活用が欠かせません。
基本的な使い方から、データ型の変換、複数の@PathVariableの使用方法、オプションパラメータ、さらに正規表現を使ったURLパラメータの制約まで、幅広い使い方を学びました。これらの知識を使えば、より柔軟で強力なAPIを設計できるようになります。
具体的な実装方法や、Springの他のアノテーション（例えば、@RequestParamや@RequestBody）との違いを理解することで、開発スキルの向上が期待できます。また、@PathVariableはRESTful APIの設計にも非常に役立つため、今後の開発に活用していきましょう。
実践サンプル：全機能の総復習
ここまでの内容を踏まえた総合的なサンプルプログラムを用意しました。複数の@PathVariableと正規表現を組み合わせた応用例です。
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class AdvancedController {
@RequestMapping("/api/{version:v[0-9]+}/users/{userId:[0-9]+}")
public String getUserByVersion(@PathVariable String version, @PathVariable int userId) {
return "API Version: " + version + ", User ID: " + userId;
}
}
実行結果例
GET /api/v1/users/123
=> API Version: v1, User ID: 123
GET /api/v2/users/abc
=> 404 Not Found
このサンプルでは、APIのバージョン管理を{version:v[0-9]+}という形で、ユーザーIDは数値のみを許可する{userId:[0-9]+}という正規表現で制御しています。これにより、誤った形式のURLリクエストを防ぎ、APIの信頼性を向上させることができます。
生徒
「今日の授業で学んだ@PathVariableアノテーション、すごく便利ですね！特にURLから動的に値を取得できるのが面白かったです。」
先生
「そうだね。これを使うと、APIの設計が柔軟になるんだ。例えば、ユーザーIDや商品のカテゴリなど、URLパスに組み込んだ情報を簡単に利用できるんだよ。」
生徒
「複数の@PathVariableも同時に使えるから、いろんなケースに対応できそうですね。オプションにしたり、正規表現で制御するのも便利です。」
先生
「その通り！データのバリデーションやAPIバージョン管理にも応用できるから、実務でもよく使われるテクニックだよ。これからのプロジェクトでぜひ活用してみてね。」
生徒
「はい！次回は@RequestParamについても教えてください。」
先生
「もちろん！次回は@RequestParamを使ったクエリパラメータの処理について詳しく学んでいこう！」
この記事を読んだ人からの質問
