
# エディター向けのメタデータ

Spring のコードを持つすべてのパッケージに対して、ビルダー `spring_metadata` は `lib/spring_gen/spring_metadata.json` を書き出します。これはエディターやツールのために、パッケージの Spring 側を記述します。型、説明、デフォルトを持つ設定プロパティ、指定できる値、Bean、プロファイル、そして Flutter アプリではローダーの種類とルートです。

ファイルの内容はすべてコードから来ます。自分で書いたり編集したりすることはありません。フィールドの `///` コメントはプロパティの説明に、リテラルの初期化子はデフォルトに、enum 型は値のリストになります。

## 使う理由

プロパティを知っているエディターは、`application.yml` で `server.port` を補完し、ホバーでその説明を表示し、`server.prot` や `port: abc` を指摘できます。それらを知るには、アプリと、それが使うすべてのスターターのすべてのキーの記述が必要です。Spring Boot にも同じ必要があり、同じ答えがあります。そのアノテーションプロセッサーが Java のクラスとその Javadoc から `META-INF/spring-configuration-metadata.json` を書き出します。

ファイルをコードから導くことで、内容が正しく保たれます。スターターはメタデータの元になるのと同じ `@ConfigurationProperties` クラスを通して設定を読むので、プロパティの説明と読まれ方がずれることはありません。

## 書き出される条件

ビルダーは、ジェネレーターに依存するすべてのパッケージで動きます。`lib/` または `bin/` の `.dart` ファイル (生成ファイルを除く) に次の語のいずれかが含まれる場合にファイルを書き出します: `ComponentScan`、`SpringBootApplication`、`AutoConfigurationModule`、`ConfigurationProperties`、`BeanDefinition<`、`@Component`、`@Service`、`@Configuration`、`@Bean`、`@ThemeLoaderKind`、`@ScreenRoute`、`@RouteShell`。Spring のコードのないパッケージにはファイルができません。

ファイルはソートされ、キーは決まった順序なので、コードが変わったときにだけ変わります。そのため差分でレビューしやすくなっています。

メインのビルダーと同じく、ソースにエラーがある間は以前に書き出したファイルを残します。ビルドは警告 (`lib/spring_gen/spring_metadata.json is kept unchanged until this error is fixed:`) をログに出し、古い内容を再び書き出します。そのため、`build_runner watch` が入力途中の行のたびにファイルを削除することはありません。

## 例

`spring_boot_starter_web` の `@ConfigurationProperties` クラス:

```dart
// spring_boot_starter_web/lib/src/config/web_properties.dart
@ConfigurationProperties('server')
class ServerSettings {
  /// The port. `0` picks a free one; the real port is then in
  /// `local.server.port`.
  int port = 8080;

  /// What happens to running requests when the server stops: `graceful`
  /// accepts no new connections and lets them finish, `immediate` cuts
  /// them.
  Shutdown shutdown = Shutdown.graceful;
  // ...
}

enum Shutdown {
  /// Stop accepting connections and let running requests finish, for up
  /// to `spring.lifecycle.timeout-per-shutdown-phase` (30 seconds by
  /// default); then close what is left. The default.
  graceful,

  /// Close every connection right away, cutting running requests.
  immediate,
}
```

ビルダーがこれに対して、そのパッケージの `lib/spring_gen/spring_metadata.json` に書き出すエントリー:

```json
{
  "properties": [
    {
      "name": "server.port",
      "type": "int",
      "description": "The port. `0` picks a free one; the real port is then in `local.server.port`.",
      "default": 8080,
      "deprecated": null,
      "source": "package:spring_boot_starter_web/src/config/web_properties.dart",
      "line": 35,
      "class": "ServerSettings"
    },
    {
      "name": "server.shutdown",
      "type": "Shutdown",
      "description": "What happens to running requests when the server stops: `graceful` accepts no new connections and lets them finish, `immediate` cuts them.",
      "default": "graceful",
      "deprecated": null,
      "source": "package:spring_boot_starter_web/src/config/web_properties.dart",
      "line": 44,
      "class": "ServerSettings"
    }
  ],
  "hints": [
    {
      "name": "server.shutdown",
      "values": [
        {
          "value": "graceful",
          "description": "Stop accepting connections and let running requests finish, for up to `spring.lifecycle.timeout-per-shutdown-phase` (30 seconds by default); then close what is left. The default."
        },
        {
          "value": "immediate",
          "description": "Close every connection right away, cutting running requests."
        }
      ]
    }
  ]
}
```

説明は `///` コメントの最初の段落を一行にしたものです。デフォルトの `Shutdown.graceful` は、プロパティの値を書くときの形 `graceful` で書かれます。enum は、その定数を列挙するヒントを追加し、各定数にはそれぞれの `///` テキストが付きます。

## ファイルの内容

```json
{
  "version": 1,
  "package": "neon_farum_azula",
  "properties": [ ... ],
  "hints": [ ... ],
  "beans": [ ... ],
  "profiles": [ "release", "web" ],
  "loaderKinds": [ ... ],
  "routes": [ ... ]
}
```

| キー | 内容 | 存在する条件 |
|---|---|---|
| `version` | 形式のバージョン、`1`。 | 常に |
| `package` | パッケージの名前。 | 常に |
| `properties` | パッケージがバインドする、または読む設定キー。 | 常に (空の場合もある) |
| `hints` | キーの値、範囲、警告。 | 常に (空の場合もある) |
| `beans` | パッケージが定義する Bean。 | 常に (空の場合もある) |
| `profiles` | パッケージが使うプロファイル名。 | 常に (空の場合もある) |
| `entities`、`repositories` | `spring_boot_starter_data` のデータ層: [データ](data.md) を参照。 | データ層がある場合のみ |
| `loaderKinds` | `@ThemeLoaderKind` クラス。 | ある場合のみ |
| `routes`、`shells` | `@ScreenRoute` の画面と `@RouteShell` のシェル。 | ある場合のみ |
| `theme` | `spring.flutter.theme.*` のスキーマ: その `types` と `properties`。 | `spring_boot_starter_flutter` 自身のメタデータのみ |

## プロパティ

### `@ConfigurationProperties` でバインドされるもの

`@ConfigurationProperties('prefix')` を持つ各クラスと、`@ConfigurationProperties('prefix')` を持つ各 `@Bean` メソッド (その場合は戻り値の型のクラス) について、ビルダーはバインドされるメンバーごとに一つのプロパティを列挙します。メンバーはバインダーが見つけるのと同じように見つけられます。

- **コンストラクターバインディング**: クラスがパラメーターを持つ public で非ファクトリーのコンストラクターを一つだけ持ち、それが `@Autowired` でない場合、プロパティはそのパラメーターです。
- **それ以外では**、クラスと SDK 外のスーパークラスの、書き込み可能な public フィールド (`late` でない限り `final` でないもの) と宣言されたセッターです。

各エントリーには次のキーがあります。

| キー | 由来 |
|---|---|
| `name` | プレフィックス、ドット、ケバブケースにしたメンバー名 (`baseUrl` は `base-url`、`apiURL` は `api-url`)。メンバーに `@Name('import')` を付けると最後のセグメントが別の名前になります。 |
| `type` | 書かれたとおりの Dart の型 (`int`、`Duration`、`List<String>`、`int?`)。 |
| `description` | フィールド (またはフィールドを初期化するコンストラクターのパラメーターでは、そのフィールド) の `///` コメントの最初の段落を一行にしたもの。コメントがなければ `null`。 |
| `default` | フィールドのリテラルの初期化子、またはコンストラクターのパラメーターのデフォルト値。下記を参照。 |
| `deprecated` | メンバーの `@Deprecated('...')` のメッセージ。なければ `null`。 |
| `source`、`line` | メンバーが宣言された場所: `lib/` のファイルなら `package:<package>/<path>`、`bin/` のファイルならそのパス。その名前の行。 |
| `class` | それを宣言するクラス。 |

入れ子の値もたどられます。

| メンバーの型 | プロパティ名 |
|---|---|
| 同じパッケージのクラス (抽象でも enum でもない) | メンバー名の下のそのメンバー: `server.compression.min-response-size` |
| そのようなクラスのリストやセット | `name[*].field` |
| そのようなクラスを値とするマップ | `name.*.field` |
| 単純な値のマップ | `name.*`。値の型で型付けされる |
| 単純な値のリスト | `name` そのもの (カンマ区切りのテキストもそこにバインドされる) |

SDK や他のパッケージの型 (`Duration`、`DataSize`、`Uri`) は値であり、グループではありません。クラスがそれ自身の中へたどられることはなく、8 レベルより深くたどられることもありません。

### デフォルト

デフォルトになるのは単純なリテラルだけです。それ以外 (呼び出し、他の場所の定数、`$` や `\` を含む文字列) は `null` になります。

| 書かれたもの | `default` |
|---|---|
| `true`、`false` | `true`、`false` |
| `8080`、`0.5` | `8080`、`0.5` |
| `'plain'`、`r"plain"` | `"plain"` |
| `[]`、`{}`、`const []` | `[]`、`{}` |
| `['a', 'b']` (リテラルのみ) | `["a", "b"]` |
| `Shutdown.graceful` (フィールドの型の enum 定数) | `"graceful"` (ケバブケース) |
| `Duration(seconds: 30)` (単位が一つ) | `"30s"` (`ms`、`s`、`m`、`h`、`d`) |
| `DataSize.ofMegabytes(10)` | `"10MB"` (`B`、`KB`、`MB`、`GB`、`TB`) |
| `null` | `null` |

`null` のデフォルトとデフォルトなしは同じに見えます。形式には `default` キーが一つしかないからです。

### 読まれるだけのキー

コードがバインドせずに読むキーも列挙されるので、エディターはそれらを知ることができます。

- `@Value('${app.title:Shop}')` のような、任意のアノテーション引数の中の各 `${key}` または `${key:default}` プレースホルダー。型は `String`、`:` の後のテキストがデフォルトです。
- `@ConditionalOnProperty` (型は `String`) と `@ConditionalOnBooleanProperty` (型は `bool`) の名前と、その `prefix`。

これらには説明がありません。`@ConfigurationProperties` クラスが同じキーをバインドしている場合は、より良い説明を持つそのエントリーが優先されます。

## ヒント

ヒントは一つのプロパティの値を絞り込みます。ビルダーは、何か伝えることのあるプロパティごとに一つ書き出します。

| コード中の出どころ | ヒントの中身 |
|---|---|
| enum 型のプロパティ | `values`: ケバブケースにした各定数と、`description` としてその `///` テキスト |
| `String` フィールドの `@PropertyValues(['plain', 'json'])` | `values`: それらのテキスト。説明なし |
| `@PropertyValues.provider('profiles')` | `provider: "profiles"`: エディターがプロジェクトのプロファイルを列挙する |
| `@Range(0, 65535)` | `range: [0, 65535]` |
| `@WarnValues([...], 'why')` | `warn: [{ "values": [...], "message": "why" }]` (enum 定数はケバブケース) |

`@Range`、`@WarnValues`、`@PropertyValues` は `spring_core_dart` のもので、メタデータ専用です。実行時には何もチェックしません。リストのプロパティでは、ヒントは要素を記述するので `name[*]` という名前になります。

```dart
// spring_boot_starter_flutter: Web 開発サーバーのポート
/// The port of the web dev server; 0 picks a free port.
@Range(0, 65535)
@WarnValues(
  [1, 7, 9, 11, /* ... */ 6697, 10080],
  "Browsers refuse to open this port (Chromium's list of blocked ports).",
)
final int? port;
```

```json
{
  "name": "spring.flutter.web.dev-server.port",
  "range": [0, 65535],
  "warn": [
    {
      "values": [1, 7, 9, 11, "...", 6697, 10080],
      "message": "Browsers refuse to open this port (Chromium's list of blocked ports)."
    }
  ]
}
```

(`"..."` は、ここで省いた値を表します。)

## Bean

メインのビルダーのスキャンが見つけるすべての Bean と、ライブラリが素の Dart で `BeanDefinition<T>(...)` を使って手で定義するすべての Bean (スターターの自動構成がそうしているように。構文木から読まれます) です。

```json
{
  "name": "basket",
  "type": "Basket",
  "types": ["Basket"],
  "scope": "singleton",
  "primary": false,
  "qualifiers": [],
  "profiles": [],
  "conditions": [],
  "source": "package:neon_books_app/src/basket/basket.dart",
  "line": 31,
  "injects": [
    { "parameter": "_shop", "type": "ShopClient", "qualifier": null }
  ],
  "members": [
    { "name": "add", "kind": "method", "type": "Future<void>", "parameters": ["Book book"] },
    { "name": "clear", "kind": "method", "type": "void", "parameters": [] }
  ]
}
```

| キー | 内容 |
|---|---|
| `name`、`type` | Bean の名前とクラス。 |
| `types` | Bean を注入できるすべての型。自身の型が先頭。 |
| `scope`、`primary`、`qualifiers` | 宣言どおり。 |
| `profiles` | その `@Profile` 条件のプロファイル名。 |
| `conditions` | その他の条件を書かれたとおりに (`@ConditionalOnProperty(...)`)。`@Bean` メソッドはクラスの条件を先に列挙する。 |
| `injects` | 注入ポイント (コンストラクターのパラメーター、注入されるフィールドとメソッド): パラメーター、その型、その修飾子。`@Value` のポイントは除外。 |
| `members` | SpEL 式が Bean で到達できるもの: クラスとそのスーパータイプ (`Object` のものを除く) の public なゲッター、フィールド、メソッド。メソッドはパラメーターを `Type name` として列挙し、名前付きのものは波括弧、省略可能なものは角括弧で囲む。 |

エディターはこれらを使って `#{@basket.count}` を解決し、注入ポイントがどの Bean を受け取るか (なし、または `@Primary` や `@Qualifier` のない複数) を表示します。

## プロファイル

パッケージのプロファイル名をソートしたものです。`@Profile` 式の中の名前 (`(dev | local) & !ci` は `dev`、`local`、`ci`) と、`lib/resources/` のすべての `application-<name>.yml`、`.yaml`、`.properties` ファイルの `<name>` です。このサイトの `application-release.yml` と `application-web.yml` は `["release", "web"]` になります。

## ローダーの種類

ソースのテキストで見つかった `@ThemeLoaderKind` クラスごとに一つのエントリーです。種類の名前、クラス、ソースと行、そして `props` (パッケージ自身のテーマがその種類のローダーに与えるトップレベルのキー。`kind`、`phases`、`tracks`、`web`、`web-sha256` を除く) です。このサイトから:

```json
"loaderKinds": [
  {
    "name": "spring-leaf",
    "class": "SpringLeafLoader",
    "source": "package:neon_farum_azula/src/splash/spring_leaf_loader.dart",
    "line": 6,
    "props": ["background", "leaf", "ring", "title"]
  }
]
```

このリストは、ライブラリのローダーの種類がアプリに知られる手段でもあります。アプリの [型付きキー](flutter/typed-keys.md) のビルダーは、`dependencies` の各パッケージの `loaderKinds` を読むので、アプリのテーマはそれらを指定できます。

## ルートとシェル

`spring_boot_starter_flutter_navigation` では、各 `@ScreenRoute` の画面が、パス、名前、クラス、ソースと、その他に宣言しているもの (`title`、`params`、`extra`、`shell`、`branch`、`content`、`notFound`、`preAuthorize`、そして `@RouteInfo` の `description`、`image`、`index: false`、`link: false`、`paths`) とともに列挙されます。各 `@RouteShell` は、クラス、ソース、ブランチとともに列挙されます。ルートはパスでソートされます。このサイトから:

```json
"routes": [
  {
    "path": "/components/{*path}",
    "name": "docs-page",
    "class": "DocsPage",
    "source": "package:neon_farum_azula/src/pages/docs/docs_page.dart#DocsPage",
    "title": "#{docs.title}",
    "content": "resources:content/components/"
  }
]
```

エディターはこれらでパスを補完し、[検索エンジン向けのページ](flutter/seo.md) はこれらから作られます。

## テーマ

`spring_boot_starter_flutter` のメタデータには、もう一つのキー `theme` があります。`spring.flutter.theme.*` の型とプロパティです (それぞれ型、説明、デフォルト、そしてルートで動くか、`themes.<name>` の中で動くか、両方か)。ビルダーはそれを、テーマのドキュメントの元になるのと同じファイルである、スターターの `tool/theme_metadata.json` からコピーします。他のパッケージはそれを繰り返しません。ツールはスターターのファイルから取ります。

## 公開

`spring_metadata.json` は他の生成ファイルと一緒にコミットします。`lib/` にあるので、`META-INF` が jar の一部であるのと同じく、パッケージとともに公開されます。アプリの `.dart_tool/package_config.json` を知っているツールは、アプリとそれが依存するすべてのパッケージのメタデータを `<package>/lib/spring_gen/spring_metadata.json` で見つけます。Spring for Dart の言語サーバーはその方法でそれらを読み、`application*.yml`、`.properties`、Dart での補完、ホバー、チェックに使います。

## どのエディターでも使える JSON Schema

言語サーバーのないエディターでも、JSON Schema で `application.yml` をチェックできます。Spring for Dart のリポジトリには、アプリとその依存関係のメタデータから JSON Schema を作るツールがあります。

```sh
# spring_core_dart リポジトリで。先にアプリで `dart pub get` とビルドを実行しておく。
dart run tool/spring_schema.dart path/to/app
# または: dart run tool/spring_schema.dart path/to/app --out schema.json
```

`path/to/app/spring-application.schema.json` (JSON Schema draft 2020-12) を書き出します。含まれるもの:

- すべてのプロパティを YAML の入れ子のキーとして、その説明、デフォルト、該当すれば `deprecated` とともに。`a[*].b` と `a.*.b` は配列とマップになります。
- `String` は文字列、`int` は整数、`double` と `num` は数値、`bool` は真偽値、`Duration`、`Uri`、`DateTime` は文字列として。リストはカンマ区切りの一つのテキストも受け付けます。
- ヒントの `values` は指定できる定数として、`range` は `minimum` と `maximum` として。JSON Schema には警告がないので、`warn` はホバーのテキストに入ります。
- Flutter のスターターがあれば、`spring.flutter.theme` の下にテーマのプロパティ。
- すべての場所で、`${...}` プレースホルダーを指定できる値として。アプリの起動時にしか解決されないからです。

YAML ファイルの最初の行でスキーマを指定します。パスは YAML ファイルからの相対パスで、URL でもかまいません。

```yaml
# yaml-language-server: $schema=../../spring-application.schema.json
spring:
  profiles:
    active: dev
```

YAML 言語サーバーを使うエディター (YAML 拡張機能付きの VS Code、Zed、Neovim など) は、キーを補完し、その説明を表示し、値をチェックします。間違った型や、ヒントのリストや範囲の外の値です。未知のキーは許可されます (`additionalProperties: true`)。メタデータが記述していないコードがキーを読むこともあるからです。言語サーバー自身のチェックはより厳格です。

## Spring (Java) との対応

Spring Boot の `spring-boot-configuration-processor` は、コンパイル時に `@ConfigurationProperties` クラスとその Javadoc から `META-INF/spring-configuration-metadata.json` を書き出します。違い:

- **手で書くものがない。** Spring Boot は、ヒントや追加のキーのために手で書いた `META-INF/additional-spring-configuration-metadata.json` をマージします。ここでは、コードの `@PropertyValues`、`@Range`、`@WarnValues` がその役割を担い、`@Value` や `@ConditionalOnProperty` が読むキーはビルドが見つけます。
- **範囲が広い。** Spring Boot のファイルにはプロパティとヒントがあります。このファイルには Bean、プロファイル、ローダーの種類、ルートもあります。
- **デフォルトはプロパティの形。** `Duration(seconds: 30)` のデフォルトは、`application.yml` に書くときと同じ `30s` で書かれます。

## 関連項目

- [型付きキー: context.theme と context.messages](flutter/typed-keys.md)
- [ビルドが読むプロパティ](build-properties.md)
- [ビルダー](builders.md)
- [@ConfigurationProperties](../spring-core-dart/config/configuration-properties.md)
- [プロファイル](../spring-core-dart/config/profiles.md)
