
# インターセプター

`RequestInterceptor` は、すべてのリクエストを送られる前に変更します。すべての呼び出しが必要とし、どのメソッドも繰り返すべきでないもの、つまり認証のヘッダー、トレースの ID、共通のクエリパラメーターに使います。すべての `RequestInterceptor` の Bean は、`@Order` の順に、すべてのクライアントに適用されます。

## 使う理由

すべてのメソッドに手で追加したトークンやリクエスト ID は雑音で、一つでも忘れたメソッドは認証されていないリクエストを送ります。インターセプターは、すべてのクライアントまたは一部のクライアントのために、それを一度だけ追加し、試行のたびに再び実行されるため、更新されたトークンはリトライに届きます。

## 例

```dart
@Configuration()
class FeignSetup {
  // ユーザーのトークン。関数は非同期でもよく、試行のたびに再び問い合わせられる。
  @Bean()
  RequestInterceptor auth(TokenStore tokens) =>
      BearerTokenRequestInterceptor(() => tokens.accessToken);

  @Bean()
  @Order(10)
  RequestInterceptor requestIds() => RequestIds();
}

// すべての呼び出しはリクエスト ID を持つ。カタログは言語も受け取る。
final class RequestIds implements RequestInterceptor {
  @override
  void apply(RequestTemplate template) {
    template.header('X-Request-Id', newId());
    if (template.clientName == 'catalog') template.query('lang', 'en');
  }
}
```

## RequestTemplate

| メンバー | 意味 |
|---|---|
| `method`、`url` | HTTP メソッドと完全な URL (ベース URL、パス、クエリ)。インターセプターはそれらを置き換えてよい。 |
| `headers` | 読んだり変更したりするリクエストのヘッダー。 |
| `body` | エンコードされたボディ、または `null`。置き換えても `Content-Type` は変わらない。 |
| `header(name, value)` | Feign と同じく値を追加する。ヘッダーを置き換えるには、先に `removeHeader(name)` を呼ぶ。 |
| `removeHeader(name)` | ヘッダーを取り除く。 |
| `query(name, value)` | クエリパラメーターを追加する。 |
| `methodKey` | どのメソッドが呼び出しを行うか。`CatalogClient#find(String)` など。エラーデコーダーも同じキーを受け取る。 |
| `clientName` | 一部のクライアントにだけ作用するための、クライアントの `@FeignClient` の名前。 |

## インターセプターの実行方法

- `apply` は、たとえば新しいトークンを取得するために `Future` を返してもかまいません。呼び出しはそれを待ちます。例外は呼び出しを失敗させます。
- リトライを含め、呼び出しのすべての試行で、毎回新しいテンプレートの上で実行されるため、ヘッダーの値が積み重なることはありません。
- 呼び出しの `call-timeout` と呼び出し元の期限のもとで実行されます。
- サーバー送信イベントのストリームでは、接続のたびに実行されるため、ストリームが再接続するときは更新されたトークンが使われます。
- その後で、それらが設定しなかった名前について、`default-request-headers`、`default-query-parameters`、デフォルトの `Accept` ヘッダーが追加されます。

## 出来上がったインターセプター

| インターセプター | 送るもの |
|---|---|
| `BearerTokenRequestInterceptor(token)` | 非同期でもよい関数からの `Authorization: Bearer ...`。`null` を返すと何も追加しない。 |
| `BasicAuthRequestInterceptor(user, password)` | Feign と同じく ISO-8859-1 でエンコードした HTTP Basic のクレデンシャル。それ以外の文字には `encoding: utf8` を渡す。 |

## クライアントが受け取るインターセプター

1. アプリケーションの `RequestInterceptor` の Bean と、クライアントの `@FeignClient(configuration:)` クラスのものを、すべて一緒に `@Order` の順で。
2. 次に、`request-interceptors` プロパティが指定する Bean。まず `default` のもの、次にクライアントのもの。両方に該当する Bean は一度だけ実行されます。

あるクライアントの構成クラスの Bean が他のクライアントに届くことは決してありません ([設定](configuration.md) を参照)。

## 秘密

秘密はクエリパラメーターではなくヘッダーとして送ってください。クエリを含む URL はログと例外のメッセージに出ます。`Authorization`、`Proxy-Authorization`、`Cookie`、`Set-Cookie`、`DPoP` はログで常にマスクされます。その他のものは `sensitive-headers` で指定してください ([ロギング](logging.md) を参照)。

## Spring (Java) との対応

```java
@Bean
RequestInterceptor requestIds() {
  return template -> template.header("X-Request-Id", newId());
}
```

インターフェースは同じです。ここでは各リトライは新しいテンプレートから始まります。Feign は同じテンプレートの上でインターセプターを再び実行し、そこではヘッダーの値が積み重なります。

## 関連項目

- [設定](configuration.md)
- [エラー、リトライ、タイムアウト](errors-and-retries.md)
- [ロギング](logging.md)
