
# @RestController

`@RestController()` は、メソッドが HTTP リクエストに応答するクラス、つまり REST コントローラーを示します。クラスは Bean であり、マッピングアノテーションを持つすべてのメソッドがエンドポイントになります。

## 使う理由

Web API の出発点です。クラスは [@Component](../../spring-core-dart/beans/component.md) と同じく Bean なので、依存はコンストラクターから受け取ります。スターターは各リクエストを、マッピング（`@GetMapping`、`@PostMapping` など）がそのメソッドとパスに一致するメソッドに送り、リクエストから引数を埋め、戻り値をボディとして書きます。オブジェクトなら JSON、`String` ならテキストです。

HTTP に応答するすべてのクラスに使ってください。ビジネスロジックはサービスに置き、コントローラーには HTTP とそれらのサービスの間の変換をさせます。

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

@Service()
class BookService {
  Future<Book> find(String isbn) async => Book(isbn: isbn, title: 'Dune');
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  // GET /api/books/978-0 は本を JSON で返す。
  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  // マッピングのない普通のメソッドはエンドポイントではない。
  String describe(Book book) => '${book.title} (${book.isbn})';
}

// 名前で Bean を探すコードのための、明示的な Bean 名。
@RestController('adminBooks')
@RequestMapping('/admin/books')
class AdminBookController {
  @GetMapping('/count')
  int count() => 1;
}
```

クラスに付けた `@ResponseStatus` は、自身のステータスを持たないすべてのメソッドのステータスを設定します。

```dart
// このコントローラーのすべてのメソッドは 202 Accepted で応答する。
@RestController()
@RequestMapping('/api/jobs')
@ResponseStatus(HttpStatus.accepted)
class JobController {
  @PostMapping()
  void start() {}

  // メソッド自身のアノテーションが優先される。
  @GetMapping('/health')
  @ResponseStatus(HttpStatus.ok)
  String health() => 'UP';
}
```

## パラメーター

| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `name`（位置引数） | `String?` | `null` | Bean 名。`null` ならクラス名の lowerCamelCase（`bookController`）。 |

## ルール

- **どのメソッドがエンドポイントか。** マッピングアノテーションを 1 つ持つメソッドがマップされます: [@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@PatchMapping、@DeleteMapping](request-mapping.md)。1 つのメソッドに 2 つのマッピングアノテーションがあると起動が止まります。[@ExceptionHandler](../errors/exception-handler.md) を持つメソッドは、このコントローラーのエラーに応答します。
- **素の `@Controller()` も同じようにマップされます。** このサーバーには HTML のビューがないため、戻り値は常にボディです。`@RestController` は意図を示すものなので、どちらを選んでもかまいません。
- **クラスに付けた `@RequestMapping`** は、すべてのメソッドのパスのプレフィックスと、その `produces`、`consumes`、`headers` を与えます（[@RequestMapping](request-mapping.md) を参照）。
- **クラスに付けたアノテーションはすべてのメソッドに適用され**、メソッド自身のものが優先されます: `@ResponseStatus`、[`@CrossOrigin`](../cors.md)（メソッドのものとマージされます）。
- **コントローラーはシングルトン Bean です。** 1 つのインスタンスが、`await` をまたいで並行にすべてのリクエストに応答します。そのため、リクエストのデータはフィールドではなく引数とローカル変数に置いてください。
- **AOP が適用されます。** メソッドはコンテナが保持する Bean に対して呼ばれるため、コントローラーへのアドバイス（`@Cacheable`、メソッドバリデーション、セキュリティスターターの `@PreAuthorize`）が実行されます。
- **ジェネレーターがクラスを見られる必要があります。** クラスはスキャンされるコード（`lib/` と `main` のディレクトリ）の中にある必要があり、変更した後には `build_runner` を実行する必要があります。ジェネレーターはマップされた各メソッド（引数、そのアノテーション、結果の型）を記録し、スターターは起動時にその記録からルートを組み立てます。
- **メソッドが受け取り、返すクラスは JSON 用に記述されます**（同じパッケージにある場合）。別のパッケージのクラスには、それ自身のイントロスペクション（そのパッケージでの `@Introspected()`、[JSON](../../spring-core-dart/json/index.md) を参照）が必要です。
- パス変数に対応する引数がないなど、**誤りがあると起動が止まります**（[起動時のチェック](startup-checks.md) を参照）。

## Spring (Java) との対応

```java
@RestController
@RequestMapping("/api/books")
class BookController {
  private final BookService books;

  BookController(BookService books) { this.books = books; }

  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { return books.find(isbn); }
}
```

重要な違い:

- Spring では、`@Controller` はメソッドに `@ResponseBody` がない限りビュー名を返します。ここにはビューがないため、`@Controller` と `@RestController` は同じように動作します。
- Spring がメタアノテーションを使うところで、Dart では `@RestController` は `Controller` のサブクラスです。
- ジェネレーターはビルド時にメソッドを見つけます。実行時に追加されたコントローラー（コードで登録された Bean）は、その定義がジェネレーターの書き出すメソッドの記述を持つ場合にだけマップされます。

## 関連項目

- [@RequestMapping と @GetMapping](request-mapping.md)
- [戻り値](results.md)
- [@ExceptionHandler](../errors/exception-handler.md)
- [spring_core_dart の @Controller](../../spring-core-dart/beans/controller.md)
- [@ComponentScan](../../spring-core-dart/beans/component-scan.md)
