Spring for Dart
Spring for Dart の拡張機能は、IntelliJ IDEA が Java の Spring に与えるエディターのサポートを Zed に与えます。spring_core_dart、spring_boot_dart、spring_boot_starter_* パッケージで作られたアプリケーションのためのものです。
そのようなアプリケーションでは、結び付けの多くがアノテーションと文字列の中にあります。コンストラクターのパラメーターがどの Bean を受け取るか、${shop.name} がどのプロパティを読むか、SpEL 式やポイントカットが何を意味するかです。Dart のアナライザーにはそのどれも見えません。拡張機能は、それが見える第二の言語サーバー dart_spring を追加します。それは Dart の言語サーバーの隣で動き、その結果は Dart のサーバーの結果に加えられます。
| 拡張機能の ID | dart-spring |
| バージョン | 0.7.1。常にサポートするフレームワークのバージョン |
| 言語 | Dart、YAML、Properties |
| ソース | spring_core_dart リポジトリの extensions/zed/dart_spring |
| 言語サーバー | extensions/language_server |
この拡張機能は、他の Zed の拡張機能のリポジトリではなく、フレームワークのリポジトリにあります。インストール を参照してください。
提供するもの
- ナビゲーション。 定義へ移動 (
F12またはCmdクリック) で、注入ポイントからその Bean へ、${key}からプロパティへ、ポイントカットからクラスへ、ルートのパスからその画面へ移動します。 - ホバー。 すべてのプロファイルのファイルでのプロパティの値、注入ポイントの候補の Bean、
resources:の場所が解決されるファイル、名前付きポイントカットの式。 - 入力中のチェック。 不正な SpEL、不正なポイントカット、未知のプロパティ、普通の文字列の中のプレースホルダー、足りないアセット、未知の設定キー、曖昧な Bean。
- Dart の文字列の中の SpEL、プレースホルダー、ポイントカット、
@Queryの SQL、そして設定ファイルの中のプレースホルダーの ハイライト。 - パッケージとその依存関係の Spring のメタデータからの、設定ファイルでの補完、ホバー、チェック。
@Query('...')の中と派生クエリの名前での Spring Data のサポート。- Dart のための、そして YAML と
.propertiesファイルのテーマのための スニペット。 .propertiesファイルのための Properties 言語。- Spring Initializr のような プロジェクトジェネレーター
dart_spring_lsp create。
ナビゲーション
定義へ移動は、選択せずにカーソルを対象に置きます。
| クリックする場所 | 移動先 |
|---|---|
注入ポイントの型: コンストラクターのパラメーター、フィールド、@Autowired のセッターやメソッド、@Bean メソッドのパラメーター |
その型のすべての Bean。@Primary が先。List<T>、Set<T>、ObjectProvider<T> は T の Bean へ |
Bean のコンストラクターの this.payments |
フィールドの型の Bean |
@Qualifier('cash') を持つパラメーターやフィールド、または 'cash' の文字列そのもの |
cash という名前、または修飾子の Bean |
@DependsOn、@ConditionalOnBean、@ConditionalOnMissingBean.named の文字列 |
それらの Bean |
getBean<Clock>()、getBeanProvider<T>()、context.bean<T>() |
その型の Bean |
@BuildContextAccess の Bean のために生成されたゲッター context.basket |
その Bean |
ウィジェットの Bean レコードの中の型: SpringStatelessWidget<(Basket, {Clock utc})>、SpringStatefulWidget<...>、SpringState<W, (...)> |
その型の Bean。名前付きのフィールドはその名前で選ぶ |
@Value、getProperty('shop.name')、@ConditionalOnProperty の中の ${shop.name} |
それを定義するすべての application*.properties の中のキー |
@ConfigurationProperties('shop') |
shop.* のキー |
SpEL の中の Bean 名: #{appConfig.name}、#{@clock.now()} |
その Bean |
resources:legacy.properties (@PropertySource、@Value、getResource の中)、file:config/app.properties、asset:assets/logo.png |
そのファイル。resources: はパッケージの lib/resources/ (テストでは test/resources/ が先)。file: と asset: はパッケージからの相対 |
ポイントカットの中の型: within(...)、execution(...)、@annotation(Timed) |
そのクラス。*Service のようなワイルドカードはすべての一致へ |
ポイントカットの中の pricing()、AuditAspect.pricing() |
@Pointcut メソッド |
bean(order*)、execution(* OrderService.place*(..)) のメソッド |
一致する Bean とメソッド |
キャッシュのキーや条件の中の #isbn: @Cacheable('books', key: '#isbn') |
メソッドのパラメーター |
画面のパス: context.route.go('/catalog/books/978-0')、push、RouteLocation.parse / expand、@RouteShell(branches: [...]) や @ScreenRoute(branch: '/more') のブランチ、@RouteInfo(paths: [...])、設定ファイルの spring.flutter.navigation.initial / login / redirects |
パス変数と {*rest} も含めてパターンが一致する @ScreenRoute クラス (または ScreenRoutes の画面)。どのシェルも持たないブランチには下線が引かれる |
@ScreenRoute(title:)、@RouteInfo(description:)、ScreenRoutes...screen(title:) の中の #{nav.catalog} |
messages*.properties の中のキー。ホバーはメッセージを表示し、#{ の後でキーが補完され、未知のキーは警告 |
ホバー
注入ポイントへのホバーは、候補の Bean を、それぞれが宣言されたファイルとともに列挙します。次のコンストラクターについて:
@Service()
class Checkout {
Checkout(this.payments, @Value(r'${shop.name}') this.shopName);
final PaymentService payments;
final String shopName;
}
PaymentService にホバーすると、次のように表示されます。
Beans of type PaymentService
- bean 'cardPayments': CardPayments @Primary — lib/src/card_payments.dart
- bean 'cashPayments': CashPayments @Profile([dev]) — lib/src/cash_payments.dart
プレースホルダーの中の shop.name にホバーすると、それを設定する各ファイルでの値が表示されます。
shop.name
- application.properties: Book Shop
- application-dev.properties: Book Shop (dev)
何も見つからない場合、ホバーはそう伝えます: PaymentService: no bean found in this project、または shop.name: not defined in any properties file; the default after the colon is used: Shop。存在しない resources: の場所では、探したフォルダーを列挙します。
入力中のチェック
問題は、エディターの下線として、そして診断のパネルに現れます。
- 不正な SpEL (
#{1 +}): パーサーが報告する位置でのエラー。SpEL はspring_core_dart自身が解析するので、エディターはランタイムが拒否するものとまったく同じものを拒否します。 - 不正なポイントカット。プロジェクトの
@Pointcutメソッドとともに、ランタイム自身のパーサーでチェックされます。未知のordrs()には下線が引かれます。 - キャッシュのキーと条件 (
@Cacheable、@CachePut、@CacheEvictのkey:、condition:、unless:。@Cachingの中も): SpEL の構文。パラメーターでない (#root、#result、#p0でもない)#isbmは、パラメーターを列挙する警告になります。 - 未定義のプレースホルダー: どのプロパティファイルも、メタデータのどのプロパティも定義していない、デフォルトなしの
${key}は警告です。 - 普通の文字列の中のプレースホルダー:
@Value('${key}')はエラーです。Dart ではそれは文字列補間だからです。メッセージはIn Dart ${...} in a normal string is interpolation, not a placeholder: use a raw string, r'${key}' (or escape: '\${key}')です。 - テストのコンテナー (
spring_boot_starter_test/containers.dart):staticでない@Containerフィールドと、GenericContainerに付けた@ServiceConnectionはエラーです。@ServiceConnectionのPostgresContainerやKeycloakContainerのプロパティは、そのテストファイルで定義されたものとみなされ、ホバーはどのコンテナーがそれを提供するかを示します。 - Flutter のアセット: ファイルがない、または
pubspec.yamlのflutter: assets:の下で宣言されていない@Value('asset:...')は、追加すべきエントリーを示す警告です。 - 注入ポイント: Bean がなければエラー。複数の Bean があってどれも
@Primaryでなければ、どのプロファイルが考慮されたかを示す警告です。 - プロファイル: どの
application-xファイルもメタデータも知らないプロファイルを使う@Profile('x')は警告で、近い既知のプロファイルがあれば「Did you mean」が付きます。
文字列の中のハイライト
セマンティックハイライトが有効なら (設定 を参照)、拡張機能はアノテーションの文字列の中に色を付けます。
- SpEL とプレースホルダー: キーワード、演算子、数値、文字列、
#variables、@beans、メソッド、プロパティ、T(Types)、プレースホルダーのキー。@Scheduledの cron と間隔の文字列、素の SpEL のキャッシュキーでも。 - ポイントカット: 指定子 (
execution、within、@annotationなど)、&&、||、!、型、アノテーション、Bean のパターン、メソッド名、名前付きポイントカット。 @Queryの中の SQL: Spring Data のリポジトリ を参照してください。- クロージャーのパラメーター は、
(alert) => heard.add('${alert.isbn}')のように、宣言された場所と、クロージャーの本体がそれを使うすべての場所で、独自のトークンclosureParameterを受け取ります。クロージャーの中で再び宣言された名前はそれを隠します。関数とメソッドのパラメーターはそのままです。
設定ファイルでは、application*.yml / .yaml、resources/ の下の YAML、.properties ファイルの値の中の ${key}、${key:default}、#{...} が同じようにハイライトされます。YAML では、引用符のない # はコメントとして読まれるので、SpEL は引用符の中でだけ数えられます。
設定ファイルと Spring のメタデータ
ジェネレーターは、Spring のコードを持つすべてのパッケージに lib/spring_gen/spring_metadata.json を書き出します。言語サーバーは、自分のパッケージとそのすべての依存関係 (.dart_tool/package_config.json を通して見つける) についてそのファイルを読み、ビルドがそれを変えると再読み込みします。application*.yml、.properties ファイル、lib/resources/ の下の YAML で、次のものを提供します。
- キーの 補完。入れ子の YAML (カーソルの上にあるキーの下のキー、ドット区切りのキー、リストとマップのパターン) を考慮します。そして値の補完。メタデータの enum のヒント、
true/false、spring.profiles.activeのためのプロファイル、テーマでの$colors.<role>と宣言された色とトークン ($neon.cyan)、色オブジェクトの部分 (color、alpha、mix) です。 - 説明、型、デフォルト、キーを宣言するクラスとファイルを示す ホバー。ヒントの値と範囲。テーマのキーでは、それが設定する Flutter のフィールドと、状態ごとの値を取るかどうか。
- チェック: 「Did you mean」付きの未知のキー、間違った型 (
port: abc)、範囲外の数値、メタデータが警告する値 (ブラウザーが拒否するポート)、テーマのキーと色、壊れた$の参照。 - ローダーとスプラッシュ (
loaders.<name>、splash):kindの値 (組み込みのものとワークスペースの@ThemeLoaderKindクラス)、各種類が受け取るキー、宣言された名前からチェック・補完されるsplash.loaderとsplash.animation、.htmlファイルからチェック・補完されるローダーのweb:ファイル。 $の参照から、依存関係のテーマの中も含めて宣言された場所への、splash.loader: nameからloaders.<name>への、web:からファイルへの、${key}からそれを設定するすべてのプロファイルのファイルへの 定義へ移動。- 設定の値と Dart の文字列の中の SpEL の Bean:
#{@bean.member}は@の後で Bean を、.の後でメンバーを補完し、ホバーで型を表示し、Bean へ移動し、未知の Bean やメンバーを報告します。
診断のパネルでは、未知のキーは次のように見えます。
Unknown property 'prot' in 'server'. Did you mean 'port'?
開いている設定ファイルの保存されていないキーも、ナビゲーションと未知のキーのチェックで数えられます。
メタデータのファイルを持たないパッケージは、そのファイルの先頭に情報の行を一つ表示します: No Spring metadata for my_app: run build_runner (dart run build_runner build) to get completion, hovers and checks for keys, beans and the theme。それまでエディターは推測しません。依存関係が定義しうるキーは、未知のものとして報告されません。
Spring Data のリポジトリ
spring_boot_starter_data について、リポジトリのメソッドの @Query('...') の中 (隣接する文字列リテラルは一つのテキストとして数えられます) と、findByTitle のような派生クエリの名前で:
- SQL の ハイライト: キーワード、テーブル名とカラム名、エイリアス、数値、文字列、コメント、
:params、{Entity.property}、:#{...}の SpEL。 - 定義へ移動:
{Book}からエンティティのクラスへ、{Book.author}からフィールドへ、:yearと#yearからメソッドのパラメーターへ、SpEL の中の Bean から Bean へ、派生名 (findByTitle) のプロパティの部分からフィールドへ。 - ホバー: テーブル、ID、プロパティを持つエンティティ。カラム、型、参照を持つプロパティ。型を持つパラメーター。そして派生クエリの名前では、それが表す SQL。
{(エンティティ)、{Book.(保存されるプロパティ)、:(メソッドのパラメーター) の後の、そして:#{の中のパラメーター、Bean、メンバーの 補完。- チェック: 「Did you mean」付きの未知の
{Entity}や{Entity.property}、パラメーターでない:name(エラー)、クエリが使わないパラメーター (警告。PageableとSortは除く)、:#{...}の中の不正な SpEL、素の?、対応の取れていない引用符、括弧、波括弧。派生名では、未知のプロパティ、コレクションや入れ子のパス、名前に合わないパラメーターの数。
データベースにはあってもどのエンティティも宣言していないテーブルやカラムはチェックされません。クエリ と 派生クエリ を参照してください。
Properties 言語
拡張機能は、.properties ファイルのための Properties 言語を持ち込みます。Zed の Java の拡張機能が使うのと同じコミットの tree-sitter-properties を基盤としているので、両方は同じようにハイライトします。キー、値、# と ! のコメント、エスケープ、\ による行の継続、Spring の ${key} と ${key:default} のプレースホルダー (${PORT:8080} のような環境変数は別の色)、リストのインデックス (servers[0].host) に色を付けます。Cmd-/ で行をコメントアウトします。
スニペット
プレフィックスを入力して Tab を押します。フィールドは Tab で順に埋められ、二度現れるフィールドは両方の場所で同時に編集されます。
たとえば、spservice は次のように展開されます。
@Service()
class NameService {
NameService(this.repository);
final Repository repository;
}
最初に Name、次に repository、次に Repository が選択されます。spvalue は次のように展開されます。
@Value(r'${app.key:default}')
late final String name;
Dart
| プレフィックス | 挿入されるもの |
|---|---|
spboot |
@SpringBootApplication を持つ main |
spscan |
@ComponentScan モジュール (Boot なしの spring_core_dart) |
spservice、spcomponent、sprepository |
Bean クラス |
spiface |
インターフェースとその @Service の実装 |
spconfig、spbean |
@Configuration クラス、@Bean メソッド |
spvalue、spvalueparam |
プロパティから値を入れるフィールドやコンストラクターのパラメーター |
spautowired、spsetter |
フィールド注入やセッター注入 |
spqualifier、spprimary、spprofile |
Bean の選択 |
spself |
自己呼び出しにアドバイスを適用するための @Lazy の自己注入 |
sppost、sppre |
@PostConstruct、@PreDestroy |
splistener、sppublish |
@EventListener、イベントの発行 |
spaspect |
アノテーションとそのための @Around アスペクト |
spprops、spcondprop、sprunner |
@ConfigurationProperties、@ConditionalOnProperty、CommandLineRunner |
splog、splogger |
@Log (生成される log ゲッター)、SpringLog の定数 |
sptest |
springBootTest と BeanOverride を使うテストファイル |
Flutter
spring_boot_starter_flutter 向け:
| プレフィックス | 挿入されるもの |
|---|---|
spflutter |
SpringApplicationWidget の下に @SpringBootApplication を持つ main |
spstateless、spstateful |
beans を読む SpringStatelessWidget<(...)>、SpringState を持つ SpringStatefulWidget |
spnotifier |
@BuildContextAccess を持つ @ChangeNotifierComponent |
spaccess、spnotify |
@BuildContextAccess(name: ...)、@NotifyListeners を持つ ChangeNotifier の Bean |
spasset |
@Value('asset:...') のパラメーター |
splifecycle |
AppLifecycleStateEvent のための @EventListener |
spwidgettest |
springBootTest と SpringScope を使うウィジェットテスト |
sploaderpainter |
@ThemeLoaderKind のペインター (ThemeLoaderPainter<P>) |
テーマとアプリのウィジェット
application.yml と .properties ファイルで、両方で同じプレフィックス:
| プレフィックス | 挿入されるもの |
|---|---|
spapp |
spring.flutter.app: 種類、タイトル、デバッグバナー |
sptheme |
spring.flutter.theme: アクティブなテーマ、シードカラー、フォント、シェイプ、コンポーネント、ダークテーマ |
spthemeall |
すべてのテーマのプロパティをコメントアウトし、その値とともに (YAML のみ) |
spthemenew |
独自のテーマ (themes.<name>、extends)。YAML では独自のファイルに |
spcolors、sptypography、spshape |
色のロール、テキストのロールごとのフォント、シェイプのスケール |
spcolorobject |
alpha と mix: { with, amount } の一方または両方を持つ色 |
spcomponents、sptokens |
トークンからの Material のコンポーネント、アプリ独自のトークン |
spfonts |
spring.flutter.fonts: 自動読み込み、除外 |
sploader、sploaderkind |
組み込みのローダー、フェーズと web: を持つ @ThemeLoaderKind クラスのローダー |
spsplash |
splash: 背景、ロゴ、タイトル、ローダー、最小時間、終了 |
プロジェクトを作る
言語サーバーは、Spring Initializr のように、Spring Boot のアプリケーションも作ります。Zed の拡張機能はまだコマンドパレットにコマンドを追加できないので、ターミナルで実行します (Zed のターミナルでも動きます: Ctrl-`)。Dart ファイルが一度開かれると、拡張機能はダウンロードしたサーバーを決まったパスに保持します。
# macOS
"$HOME/Library/Application Support/Zed/extensions/work/dart-spring/bin/dart_spring_lsp" create my_app
# Linux
~/.local/share/zed/extensions/work/dart-spring/bin/dart_spring_lsp create my_app
# Windows
& "$env:LOCALAPPDATA\Zed\extensions\work\dart-spring\bin\dart_spring_lsp.exe" create my_app
| オプション | 効果 |
|---|---|
create my_app |
プロジェクトを持つ新しいフォルダー my_app |
create . |
現在の空のフォルダーにプロジェクト |
--name=shop |
パッケージ名。デフォルトはフォルダー名から |
--no-pub |
dart pub get と build_runner build をスキップする |
--force |
空でないフォルダーに書き込む |
--help |
オプション |
@SpringBootApplication を持つ bin/main.dart、@ConfigurationProperties('app') クラス、@Service、ApplicationRunner、lib/resources/application.properties と application-dev.properties、springBootTest のテスト、そして spring_boot_dart、ロギングとテストのスターター、ジェネレーターを持つ pubspec.yaml を書き出します。その後:
cd my_app
dart run bin/main.dart # my_app says: Hello, world!
dart test
設定
ナビゲーション、ホバー、チェックは、拡張機能をインストールしたらすぐに動きます。Zed の settings.json の二つの設定で色が加わります。
SpEL、プレースホルダー、ポイントカット、SQL のための セマンティックハイライト:
{
"languages": {
"Dart": { "semantic_tokens": "combined" },
"YAML": { "semantic_tokens": "combined" },
"Properties": { "semantic_tokens": "combined" }
}
}
クロージャーのパラメーターの色。 ルールが、サーバーの closureParameter トークンを variable.parameter.closure のようなテーマのスタイルに対応付け、Farum Azula Themes がそれに色を付けます。Flutter Tools の拡張機能は、その Dart の言語とともにこれらのルールを提供します。別の Dart の拡張機能では、自分で追加してください。
{
"global_lsp_settings": {
"semantic_token_rules": [
{ "token_type": "class", "token_modifiers": ["annotation"] },
{ "token_type": "property", "token_modifiers": ["annotation"] },
{ "token_type": "method", "token_modifiers": ["annotation"] },
{ "token_type": "annotation" },
{ "token_type": "parameter" },
{ "token_type": "closureParameter", "style": ["variable.parameter.closure"] }
]
}
}
スタイルのないルールは、トークンの色を取り除き、tree-sitter の色に任せます。Dart の解析サーバーはすべてのパラメーターを parameter とするので、そのルールがなければ、そのトークンが closureParameter を隠してしまいます。最初の四つのルールは、アノテーションを独自の色に保ちます。Zed がスタイルのないルールを尊重するのは、それがそのトークンの種類の最初のルールである場合だけなので、各種類には多くとも一つを、その他のルールより前に置いてください。
独自のサーバー。 拡張機能は次の順で言語サーバーを探すので、ローカルのビルドが優先されます。
- Zed の設定の
lsp.dart-spring.binary.path。必要ならbinary.argumentsとともに。 PATH上のdart_spring_lsp。リポジトリからdart run tool/install_language_server.dartでビルドしたもの (~/.pub-cache/binに入ります)。- GitHub リリース
v<version>(macOS Apple Silicon、Linux x64 と arm64、Windows x64) から、またはそれにバイナリーがなければ最新のリリースからダウンロードしたバイナリー。
{
"lsp": {
"dart-spring": {
"binary": { "path": "/path/to/dart_spring_lsp" }
}
}
}
トラブルシューティング
ナビゲーションもホバーもまったくない。 サーバーは、Dart ファイルが初めて開かれたときにダウンロードされます。Zed はステータスバーにダウンロードを表示します。Zed のログ (zed: open log) とサーバーのログ (dev: open language server logs、dart_spring) を確認してください。
"no prebuilt language server for this platform"。 Intel の Mac やその他のプラットフォーム向けのバイナリーはありません。spring_core_dart リポジトリをクローンし、dart run tool/install_language_server.dart を実行し、~/.pub-cache/bin が Zed から見える PATH にあることを確認してください。
SpEL やプレースホルダーの色がない。 Dart、YAML、Properties で semantic_tokens を有効にしてください (設定 を参照)。
スターターのキーが補完されない、またはテーマがチェックされない。 パッケージが lib/spring_gen/spring_metadata.json を持つように、dart run build_runner build を実行してください。メタデータが存在する前に公開された依存関係は、ファイルの先頭に No Spring metadata in ... を表示します。
Bean が存在するのに見つからないと報告される。 手で宣言された Bean (BeanDefinition(...)) はインデックスされません。サーバーは Dart の構文だけを解析するので、pub get の前でも動きます。