設定
各クライアントは、その名前 (@FeignClient('catalog')) で spring.feign.client.config.catalog.* の下に設定します。名前 default はすべてのクライアントに適用され、クライアント自身の設定が優先されます。キーは Spring Cloud OpenFeign のもので、spring.cloud.openfeign ではなく spring.feign の下にあります。@FeignClient の属性とクライアントごとの構成クラスがそれを補います。
使う理由
タイムアウト、ロギング、クレデンシャルは、サービスと環境によって異なります。遅いレポートのサービスには長い読み取りタイムアウトが、決済サービスにはリトライと独自のアカウントが、開発には完全なログが必要です。プロパティを使えばビルドなしでこれらを変えられ、default のブロックは共通の値を一か所にまとめます。
例
# lib/resources/application.properties
spring.feign.client.config.default.read-timeout=10s
spring.feign.client.config.default.connect-timeout=2s
spring.feign.client.config.default.call-timeout=15s
spring.feign.client.config.default.sensitive-headers=X-Api-Key
spring.feign.client.config.catalog.url=https://api.neon.books
spring.feign.client.config.catalog.logger-level=basic
spring.feign.client.config.catalog.dismiss404=true
spring.feign.client.config.catalog.default-request-headers.X-Shop=neon
spring.feign.client.config.catalog.default-query-parameters.lang=en
spring.feign.client.config.catalog.follow-redirects=false
spring.feign.client.config.catalog.retryer=catalogRetryer
spring.feign.client.config.catalog.error-decoder=ShopErrors
spring.feign.client.config.catalog.request-interceptors[0]=requestIds
spring.feign.client.decode-slash=false
// カタログには独自のアカウントといくつかのリトライが必要。
@FeignClient('catalog', url: r'${catalog.url}', configuration: [CatalogFeignConfig])
abstract interface class CatalogClient {
@GetMapping('/books/{isbn}')
Future<Book> find(@PathVariable() String isbn);
}
@Configuration()
class CatalogFeignConfig {
@Bean()
Retryer catalogRetryer() => const DefaultRetryer(maxAttempts: 3);
@Bean()
RequestInterceptor catalogAuth() => BasicAuthRequestInterceptor('shop', 's3cret');
}
クライアントの設定
各キーは spring.feign.client.config.<name>.<key> です。型を含む完全な表は すべてのプロパティ にあります。
| キー | デフォルト | 意味 |
|---|---|---|
url |
なし | @FeignClient(url:) が空のときのベース URL。スキームがなければ http:// が追加される。${...} のプレースホルダーも可。 |
read-timeout |
60s |
レスポンスを、次にボディの 2 つのチャンクの間を待つ最長時間。呼び出し全体の上限ではない。なしは 0。 |
connect-timeout |
10s |
default の下でのみ: すべてのクライアントが共有するトランスポートの接続タイムアウト。なしは 0。 |
call-timeout |
なし | 一回の呼び出しが、リトライと待機を含めて全体でかけてよい最長時間。 |
logger-level |
none |
none、basic、headers、full (ロギング を参照)。 |
dismiss404 |
false |
404 は例外ではなく null (または ResponseEntity) を返す。void メソッドは引き続き例外を投げる。 |
default-request-headers.<Name> |
なし | インターセプターが実行された後、その名前のヘッダーを持たないすべてのリクエストに追加されるヘッダー。カンマ区切りのリストかインデックス付きのリストで複数の値。 |
default-query-parameters.<name> |
なし | クエリパラメーターについて同じ。クエリを含む URL はログと例外のメッセージに出るため、秘密にはヘッダーを選ぶこと。 |
follow-redirects |
true |
false では、3xx の応答はエラーのステータス。 |
retryer |
なし (リトライしない) | Retryer の Bean。Bean 名で、またはちょうど一つの Bean に一致するクラス名で。 |
error-decoder |
DefaultErrorDecoder |
ErrorDecoder の Bean。同じ方法で。 |
request-interceptors |
なし | 名前で指定する追加の RequestInterceptor の Bean: まず default のもの、次にクライアントのもの。 |
sensitive-headers |
なし | ログで *** とマスクされる追加のヘッダー: default のもの、次にクライアントのもの。 |
event-stream.reconnect、.reconnect-delay、.max-attempts |
true、3s、上限なし |
サーバー送信イベント (サーバー送信イベント を参照)。 |
そして、すべてのクライアントに共通のキーが一つ: spring.feign.client.decode-slash (true)。@PathVariable の値の中の / は / のままです。false ではそれを %2F として送ります。
値の組み合わせ方
- クライアントのキーは
defaultのものより優先されます。 - クライアントの
default-request-headersとdefault-query-parametersはdefaultのものに追加され、同じ名前ではクライアントのものが優先されます。 request-interceptorsとsensitive-headersは足し合わされます。defaultのもの、次にクライアントのものです。- オン/オフのキー (
dismiss404、follow-redirects、event-stream.reconnect、decode-slash) は、大文字小文字を問わずtrue/false、そしてon/off、yes/no、1/0を受け取ります。それ以外の値は、キーを示すエラーとともにアプリケーションを止めます。 spring.cloud.openfeign.*のキーは起動を止め、新しいキーを示します。
@FeignClient
| 属性 | デフォルト | 意味 |
|---|---|---|
name (位置引数) |
サービスの名前: 設定のキーであり、インターセプターが見る clientName。 |
|
url |
なし | ベース URL。url プロパティより優先される。${...} のプレースホルダーは解決される。 |
path |
'' |
各メソッドのパスの前に置かれる。 |
contextId |
名前 | 名前の代わりの設定のキー (...config.catalog-admin.*)。異なる設定を持つ、一つのサービスの 2 つのクライアントのため。 |
qualifiers |
[] |
@Qualifier('books') でクライアントの Bean を選ぶ追加の名前。 |
primary |
true |
クライアントの Bean が @Primary かどうか。 |
dismiss404 |
false |
dismiss404 プロパティと同じ。 |
configuration |
[] |
その Bean がこのクライアントにだけ適用される @Configuration() クラス。 |
fallback |
なし | インターフェースを実装し、呼び出しが失敗したときに応答する Bean のクラス (エラー、リトライ、タイムアウト を参照)。 |
クライアントごとの Bean
@FeignClient(configuration:) は、その Retryer、ErrorDecoder、RequestInterceptor の Bean がそのクライアントだけを設定するクラスを列挙します。列挙したクラスは @Configuration() の Bean でなければならず、そうでなければアプリケーションは止まります。その Bean が他のクライアントに届くことは決してありません。
各クライアントについて、スターターは次のように選びます。
- リトライヤーとエラーデコーダー:
retryer/error-decoderプロパティが設定されていればそれ。なければクライアントの構成クラスの Bean。なければアプリケーションの Bean。なければリトライなしとDefaultErrorDecoder。一つのレベルに 2 つの候補の Bean がある場合は、そのどちらかが@Primaryである必要があります。 - インターセプター: アプリケーションの
RequestInterceptorの Bean とクライアントの構成クラスのものを、すべて一緒に@Orderの順で。次にrequest-interceptorsプロパティが指定する Bean。プロパティは Bean に追加します。両方に該当する Bean は一度だけ実行されます。
Spring (Java) との対応
spring:
cloud:
openfeign:
client:
config:
default:
read-timeout: 10000
catalog:
logger-level: basic
キーは spring.feign の下の Spring Cloud OpenFeign のものです。connect-timeout はすべてのクライアントに一つの設定で、call-timeout と sensitive-headers は追加されたものです。retryer、error-decoder、request-interceptors のプロパティは Bean を指定します (Spring は Bean がなければクラスを生成します)。構成クラスは、子コンテキストではなく、他のクライアントから遠ざけられた普通の Bean です。クライアントごとなのは Retryer、ErrorDecoder、RequestInterceptor だけです。