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 の拡張機能のリポジトリではなく、フレームワークのリポジトリにあります。インストール を参照してください。

提供するもの

ナビゲーション

定義へ移動は、選択せずにカーソルを対象に置きます。

クリックする場所 移動先
注入ポイントの型: コンストラクターのパラメーター、フィールド、@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: の場所では、探したフォルダーを列挙します。

入力中のチェック

問題は、エディターの下線として、そして診断のパネルに現れます。

文字列の中のハイライト

セマンティックハイライトが有効なら (設定 を参照)、拡張機能はアノテーションの文字列の中に色を付けます。

設定ファイルでは、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 で、次のものを提供します。

診断のパネルでは、未知のキーは次のように見えます。

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 のような派生クエリの名前で:

データベースにはあってもどのエンティティも宣言していないテーブルやカラムはチェックされません。クエリ と 派生クエリ を参照してください。

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 がスタイルのないルールを尊重するのは、それがそのトークンの種類の最初のルールである場合だけなので、各種類には多くとも一つを、その他のルールより前に置いてください。

独自のサーバー。 拡張機能は次の順で言語サーバーを探すので、ローカルのビルドが優先されます。

  1. Zed の設定の lsp.dart-spring.binary.path。必要なら binary.arguments とともに。
  2. PATH 上の dart_spring_lsp。リポジトリから dart run tool/install_language_server.dart でビルドしたもの (~/.pub-cache/bin に入ります)。
  3. 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 の前でも動きます。

リンク