独自のエンドポイント

@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 はない、そしてエンドポイントはビルド時に見つけられます。

関連項目