@RestController
@RestController() は、メソッドが HTTP リクエストに応答するクラス、つまり REST コントローラーを示します。クラスは Bean であり、マッピングアノテーションを持つすべてのメソッドがエンドポイントになります。
使う理由
Web API の出発点です。クラスは @Component と同じく Bean なので、依存はコンストラクターから受け取ります。スターターは各リクエストを、マッピング(@GetMapping、@PostMapping など)がそのメソッドとパスに一致するメソッドに送り、リクエストから引数を埋め、戻り値をボディとして書きます。オブジェクトなら JSON、String ならテキストです。
HTTP に応答するすべてのクラスに使ってください。ビジネスロジックはサービスに置き、コントローラーには HTTP とそれらのサービスの間の変換をさせます。
例
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 は、自身のステータスを持たないすべてのメソッドのステータスを設定します。
// このコントローラーのすべてのメソッドは 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。1 つのメソッドに 2 つのマッピングアノテーションがあると起動が止まります。@ExceptionHandler を持つメソッドは、このコントローラーのエラーに応答します。
- 素の
@Controller()も同じようにマップされます。 このサーバーには HTML のビューがないため、戻り値は常にボディです。@RestControllerは意図を示すものなので、どちらを選んでもかまいません。 - クラスに付けた
@RequestMappingは、すべてのメソッドのパスのプレフィックスと、そのproduces、consumes、headersを与えます(@RequestMapping を参照)。 - クラスに付けたアノテーションはすべてのメソッドに適用され、メソッド自身のものが優先されます:
@ResponseStatus、@CrossOrigin(メソッドのものとマージされます)。 - コントローラーはシングルトン Bean です。 1 つのインスタンスが、
awaitをまたいで並行にすべてのリクエストに応答します。そのため、リクエストのデータはフィールドではなく引数とローカル変数に置いてください。 - AOP が適用されます。 メソッドはコンテナが保持する Bean に対して呼ばれるため、コントローラーへのアドバイス(
@Cacheable、メソッドバリデーション、セキュリティスターターの@PreAuthorize)が実行されます。 - ジェネレーターがクラスを見られる必要があります。 クラスはスキャンされるコード(
lib/とmainのディレクトリ)の中にある必要があり、変更した後にはbuild_runnerを実行する必要があります。ジェネレーターはマップされた各メソッド(引数、そのアノテーション、結果の型)を記録し、スターターは起動時にその記録からルートを組み立てます。 - メソッドが受け取り、返すクラスは JSON 用に記述されます(同じパッケージにある場合)。別のパッケージのクラスには、それ自身のイントロスペクション(そのパッケージでの
@Introspected()、JSON を参照)が必要です。 - パス変数に対応する引数がないなど、誤りがあると起動が止まります(起動時のチェック を参照)。
Spring (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)は、その定義がジェネレーターの書き出すメソッドの記述を持つ場合にだけマップされます。