独自のエンドポイント
@Endpoint クラスは、health や info の隣、/actuator/<id> の下にエンドポイントを追加します。有効化、公開、セキュリティ、メディアタイプのルールは同じです。Spring Boot の @Endpoint に当たります。
使う理由
アプリケーションに属する運用データ (機能フラグ、キューのサイズ、キャッシュの統計) は Actuator に向いています。一つのベースパス、一つのセキュリティのルール、一つの JSON のスタイルです。コントローラーではなくエンドポイントとして書けば、そのすべてがただで手に入ります。
例
// GET /actuator/features と GET /actuator/features/{name}
@Endpoint(id: 'features')
class FeaturesEndpoint {
FeaturesEndpoint(this.flags);
final FeatureFlags flags;
@ReadOperation()
Map<String, bool> features() => flags.all;
@ReadOperation()
bool? feature(@Selector() String name) => flags.all[name]; // null は 404 を返す
}
management.endpoints.web.exposure.include=health,features
$ curl localhost:8080/actuator/features
{"search":true,"recommendations":false}
$ curl localhost:8080/actuator/features/search
true
@Endpoint
| パラメーター | デフォルト | 意味 |
|---|---|---|
id |
必須 | エンドポイントの ID: ベースパスの下のパスであり、そのプロパティの <id> |
enableByDefault |
true |
プロパティが何も指定しないときに有効かどうか |
name |
クラスから | Bean の名前 |
@Endpoint は @Component の一種です。クラスはスキャンされるコードの中になければなりません。エンドポイントは、リフレクションなしに、ジェネレーターが書く Bean 定義の中から見つけられます。
組み込みのものと同じルールに従います: management.endpoint.features.enabled または .access、management.endpoints.web.exposure.include、management.endpoints.web.path-mapping.features。エンドポイント を参照してください。
操作
| 要素 | なるもの |
|---|---|
@ReadOperation() メソッド |
GET (と HEAD) の操作。produces: はそのメディアタイプを列挙する |
@Selector() パラメーター |
パスのセグメント。順に: /actuator/features/{name} |
@Selector(match: SelectorMatch.allRemaining) パラメーター |
パスの残りを List<String> として |
| その他のパラメーター | その型に変換されるクエリパラメーター。(nullable でないのに) ないか変換できなければ 400 |
SecurityContext パラメーター |
リクエストのユーザーとロール |
null の結果 |
404 |
WebEndpointResponse(body:, status:, contentType:) の結果 |
そのステータスとメディアタイプ |
Future の結果 |
待たれる |
結果は JSON として書かれます。今のところ読み取り操作しかありません。@WriteOperation も @DeleteOperation もありません。
@EndpointWebExtension
Web 拡張は、HTTP でのエンドポイントの操作を置き換えます。たとえば、health エンドポイントの拡張のように、別のステータスで応答するためです。
@EndpointWebExtension(endpoint: FeaturesEndpoint)
class FeaturesWebExtension {
FeaturesWebExtension(this.delegate);
final FeaturesEndpoint delegate;
@ReadOperation()
WebEndpointResponse<bool> feature(@Selector() String name) {
final value = delegate.feature(name);
return value == null
? const WebEndpointResponse(status: 404)
: WebEndpointResponse(body: value);
}
}
Spring (Java) との対応
@Endpoint(id = "features")
@Component
class FeaturesEndpoint {
@ReadOperation
Map<String, Boolean> features() { ... }
@ReadOperation
Boolean feature(@Selector String name) { ... }
}
アノテーションは同じです。違い: 読み取り操作のみ、JMX はない、そしてエンドポイントはビルド時に見つけられます。