
# 独自のエンドポイント

`@Endpoint` クラスは、`health` や `info` の隣、`/actuator/<id>` の下にエンドポイントを追加します。有効化、公開、セキュリティ、メディアタイプのルールは同じです。Spring Boot の `@Endpoint` に当たります。

## 使う理由

アプリケーションに属する運用データ (機能フラグ、キューのサイズ、キャッシュの統計) は Actuator に向いています。一つのベースパス、一つのセキュリティのルール、一つの JSON のスタイルです。コントローラーではなくエンドポイントとして書けば、そのすべてがただで手に入ります。

## 例

```dart
// 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 を返す
}
```

```properties
management.endpoints.web.exposure.include=health,features
```

```console
$ 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`。[エンドポイント](endpoints.md) を参照してください。

## 操作

| 要素 | なるもの |
|---|---|
| `@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 エンドポイントの拡張のように、別のステータスで応答するためです。

```dart
@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) との対応

```java
@Endpoint(id = "features")
@Component
class FeaturesEndpoint {
  @ReadOperation
  Map<String, Boolean> features() { ... }

  @ReadOperation
  Boolean feature(@Selector String name) { ... }
}
```

アノテーションは同じです。違い: 読み取り操作のみ、JMX はない、そしてエンドポイントはビルド時に見つけられます。

## 関連項目

- [エンドポイント](endpoints.md)
- [セキュリティ](security.md)
- [ヘルス](health.md)
