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

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 クラス:

// 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 に書き出すエントリー:

{
  "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 は、その定数を列挙するヒントを追加し、各定数にはそれぞれの /// テキストが付きます。

ファイルの内容

{
  "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 のデータ層: データ を参照。 データ層がある場合のみ
loaderKinds @ThemeLoaderKind クラス。 ある場合のみ
routes、shells @ScreenRoute の画面と @RouteShell のシェル。 ある場合のみ
theme spring.flutter.theme.* のスキーマ: その types と properties。 spring_boot_starter_flutter 自身のメタデータのみ

プロパティ

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

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

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

キー 由来
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 キーが一つしかないからです。

読まれるだけのキー

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

これらには説明がありません。@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[*] という名前になります。

// 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;
{
  "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 (スターターの自動構成がそうしているように。構文木から読まれます) です。

{
  "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 を除く) です。このサイトから:

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

このリストは、ライブラリのローダーの種類がアプリに知られる手段でもあります。アプリの 型付きキー のビルダーは、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 は、クラス、ソース、ブランチとともに列挙されます。ルートはパスでソートされます。このサイトから:

"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/"
  }
]

エディターはこれらでパスを補完し、検索エンジン向けのページ はこれらから作られます。

テーマ

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 を作るツールがあります。

# 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 ファイルの最初の行でスキーマを指定します。パスは YAML ファイルからの相対パスで、URL でもかまいません。

# 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 を書き出します。違い:

関連項目