
# フィルター、ガード、エラー

ナビゲーションが画面を開く前に、フィルターがそれを別の場所に送ることがあります。`RouteFilter` は、先へ進むには `null` を、代わりに向かうにはロケーションを返します。[spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md) があれば、画面の `@PreAuthorize` がそうしたガードになります。ログインしていない人はログインに向かい、その後に戻ります。未知のアドレスは見つからない場合の画面を表示し、失敗したナビゲーションはエラー画面を表示します。

## 使う理由

誰が画面を開けるかは、そこへ導く各ボタンのルールではなく、アプリのルールです。フィルターは、タップ、アドレスバー、ディープリンク、戻るボタンという、すべての入り口について一度だけ判断します。`@PreAuthorize("hasRole('ADMIN')")` と書いたガードは、Spring のメソッドのものと同じように読めます。

## フィルター

```dart
// 管理者だけが /admin/** を開く。他の全員はカタログに向かう。
@Component()
final class AdminOnly implements RouteFilter {
  AdminOnly(this.session);

  final Session session;

  @override
  RouteLocation? filter(RouteRequest request) =>
      request.state.matches('/admin/**') && !session.isAdmin
          ? RouteLocation('/catalog')
          : null;
}
```

- `RouteFilter` Bean は、すべてのルートについて `@Order` の順に実行されます。ルートのフィルター (Dart の設定の `.filter(...)`、`nest` のルートのためのもの) は、その後に宣言された順に実行されます。
- フィルターは非同期にできます (`FutureOr<RouteLocation?>`)。
- `RouteRequest` は `state` (ロケーションと値を持つルート)、`location`、`route` (未知のアドレスでは `null`) を持ちます。
- 例外を投げるフィルターはエラー画面を表示します。

## ガード付きの画面

セキュリティスターターがあれば、画面の `@PreAuthorize` はメソッドセキュリティの式を受け取ります。

```dart
@ScreenRoute('/admin', title: 'Admin')
@PreAuthorize("hasRole('ADMIN')")
class AdminPage extends StatelessWidget { ... }
```

```yaml
spring:
  flutter:
    navigation:
      login: /login
```

- ログインしていない人は `spring.flutter.navigation.login` に向かい、ログイン後に画面に戻ります。このプロパティがなければ、そうしたナビゲーションはエラー画面を表示します。
- ロールを持たないログイン済みのユーザーはエラー画面を受け取ります。
- ログアウトの後、一番上の画面はガードを通って再び開かれます。
- Dart の設定では: `.filter(RouteSecurity.preAuthorize("hasRole('ADMIN')"))`。
- セキュリティスターターのない (`RouteAuthorizationFilter` Bean のない) ガード付きのルートは、そのルートを全員に開放する代わりに起動を止めます。
- ガードはデバイス上の画面を隠すだけです。サーバーは引き続きすべてのリクエストをチェックします。

## 見つからない場合の画面

```dart
@ScreenRoute.notFound()
class NotFoundPage extends StatelessWidget {
  const NotFoundPage({super.key});

  @override
  Widget build(BuildContext context) =>
      Center(child: Text('Nothing at ${context.route.uri}'));
}
```

## エラー画面

失敗したナビゲーション (`int` に対する `?page=abc` のような変換できない値、例外を投げるフィルター、拒否するガード) は、エラー画面を表示します。Dart の設定の `.error(...)`、なければ簡素なものです。その `RouteState.error` が理由を示します。

## 拒否されるアドレス

エンコードされたスラッシュやバックスラッシュ、バックスラッシュ、エンコードされた NUL、または (デコード後の) `.` / `..` セグメントを持つアドレスは何も開きません。アプリはその画面にとどまるか、そうしたリンクで開かれた場合は最初の画面を開きます。そうしないと、そうしたアドレスが一つのルートにとどまりながら、その `{*rest}` の値が別のルートのフォルダーのファイルを指し、そのルートのガードをすり抜けることがありえます。入力されたアドレスの単なるドットセグメントは先に解決されるため、ガードも含め、それが指す画面に到達します。

## 外部からのリンク

すべてのディープリンクは、フィルターとガードを含むルートを通ります。`@RouteInfo(link: false)`、または `spring.flutter.navigation.deep-links.exclude` の下のパスは、画面がリンクで開かれないようにします。代わりにアプリの最初の画面が開きます ([Web とディープリンク](web-and-deep-links.md) を参照)。

## Spring (Java) との対応

`RouteFilter` は `RouterFunctions` の `HandlerFilterFunction` です。`@PreAuthorize` はメソッドセキュリティのもので、セキュリティスターターが評価します。

## 関連項目

- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [画面とルート](screens.md)
- [Dart の設定でのルート](dart-configuration.md)
