Javaの@RestControllerアノテーションの使い方を完全ガイド！初心者でもわかるREST APIの基礎
生徒
「Springで@RestControllerってよく見かけますが、これって何をするために使うんですか？」
先生
「@RestControllerは、SpringフレームワークでREST APIを作成するためのアノテーションです。これを使うと、ブラウザやクライアントアプリケーションにデータを返すエンドポイントを簡単に作成できます。」
生徒
「じゃあ、普通の@Controllerとは何が違うんですか？」
先生
「良い質問ですね。@Controllerは通常のWebページ（HTML）を返すために使いますが、@RestControllerはJSONやXMLのようなデータを返すために使います。では、具体的な使い方を見ていきましょう！」
1. @RestControllerアノテーションとは？
@RestControllerは、SpringフレームワークでAPIを構築するために使用されるアノテーションです。従来の@Controllerとは異なり、@RestControllerを使用すると、メソッドから返されるオブジェクトが自動的にJSON形式にシリアライズされてHTTPレスポンスとして返されます。
これにより、Webページではなくデータをクライアントに返すためのAPIを簡単に作成でき、特にモバイルアプリケーションやフロントエンドJavaScriptフレームワークとの連携に便利です。
2. @RestControllerの基本的な使い方
それでは、@RestControllerを使って簡単なREST APIを作成してみましょう。以下の例では、"Hello, World!"というメッセージを返すエンドポイントを作成します。
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/hello")
public String sayHello() {
return "Hello, World!";
}
}
実行結果
"Hello, World!"
このように、@RestControllerを使うと、@GetMappingアノテーションでHTTP GETリクエストに対応するメソッドを簡単に定義できます。
将来を見据えて、＋αのスキルを身につけたい方へ
JavaやLinuxを学んでいても、「このままで市場価値は上がるのか」 「キャリアの選択肢を広げたい」と感じる方は少なくありません。
AIを学ぶならアイデミープレミアム
3. JSON形式のデータを返す方法
次に、JSON形式のデータを返すAPIを作成してみましょう。@RestControllerでは、メソッドが返すオブジェクトが自動的にJSONに変換されます。
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
@GetMapping("/user")
public User getUser() {
return new User("Alice", 25);
}
}
class User {
private String name;
private int age;
public User(String name, int age) {
this.name = name;
this.age = age;
}
public String getName() { return name; }
public int getAge() { return age; }
}
実行結果
{
"name": "Alice",
"age": 25
}
上記の例では、UserオブジェクトがJSON形式にシリアライズされて返されます。これにより、モバイルアプリケーションやフロントエンドフレームワークがデータを簡単に利用できます。
4. @RestControllerの活用例：CRUD操作
REST APIでは、基本的なCRUD（Create, Read, Update, Delete）操作を実装することがよくあります。以下は、簡単なCRUD操作を実装したサンプルです。
import org.springframework.web.bind.annotation.*;
import java.util.*;
@RestController
@RequestMapping("/products")
public class ProductController {
private List<String> products = new ArrayList<>(Arrays.asList("Apple", "Banana", "Orange"));
@GetMapping
public List<String> getProducts() {
return products;
}
@PostMapping
public void addProduct(@RequestBody String product) {
products.add(product);
}
@DeleteMapping("/{index}")
public void deleteProduct(@PathVariable int index) {
products.remove(index);
}
}
実行結果
GET /products
[ "Apple", "Banana", "Orange" ]
POST /products (Body: "Grapes")
[ "Apple", "Banana", "Orange", "Grapes" ]
DELETE /products/1
[ "Apple", "Orange", "Grapes" ]
このように、@RestControllerを使えば、データの取得や追加、削除といった操作を簡単に実装できます。@RequestBodyや@PathVariableを使うことで、クライアントからのリクエスト内容を処理できます。
5. @RestControllerの注意点とベストプラクティス
@RestControllerを使用する際には、以下の点に注意することで、より安全で効率的なAPIを作成できます。
- セキュリティ対策として、入力データのバリデーションを行う。
- 例外処理を
@ControllerAdviceで一元管理する。 - 適切なHTTPステータスコード（
200 OK、404 Not Foundなど）を返す。 - 大量のデータを返す場合は、
PaginationやLimitを利用する。
6. @RestControllerで@RequestParamと@PathVariableを組み合わせてパラメータを処理する
@RestControllerでは、URLパラメータやクエリパラメータを利用して、クライアントから送られた値を柔軟に扱うことができます。特に、ユーザーIDや検索キーワードなどをAPIに渡す場合、@RequestParamと@PathVariableを使い分けることで、REST APIとして意味のある設計が可能になります。
例えば、/api/user?id=10 のようにクエリ形式でパラメータを取得する場合は@RequestParam、/api/user/10 のようにURLパスそのものに意味を持たせたい場合は@PathVariableを使用します。
パラメータの扱いを適切に設計できると、フロントエンドやモバイルアプリケーションとの連携がよりスムーズになり、REST APIとしての拡張性や可読性も向上します。
7. @RestControllerとサービス層（@Service）を分けて設計する理由
@RestControllerを使ってAPIを設計する際、ビジネスロジックをすべてコントローラー内に記述してしまうと、コードが肥大化し保守性が低下します。そこで、処理の責務に応じてサービス層（@Service）を用意し、@RestControllerはリクエスト受付とレスポンス返却に専念させることが推奨されます。
このように役割を分離することで、APIの可読性が高まり、変更に強い設計となります。また、複数のAPIで同じ処理を共有する場合でも、サービス層に記述しておくことで重複を防ぎ、再利用性が向上します。
適切な役割分担を行うことで、Springアプリケーション全体の構造が整理され、REST APIの品質向上にもつながります。
8. @RestControllerで例外処理を行う際のエラーハンドリング設計
REST APIでは、予期せぬエラーや入力データの不備など、さまざまな例外が発生する可能性があります。@RestControllerで例外が発生した場合、適切なエラーレスポンスを返すことで、クライアント側での処理が行いやすくなります。
例えばデータが見つからない場合には404 Not Found、入力エラーが発生した場合には400 Bad RequestといったHTTPステータスコードを返すことで、問題を明確に伝えることができます。
また、例外処理を@ControllerAdviceとしてまとめることで、アプリ全体のエラーハンドリングを統一でき、REST APIとしての信頼性と保守性を高めることができます。
まとめ
今回の記事では、Springフレームワークの@RestControllerアノテーションについて詳しく解説しました。@RestControllerは、REST APIを簡単に構築できる便利なアノテーションであり、クライアントに対してデータをJSON形式で返すために使用されます。@GetMapping、@PostMapping、@DeleteMappingなどのメソッドと組み合わせることで、様々なHTTPリクエストに対応したエンドポイントを素早く作成できましたね。
特に、JSONデータのシリアライズ機能やCRUD操作の実装は、@RestControllerの大きな強みです。これにより、バックエンドAPIの開発が効率的になるだけでなく、モバイルアプリやフロントエンドのJavaScriptフレームワークとの連携もスムーズになります。また、セキュリティ対策や例外処理のベストプラクティスを活用することで、より堅牢なAPIを構築できることも学びました。
実際の開発現場では、複数のAPIエンドポイントを管理したり、異なるデータフォーマットに対応したりすることが求められます。そうした場合にも、@RestControllerとその他のSpringアノテーションを組み合わせて柔軟に対応できるようになります。これを機に、実際のプロジェクトでも積極的にSpringの機能を活用してみてください。
さらに理解を深めるためのサンプルコード
最後に、今回の学びを活かした応用例として、異なるHTTPステータスコードを返すAPIのサンプルコードを紹介します。
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/items")
public class ItemController {
private Map<Integer, String> items = new HashMap<>();
@GetMapping("/{id}")
public ResponseEntity<String> getItem(@PathVariable int id) {
if (items.containsKey(id)) {
return new ResponseEntity<>(items.get(id), HttpStatus.OK);
} else {
return new ResponseEntity<>("Item not found", HttpStatus.NOT_FOUND);
}
}
@PostMapping
public ResponseEntity<String> addItem(@RequestParam String name) {
int id = items.size() + 1;
items.put(id, name);
return new ResponseEntity<>("Item added with ID: " + id, HttpStatus.CREATED);
}
@DeleteMapping("/{id}")
public ResponseEntity<String> deleteItem(@PathVariable int id) {
if (items.remove(id) != null) {
return new ResponseEntity<>("Item deleted", HttpStatus.OK);
} else {
return new ResponseEntity<>("Item not found", HttpStatus.NOT_FOUND);
}
}
}
実行結果
GET /items/1
"Item not found" （ステータス: 404 Not Found）
POST /items?name=Book
"Item added with ID: 1" （ステータス: 201 Created）
DELETE /items/1
"Item deleted" （ステータス: 200 OK）
このように、ResponseEntityを使うことで、柔軟にHTTPレスポンスを制御できます。APIのユーザビリティを向上させるためには、適切なHTTPステータスコードを返すことが重要です。
生徒
「@RestControllerについて、だいぶ理解できました！データを簡単にJSONで返せるのが便利ですね。」
先生
「そうですね。特にフロントエンドとの連携が増えている今、@RestControllerの使い方を覚えることは非常に重要です。」
生徒
「CRUD操作のAPIも、思ったより簡単に作れるんですね。@RequestBodyや@PathVariableの使い方もわかりやすかったです。」
先生
「今後は@ControllerAdviceを使った例外処理や、セキュリティ設定にも挑戦してみましょう。それらをマスターすれば、より強力なAPIが作れるようになりますよ。」
生徒
「わかりました！今日は本当に勉強になりました。ありがとうございました！」
この記事を読んだ人からの質問
