エディター向けのメタデータ
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 メソッド (その場合は戻り値の型のクラス) について、ビルダーはバインドされるメンバーごとに一つのプロパティを列挙します。メンバーはバインダーが見つけるのと同じように見つけられます。
- コンストラクターバインディング: クラスがパラメーターを持つ 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[*] という名前になります。
// 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 の入れ子のキーとして、その説明、デフォルト、該当すれば
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-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で書かれます。