
# WebMvcConfigurer

`WebMvcConfigurer` を mixin した Bean は、コントローラーに機能を追加します。インターセプター、パスごとの CORS ルール、独自の型のパラメーターのためのリゾルバー、静的リソースの追加のマッピングなどです。必要なメソッドだけをオーバーライドしてください。それ以外は何もしません。

## 使う理由

スターターは、インターセプターなし、グローバルな CORS ルールなし、自身の引数リゾルバーだけでコントローラーをセットアップします。どのアプリケーションにも独自の追加がいくつか必要で、それらはすべてのコントローラーで繰り返すのではなく、一か所にまとめるべきです。

- **インターセプター** は各コントローラーメソッドの前後で実行され、それがどのメソッドかを知っています。
- **CORS マッピング** は多くのパスにまとめてルールを与えます。
- **引数リゾルバー** を使うと、メソッドは自分でヘッダーを読む代わりに `Tenant tenant` や `User user` のパラメーターを宣言できます。
- **リソースハンドラー** は、より多くのパターンで、独自のキャッシュ設定とともにファイルを提供します。

## 例

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

const log = SpringLog('app.web');

@Configuration()
class WebConfig with WebMvcConfigurer {
  @override
  void addInterceptors(InterceptorRegistry registry) {
    registry
        .addInterceptor(TimingInterceptor())
        .addPathPatterns(['/api/**'])
        .excludePathPatterns(['/api/health']);
    registry.addInterceptor(AdminOnlyInterceptor());
  }

  @override
  void addCorsMappings(CorsRegistry registry) => registry
      .addMapping('/api/**')
      .allowedOrigins(['https://shop.example'])
      .allowedMethods(['GET', 'POST']);

  @override
  void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) =>
      resolvers.add(TenantResolver());

  @override
  void addResourceHandlers(ResourceHandlerRegistry registry) => registry
      .addResourceHandler(['/assets/**'])
      .addResourceLocations(['file:build/web/assets/'])
      .setCacheControl(CacheControl.maxAge(const Duration(days: 365)).immutable());
}

// 各コントローラーメソッドにかかった時間をログに出す。
final class TimingInterceptor with HandlerInterceptor {
  @override
  bool preHandle(
    ServerHttpRequest request,
    ServerHttpResponse response,
    HandlerMethod handler,
  ) {
    request.attributes['start'] = DateTime.now();
    return true;
  }

  @override
  void afterCompletion(
    ServerHttpRequest request,
    ServerHttpResponse response,
    HandlerMethod handler,
    Object? error,
  ) {
    final start = request.attributes['start'] as DateTime;
    log.info('${handler.description} took ${DateTime.now().difference(start)}'
        '${error == null ? '' : ' and failed with ${error.runtimeType}'}');
  }
}

// @AdminOnly() を付けたメソッドは、管理者以外には 403 を返す。
class AdminOnly {
  const AdminOnly();
}

final class AdminOnlyInterceptor with HandlerInterceptor {
  @override
  bool preHandle(
    ServerHttpRequest request,
    ServerHttpResponse response,
    HandlerMethod handler,
  ) {
    if (handler.annotation<AdminOnly>() != null &&
        request.headers['X-Role'] != 'admin') {
      throw ResponseStatusException(HttpStatus.forbidden);
    }
    return true;
  }
}

// `Tenant tenant` パラメーターは X-Tenant ヘッダーのテナントを受け取る。
class Tenant {
  const Tenant(this.id);
  final String id;
}

final class TenantResolver implements HandlerMethodArgumentResolver {
  @override
  bool supportsParameter(MethodParameter parameter) =>
      parameter.type.type == Tenant;

  @override
  Object? resolveArgument(
    MethodParameter parameter,
    ServerHttpRequest request,
    ServerHttpResponse response,
  ) => Tenant(request.headers['X-Tenant'] ?? 'default');
}

@RestController()
@RequestMapping('/api/orders')
class OrderController {
  @GetMapping()
  String list(Tenant tenant) => 'orders of ${tenant.id}';

  @AdminOnly()
  @DeleteMapping('/{id}')
  void delete(@PathVariable() String id) {}
}
```

## `WebMvcConfigurer`

| メソッド | 渡されるもの | 用途 |
|---|---|---|
| `addInterceptors(InterceptorRegistry registry)` | 空のレジストリ | すべてのパスまたは一部のパスに `HandlerInterceptor` を追加する。 |
| `addCorsMappings(CorsRegistry registry)` | 空のレジストリ | パスパターンごとに CORS ルールを追加する。[CORS](cors.md) を参照。 |
| `addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers)` | 空のリスト | 独自の型のパラメーターのためのリゾルバーを追加する。 |
| `addResourceHandlers(ResourceHandlerRegistry registry)` | 空のレジストリ | 静的リソースのマッピングを追加する。[静的リソース](static-resources.md) を参照。 |

ルール:

- **どの Bean もコンフィギュアラーになれます。** 通常は `@Configuration()` クラスが mixin しますが、`@Component()` でも動きます。
- **複数のコンフィギュアラー** はすべて Bean の順序 (`@Order`) で呼ばれます。同じレジストリとリストを共有するので、追加したものは積み重なります。インターセプターとリゾルバーは、すべてのコンフィギュアラーを通して追加された順に実行されます。
- **起動時に一度だけ呼ばれます**。スターターがコントローラーのハンドラーマッピングと静的リソースのマッピングを構築する間です。後からレジストリを変更しても効果はありません。
- これを通して設定できるものは他にありません。パスのマッチング、メッセージコンバーター、フォーマッター、ビューリゾルバーに相当するものはここにはありません。JSON は `ObjectMapper` と `spring.json.*` で、変換は変換サービスで設定します。

## インターセプター

`HandlerInterceptor` はコントローラーメソッドの周囲で実行されます。[フィルター](filters.md) と違い、コントローラーメソッドにマッピングされたリクエストに対してだけ、メソッドが選ばれた後に実行され、そのメソッドを受け取ります。

| メソッド | タイミング | 戻り値 | デフォルト |
|---|---|---|---|
| `FutureOr<bool> preHandle(request, response, HandlerMethod handler)` | メソッドの前、その CORS チェックの後。 | 続けるなら `true`。インターセプター自身がリクエストに応答したなら `false`。 | `true` |
| `FutureOr<void> postHandle(request, response, handler, Object? result)` | メソッドが `result` (その `Future` の値) を返した後、結果が書かれる前。まだヘッダーを追加できる。メソッドが例外を投げたときは呼ばれない。 | — | 何もしない |
| `FutureOr<void> afterCompletion(request, response, handler, Object? error)` | リクエストが終わったとき: 結果が書かれた後、または例外に応答した後。`error` はその例外で、`@ExceptionHandler` が応答した場合も同じ。成功時は `null`。 | — | 何もしない |

ルール:

- **順序:** `preHandle` は登録順に、`postHandle` と `afterCompletion` は逆順に実行されます。
- **`preHandle` が `false` を返した場合:** メソッドは呼ばれず、スターターはそれ以上何も書きません。インターセプターが `response` を通して応答します (`await response.send(429, 'Slow down')`)。それより前のインターセプターは `afterCompletion` を受け取ります。
- **`preHandle` が例外を投げた場合:** その例外が `@ExceptionHandler` メソッドを通してリクエストの応答になります (`ResponseStatusException(HttpStatus.forbidden)` は `403`)。
- **`afterCompletion`** は、`preHandle` が `true` を返したインターセプターに対してだけ呼ばれます。その中で投げられた例外は警告としてログに出され、無視されます。ストリームやイベントストリームでは、ストリームが終わったときに実行されます。
- **登録が必要です。** インターセプターは、コンフィギュアラーが `addInterceptors` で追加したときだけ実行されます。Spring と同様に、`HandlerInterceptor` Bean だけでは拾われません。
- **見えないもの:** 静的リソース、`404`、CORS プリフライト、ルーターの `OPTIONS` の応答。これらにはフィルターを使ってください。
- **mixin して** (`with HandlerInterceptor`)、必要なステップだけをオーバーライドしてください。

### `InterceptorRegistry` と `InterceptorRegistration`

| メンバー | 意味 |
|---|---|
| `registry.addInterceptor(interceptor)` | すでに追加されたものの後にインターセプターを追加する。登録で制限されるまで、すべてのパスが対象。登録を返す。 |
| `registry.registrations` | 登録の一覧 (順番どおり、読み取り専用)。 |
| `registration.addPathPatterns(List<String> patterns)` | インターセプターを、いずれかのパターンに一致するパスに制限する。繰り返し呼ぶとパターンが追加される。 |
| `registration.excludePathPatterns(List<String> patterns)` | いずれかのパターンに一致するパスでは、含まれていてもインターセプターを実行しない。 |
| `registration.appliesTo(String path)` | パスに対してインターセプターが実行されるかどうか: 含めるパターンに一致し (または一つも設定されていない)、除外するパターンに一致しないこと。 |
| `registration.interceptor` | インターセプター。 |

パターンはパスパターン (`/api/**`、`/books/{isbn}`) で、コンテキストパスを除いたリクエストパスと照合されます。

### `HandlerMethod`

インターセプターがメソッドについて知ることができる情報:

| メンバー | 意味 |
|---|---|
| `beanName` | コントローラー Bean の名前 (`orderController`)。 |
| `beanTypeName` | コントローラークラスの名前。 |
| `description` | ログに表示される形の `OrderController.delete`。 |
| `method` | ジェネレーターによるメソッドの記述: 名前、パラメーター、アノテーション、戻り値の型。 |
| `classAnnotations` | コントローラークラスのアノテーション。 |
| `parameters` | `MethodParameter` としてのメソッドのパラメーター。 |
| `annotation<A>()` | メソッドの `A` 型のアノテーション。なければクラスのもの。どちらにもなければ `null`。 |
| `resolveBean()` | メソッドが呼び出されるコントローラーオブジェクト。 |

選ばれたハンドラーはリクエスト属性 `bestMatchingHandlerAttribute` にも、パス変数は `uriTemplateVariablesAttribute` (`Map<String, String>`) にも入っています。帰り道で実行されるフィルターのためです。

## 引数リゾルバー

`HandlerMethodArgumentResolver` は、スターターが埋め方を知らないパラメーターを提供します。現在のテナント、現在のユーザー、複数のヘッダーから計算した値などです。

| メソッド | タイミング | 意味 |
|---|---|---|
| `bool supportsParameter(MethodParameter parameter)` | 起動時に、すべてのコントローラーメソッドのパラメーターごとに一度。 | このリゾルバーがパラメーターを埋めるかどうか。 |
| `FutureOr<Object?> resolveArgument(MethodParameter parameter, ServerHttpRequest request, ServerHttpResponse response)` | リクエストごとに一度、サポートする各パラメーターについて。 | 値。`Future` を返してもよい。例外はリクエストの応答になる: `400` や `401` にするには `ResponseStatusException` を投げる。 |

ルール:

- **独自のリゾルバーが最初に問い合わされます**。組み込みのバインドより前に、リストの順で問い合わされ、最初に「はい」と答えたものがパラメーターを埋めます。そのため、リゾルバーはアノテーション付きのものも含めてどのパラメーターでも引き受けられます。セキュリティスターターはこれを `@AuthenticationPrincipal` に使っています。Spring は独自のリゾルバーを自身のものの後に問い合わせます。
- **誰も埋めないパラメーターは起動を失敗させます:** リゾルバーがなければ、`Tenant tenant` パラメーターにはバインドがありません (`needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody`)。[起動時のチェック](controllers/startup-checks.md) を参照してください。
- `supportsParameter` は起動時にだけ実行されるので遅くても構いません。`resolveArgument` はリクエストごとに実行されるので速くあるべきです。

### `MethodParameter`

| メンバー | 意味 |
|---|---|
| `name` | ソース上のパラメーター名。 |
| `type` | 宣言された型: `type.type` は Dart の `Type`、`type.nullable` は `null` を受け付けるかどうか。 |
| `annotations` | パラメーターのアノテーション。 |
| `annotation<A>()` | `A` 型の最初のアノテーション、または `null`。アノテーションの値を読むのに使う。 |
| `has<A>()` | パラメーターが `A` 型のアノテーションを持つかどうか。 |
| `index` | すべてのパラメーターの中での位置。位置パラメーターが先、次に名前付きパラメーター。 |
| `handler` | 所属する `HandlerMethod`。 |
| `parameter` | ジェネレーターによる記述。名前付きかどうか、必須かどうかを含む。 |

```dart
// @CurrentUser() を付けたパラメーターはログイン中のユーザーの名前を受け取る。
// ユーザーのいないリクエストは 401 になる。
class CurrentUser {
  const CurrentUser();
}

final class CurrentUserResolver implements HandlerMethodArgumentResolver {
  @override
  bool supportsParameter(MethodParameter parameter) => parameter.has<CurrentUser>();

  @override
  Object? resolveArgument(parameter, request, response) =>
      request.principal?.name ??
      (parameter.type.nullable
          ? null
          : throw ResponseStatusException(HttpStatus.unauthorized));
}
```

## CORS マッピング

`addCorsMappings` は、パスパターンごとにグローバルな CORS ルールを追加します。マッピングが指定しない部分には許容的なデフォルトが使われます: すべてのオリジン、`GET`、`HEAD`、`POST`、すべてのヘッダー、30 分のプリフライトキャッシュ。ルールは各ハンドラーの `@CrossOrigin` と組み合わされ、静的リソースにも適用されます。すべてのルールと特殊なケース: [CORS](cors.md)。

## リソースハンドラー

`addResourceHandlers` は、独自のパターン、ロケーション、キャッシュ設定を持つ静的リソースのマッピングを追加します。`spring.mvc.static-path-pattern` と同じパターンのマッピングは、デフォルトのものを置き換えます。すべてのオプション: [静的リソース](static-resources.md)。

## Spring (Java) との対応

```java
@Configuration
class WebConfig implements WebMvcConfigurer {
  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new TimingInterceptor())
        .addPathPatterns("/api/**")
        .excludePathPatterns("/api/health");
  }

  @Override
  public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
    resolvers.add(new TenantResolver());
  }
}
```

重要な違い:

- `WebMvcConfigurer` は四つのメソッドを持つ mixin です: インターセプター、CORS マッピング、引数リゾルバー、リソースハンドラー。Spring のその他のメソッド (パスのマッチング、メッセージコンバーター、フォーマッター、ビューコントローラーなど) に相当するものはありません。
- レジストリは可変長引数ではなくリストを受け取ります (`addPathPatterns(['/api/**'])`)。
- `preHandle` は `HandlerMethod` を受け取り、他の種類のハンドラーを受け取ることはありません。また、非同期でも構いません。
- 独自の引数リゾルバーは組み込みのものより先に問い合わされます。
- `afterCompletion` は、`@ExceptionHandler` が応答した場合でも例外を受け取ります。

## 関連項目

- [フィルター](filters.md)
- [CORS](cors.md)
- [静的リソース](static-resources.md)
- [起動時のチェック](controllers/startup-checks.md)
- [@Configuration](../spring-core-dart/beans/configuration.md)
