WebMvcConfigurer

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

使う理由

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

例

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 を参照。
addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) 空のリスト 独自の型のパラメーターのためのリゾルバーを追加する。
addResourceHandlers(ResourceHandlerRegistry registry) 空のレジストリ 静的リソースのマッピングを追加する。静的リソース を参照。

ルール:

インターセプター

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

メソッド タイミング 戻り値 デフォルト
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。 — 何もしない

ルール:

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 を投げる。

ルール:

MethodParameter

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

リソースハンドラー

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

Spring (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());
  }
}

重要な違い:

関連項目