スターター

スターター とは、pubspec.yaml に追加するとアプリケーションに機能を加えるパッケージです。Web サーバー、キャッシュ、スケジュールされたタスク、セキュリティです。デフォルトを持ち、プロパティで設定される既製の Bean を持ち込み、それぞれは同じ型の自分の Bean を宣言すると身を引きます。追加したら dart run build_runner build を実行します。ジェネレーターがそれを見つけ、その Bean を追加します (すべてのスターターのための一つのコンテキスト を参照)。

機能ごとに一つの依存関係

スターターは、その基盤となるパッケージを持ち込んで再エクスポートするので、スターターを一つインポートするだけで、その機能、Spring のアノテーション、@SpringBootApplication、ロガーが手に入ります。Web サーバーは spring_boot_starter_web だけを列挙し、それが持ち込む spring_core_dart、spring_boot_dart、ロギングスターターは列挙しません。

ルール:

  1. コードが使う機能のスターターはすべて列挙します。別のスターターがそれを持ち込んでいてもです。セキュリティスターターは Web スターターを持ち込みますが、コントローラーを持つサーバーは両方を列挙します。スターターが何に依存するかはバージョン間で変わりうるからです。
  2. スターターが持ち込むというだけの理由でパッケージを列挙しないでください。
  3. テストは開発用の依存関係として spring_boot_starter_test を使い、すべてのアプリケーションは開発用の依存関係として build_runner と spring_core_dart_generator を使います。
# REST API、キャッシュ、スケジュールされたタスクを持つサーバー。
dependencies:
  spring_boot_starter_web: ^0.9.0
  spring_boot_starter_cache: ^0.9.0
  spring_boot_starter_scheduling: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0
  test: ^1.33.0

どのスターターにも @Enable... アノテーションは不要です。@EnableCaching、@EnableScheduling、@EnableFeignClients はありません。依存関係を列挙すれば機能が有効になります。

コア

spring_core_dart

コンテナです。Bean とその注入、設定とプロファイル、イベント、メッセージ、リソース、型変換、SpEL (式言語)、バリデーション、ObjectMapper による JSON、AOP (他の Bean のメソッドの周りで実行されるコード)。他のすべてのパッケージはこれを基盤とします。依存するのは Dart チームの package:yaml だけです。

spring_core_dart: ^0.9.0

直接使うのは、Spring Boot なしで ApplicationContext.run で自分でコンテキストを起動する場合だけです。ドキュメント: spring_core_dart。

spring_boot_dart

main に付けた @SpringBootApplication() からアプリケーションを起動します。プロファイル、環境変数、引数とともに application.properties や application.yml を読み、自分の Bean とすべてのスターターの Bean でコンテキストを生成し、@ConfigurationProperties をバインドし、ApplicationRunner と CommandLineRunner の Bean を実行し、起動の失敗を説明します。ObjectMapper Bean、バリデーション、messageSource を追加します。

spring_boot_dart: ^0.9.0
@SpringBootApplication()
void main(List<String> args) => runApplication(args);

すべてのスターターがこれを持ち込むので、アプリケーションがこれを列挙することはまれです。ドキュメント: spring_boot_dart。

spring_core_dart_generator

build_runner のビルダーです。アノテーションを読み、*.spring.dart ファイルを書き出します。Bean 定義、ルート、AOP プロキシ、lib/resources/ の埋め込みリソース、スターターのリストです。ビルド時にコードをチェックし、エディターがプロパティ名の補完に使うメタデータも書き出します。すべてのアプリケーションとすべてのスターターの開発用の依存関係です。

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0

ドキュメント: spring_core_dart_generator。

サーバー

spring_boot_starter_web

HTTP サーバー (Spring MVC) です。dart:io の HttpServer で配信される @RestController クラス、JSON のボディ、@Valid のリクエストボディ、ProblemDetail としてのエラー、Server-Sent Events、アップロードとダウンロード、静的ファイル、フィルター、CORS、セッション、server.* のプロパティ。モバイルやデスクトップの Flutter アプリの中で、ローカルサーバーとしても動きます。

spring_boot_starter_web: ^0.9.0
@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) =>
      books.find(isbn) ??
      (throw ResponseStatusException(HttpStatus.notFound, 'No book $isbn'));
}

ドキュメント: spring_boot_starter_web。

spring_boot_starter_websocket

WebSocket のクライアントとエンドポイントです。クライアントは @WebSocketClient を付けた抽象クラスで、ジェネレーターがそれを実装します。JSON のメッセージ、必要に応じて開かれる一つの共有された接続、再接続を備えています。Web スターターとともに使うと、@WebSocketEndpoint の Bean が同じポートで応答します。

spring_boot_starter_websocket: ^0.9.0
@WebSocketClient('chat', url: r'${chat.url}')
abstract interface class ChatSocket {
  @OnMessage()
  Stream<ChatMessage> messages();         // 受信するメッセージ。JSON から読まれる

  @SendMessage()
  Future<void> send(ChatMessage message); // JSON として送られる
}

ドキュメント: spring_boot_starter_websocket。Web スターター上のエンドポイントについては WebSocket。

spring_boot_starter_data

Spring Data JDBC のモデルに基づく Spring Data です。@Table クラス、ジェネレーターが実装するリポジトリのインターフェース (CRUD、ページングとソート、findByTitleContainingIgnoreCase のような派生クエリ、SQL を使う @Query)、@Transactional、楽観的ロック、JdbcTemplate、マイグレーション。デフォルトはインメモリーで、spring.datasource.* から SQLite や PostgreSQL も使えます。ドライバー (sqlite3、postgres) はアプリケーション自身の依存関係です。

spring_boot_starter_data: ^0.9.0
@Table('books')
class Book {
  Book({this.id, required this.title, this.year});

  @Id()
  int? id;
  String title;
  int? year;
}

// 書くべき実装はない: ジェネレーターが書く。
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitleContainingIgnoreCase(String text);
}

ドキュメント: spring_boot_starter_data。ジェネレーターが書き出すものについては データ: エンティティ、リポジトリ、クエリ。

spring_boot_starter_cache

@Cacheable、@CachePut、@CacheEvict、@Caching によるメソッドの結果のキャッシュです。同期と非同期のメソッドに対応し、キーと条件は SpEL で書きます。spring.cache.* からの有効期限とサイズの上限を持つ、インメモリーの CacheManager があります。

spring_boot_starter_cache: ^0.9.0
@Service()
class Books {
  Books(this.api);

  final CatalogApi api;

  // API は isbn ごとに一度だけ呼ばれる。以後の呼び出しはキャッシュを読む。
  @Cacheable('books')
  Future<Book> find(String isbn) => api.load(isbn);

  @CacheEvict('books', key: '#isbn')
  Future<void> delete(String isbn) => api.delete(isbn);
}

ドキュメント: spring_boot_starter_cache。

spring_boot_starter_scheduling

固定のレート、固定の間隔、または cron 式 (プロパティから取ることもできます) で実行される @Scheduled メソッドと、TaskScheduler Bean です。タスクはアプリケーションが閉じると止まり、Flutter アプリがバックグラウンドにある間は一時停止します。

spring_boot_starter_scheduling: ^0.9.0
@Component()
class Reports {
  Reports(this.repository);

  final ReportRepository repository;

  @Scheduled(fixedRate: Duration(minutes: 5))
  void refreshCache() => repository.refresh();

  @Scheduled(cron: '0 0 9 * * MON-FRI') // 平日の 9:00
  void morningDigest() => repository.sendDigest();
}

ドキュメント: spring_boot_starter_scheduling。

spring_boot_starter_feign

HTTP のコードなしの HTTP クライアントです。@FeignClient とマッピングのアノテーションを付けた抽象クラスが、注入できるクライアントになります。アプリケーションの ObjectMapper による JSON、インターセプター、再試行、フォールバック、spring.feign.client.config.* でのクライアントごとの設定。VM、Flutter、Web で動きます。

spring_boot_starter_feign: ^0.9.0
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable() String isbn);

  @PostMapping('/books')
  Future<ResponseEntity<Book>> create(@RequestBody() Book book);
}

ドキュメント: spring_boot_starter_feign。

spring_boot_starter_security

Web スターターのためのセキュリティで、デフォルトで安全です。依存関係を列挙して何も設定しなければ、すべてのリクエストにログインが必要です。HttpSecurity で組み立てる SecurityFilterChain Bean がルールを設定します。HTTP Basic、フォームログイン、OAuth 2.0 / OpenID Connect によるシングルサインオン (oauth2Login())、JWT のリソースサーバー、セッション、CSRF、CORS、セキュリティヘッダーです。spring_security_core (ユーザー、パスワードのハッシュ化、Bean のメソッドへの @PreAuthorize) と OAuth 2.0 クライアントを持ち込みます。

spring_boot_starter_web: ^0.9.0
spring_boot_starter_security: ^0.9.0
@Configuration()
class SecurityConfig {
  @Bean()
  SecurityFilterChain filterChain(HttpSecurity http) => http
      .authorizeHttpRequests((auth) => auth
          .requestMatchers('/public/**').permitAll()
          .requestMatchers('/api/admin/**').hasRole('ADMIN')
          .anyRequest().authenticated())
      .formLogin()
      .httpBasic()
      .build();
}

ドキュメント: spring_boot_starter_security。

spring_boot_starter_oauth2_client

Spring Boot の spring.security.oauth2.client.* プロパティによる、Spring Security の OAuth 2.0 / OpenID Connect クライアントです。登録 (Google、GitHub、Facebook、Okta が組み込みで、任意のプロバイダーをその issuer で)、認可コード (PKCE 付き)、クライアントクレデンシャル、リフレッシュのグラントのトークンリクエスト、有効期限が切れる前に更新されるトークン、すべての Feign の呼び出しへのトークン。セキュリティスターターの oauth2Login() と Flutter アプリのログインはこれを基盤とします。

spring_boot_starter_oauth2_client: ^0.9.0
spring.security.oauth2.client.registration.partner.client-id=shop
spring.security.oauth2.client.registration.partner.client-secret=${PARTNER_SECRET}
spring.security.oauth2.client.registration.partner.authorization-grant-type=client_credentials
spring.security.oauth2.client.provider.partner.token-uri=https://id.partner.example/oauth2/token

# すべての Feign の呼び出しがトークンを持つ (spring_boot_starter_feign とともに)。
spring.feign.oauth2.enabled=true
spring.feign.oauth2.client-registration-id=partner

ドキュメント: spring_boot_starter_oauth2_client。

spring_boot_starter_actuator

HTTP による Spring Boot Actuator のエンドポイントで、/actuator の下にあります。ヘルスレポート (すべての HealthIndicator Bean を含む)、info、mappings を、Spring Boot の名前、プロパティ、JSON で提供します。Web スターターと、他のライブラリが基盤とする HTTP なしのエンドポイントである spring_boot_actuator を持ち込みます。

spring_boot_starter_actuator: ^0.9.0
management.endpoints.web.exposure.include=health,info,mappings
management.endpoint.health.show-details=always

ドキュメント: spring_boot_starter_actuator。

spring_boot_starter_logging

ログの行の行き先です。Spring Boot のパターンと色によるコンソール、ローテーション付きのログファイル、logging.level.* からのレベル、アプリのログ画面のためのインメモリーの LogBuffer。すべての機能のスターターがこれを持ち込むので、コマンドラインツールはこれだけを列挙します。

spring_boot_starter_logging: ^0.9.0
// このファイルのためのロガー。名前は `checkout`。
const log = SpringLog('checkout');

@Service()
class Checkout {
  void pay(int order, double amount) =>
      log.info('paid $amount', fields: {'order': order});
}
logging.level.checkout=debug
logging.file.name=logs/shop.log

ドキュメント: spring_boot_starter_logging。SpringLog の API については ロギング。

spring_boot_starter_test

開発用の依存関係としてのテストです。springBootTest は本物のアプリケーションを起動し (Spring の @SpringBootTest)、BeanOverride は Bean をフェイクに置き換え、MockMvc は Web 層をメモリー上でテストし、ApplicationContextRunner はスターターの自動構成をテストします。さらに Bean のマッチャー、captureLogs、統合テストのためのコンテナー (PostgresContainer、任意の Docker イメージ) があります。package:test と flutter_test で動きます。

dev_dependencies:
  spring_boot_starter_test: ^0.9.0
final app = springBootTest(
  springApplication,
  profiles: ['test'],
  overrides: [BeanOverride<PaymentGateway>(FakeGateway())],
);

ドキュメント: spring_boot_starter_test、Web 層のテスト、テスト: @SpringBootTest と @DataTest。

Flutter

spring_boot_starter_flutter

Flutter アプリの中の Spring Boot です。SpringApplicationWidget がアプリケーションを起動し、その Bean をウィジェットに渡します。アプリのウィジェット、そのテーマ、フォント、言語は設定ファイルから来ます。プラットフォームはプロファイル (android、ios、mobile、desktop、web など) で、アプリのライフサイクルはスケジュールされたタスクとソケットを一時停止・再開します。プラットフォームのコードはデスクトップのものだけで、spring.flutter.desktop.window.* からのウィンドウのタイトルバーとサイズのためのものです。

デザインライブラリーは知りません。インポートするのは package:flutter/widgets.dart だけなので、spring.flutter.app.type: widgets (WidgetsApp。デザインのスターターがアプリケーションにないときの種類) のアプリのビルドには Material も Cupertino も含まれません。それらを加えるのは下の二つのデザインのスターターで、列挙した一つが種類を決めます。spring.flutter.app.type を設定するのは選ぶときだけです (二つのデザインのスターター、プロファイルでのプラットフォームごとの指定、あえて widgets を保つとき)。Flutter 3.50 以降 (Dart 3.14) が必要です。

flutter:
  sdk: flutter
spring_boot_starter_flutter: ^0.9.0
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const CounterPage(),
  ),
);

// Bean の中の状態: メソッドの呼び出しのたびにリスナーに通知される。
@ChangeNotifierComponent()
class Counter {
  int value = 0;
  void increment() => value++;
}

// 必要な Bean を型に列挙し、それらが変わると再ビルドされる。
class CounterPage extends SpringStatelessWidget<(Counter,)> {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return GestureDetector(
      onTap: counter.increment,
      child: Text('${counter.value}'),
    );
  }
}

ドキュメント: spring_boot_starter_flutter。ジェネレーターがアプリのために書き出すものについては Flutter。

spring_boot_starter_flutter_material

Flutter アプリのための Material Design です。Flutter チームの material_ui の上に作られています (Flutter 3.50 から、Material は SDK の一部ではなくなりました)。依存関係にあればアプリを MaterialApp にし (spring.flutter.app.type: material。デザインのスターターがそれ一つなら推定されます)、spring.flutter.theme.* のテーマはそれぞれコンポーネントのテーマを含む Material の ThemeData になり、seed-color は Material 3 のパレットを作ります。Flutter のスターターを持ち込みます。アプリは、使うウィジェットのために material_ui も加えます。

material_ui: ^1.11.0
spring_boot_starter_flutter_material: ^0.9.0
# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: teal

ドキュメント: spring_boot_starter_flutter_material。

spring_boot_starter_flutter_cupertino

Flutter アプリのための iOS の見た目です。Material なしで、Flutter チームの cupertino_ui の上に作られています。依存関係にあればアプリを CupertinoApp にし (spring.flutter.app.type: cupertino。デザインのスターターがそれ一つなら推定され、二つのデザインのスターターがあればプラットフォームごとに種類を設定します)、テーマは CupertinoThemeData になり、seed-color は Material のアプリと同じ Material 3 のパレットを作ります。Flutter のスターターを持ち込みます。アプリは、使うウィジェットのために cupertino_ui も加えます。

cupertino_ui: ^1.1.6
spring_boot_starter_flutter_cupertino: ^0.9.0
# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: teal

ドキュメント: spring_boot_starter_flutter_cupertino。

spring_boot_starter_flutter_navigation

go_router なしで、SDK の Router (ブラウザーのアドレスバー、ディープリンク、Android の戻るボタン) 上のルートに画面を置きます。ウィジェットに付ける @ScreenRoute、Spring のパスパターン、タブを持つシェル、画面ごとに生成される型付きのルート定数、ルートのフィルター。Flutter のスターターを持ち込みます。

spring_boot_starter_flutter_navigation: ^0.9.0
@ScreenRoute('/catalog/books/{isbn}', title: 'Book')
class BookPage extends StatelessWidget {
  const BookPage({super.key});

  @override
  Widget build(BuildContext context) =>
      Text(context.route.get(BookPageRoute.isbn)); // 生成された定数
}

ドキュメント: spring_boot_starter_flutter_navigation。

spring_boot_starter_flutter_scene

flutter_scene (ブラウザーでは WebGL2、それ以外では Impeller) による、Flutter アプリのための 3D シーン。SpringSceneView はアプリのウィジェットの中のシーン、SceneBackdrop はウィジェットの背後のシーンです。シーンが描画されない場所 (オフにした場合、WebGL2 がない場合、エンジンが失敗した場合) では、プレースホルダーを表示する素のウィジェットになります。フレームの上限、モデル (spring.flutter.scene.models.*)、アプリケーションのシーンはプロパティから決まり、デバッグパネルにはすべてのシーンとモデルを名前で示すタブがあります。Flutter のスターターを持ち込みます。アプリは、使うエンジンのシーンウィジェットのために flutter_scene も列挙します。

spring_boot_starter_flutter_scene: ^0.9.0
flutter_scene: ^0.24.3
SpringSceneView.declarative(
  name: 'showroom',
  placeholder: const ShowroomPicture(),   // 描画されるまで、または描画できない場所で
  children: [SpringSceneModel('hero')],   // spring.flutter.scene.models.hero
)

ドキュメント: spring_boot_starter_flutter_scene。

spring_boot_starter_flutter_signals

Flutter アプリの Bean の中のリアクティブな状態。コンポーネントのフィールドに付ける @Signal() (代入されると、それを読んだものに伝えられる)、ゲッターに付ける @Computed() (読んだものが変わるまで保持される値。Future や Stream からも、その状態とともに)、メソッドに付ける @Effect() (読んだものが変わると再び実行される)。フィールドは普通のフィールドのままで、ウィジェットは build が読んだフィールドのためにだけ再構築されます。サードパーティのパッケージ signals_core の上に作られており、@ChangeNotifierComponent の代わりではなく、その横に並びます。Flutter のスターターを持ち込みます。

spring_boot_starter_flutter_signals: ^0.9.0
@Component()
class Basket {
  @Signal()
  List<Book> items = [];

  @Signal()
  String? coupon;

  @Computed()                        // items か coupon が変わるまで保持される
  double get total =>
      items.fold(0.0, (sum, book) => sum + book.price) *
      (coupon == null ? 1 : 0.9);

  void add(Book book) => items.add(book);
}

ドキュメント: spring_boot_starter_flutter_signals。

spring_boot_starter_flutter_security

Flutter アプリのためのセキュリティで、プラットフォームのコードを持つプラグインです。OAuth 2.0 / OpenID Connect によるアプリのログイン (OAuth2LoginService、PKCE 付きの認可コード)、キーチェーン、Android Keystore、その他のプラットフォームの安全なストアにある秘密情報、システムのログインウィンドウ、ログイン中のユーザーに従うウィジェット (context.principal)。Flutter のスターター、ナビゲーションのスターター、OAuth 2.0 クライアント、spring_security_core を持ち込むので、ログインのあるアプリはこれだけを列挙します。

flutter:
  sdk: flutter
spring_boot_starter_flutter_security: ^0.9.0
@Service()
class Account {
  Account(this._login);

  final OAuth2LoginService _login;

  Future<void> start() => _login.restore();          // 前回からログイン中か?
  Future<void> signIn() => _login.login('keycloak'); // ログインウィンドウ
  Future<void> signOut() => _login.logout();         // 取り消して忘れる
}

ドキュメント: spring_boot_starter_flutter_security。

検索

spring_search_dart

アプリケーション内の全文検索で、VM、Flutter、Web で、純粋な Dart で動きます。Markdown ファイルや任意の Bean からのドキュメント、言語ごとのアナライザー、BM25 によるランキング、前方一致、タイプミス、フレーズ、ハイライトされたスニペットを、SearchService Bean を通して提供します。依存するのは spring_boot_dart だけです。

まだ pub.dev にはありません。フレームワークの git リポジトリから取得してください。

spring_search_dart:
  git:
    url: https://github.com/farum-azula/spring_core_dart.git
    path: spring_search_dart
# lib/resources/application.yml
spring:
  search:
    markdown:
      - location: resources:content/**/*.md
        link: /docs/{path}

ドキュメント: spring_search_dart。

Supabase

spring_boot_starter_supabase

サーバーと Flutter アプリのための Supabase で、独自のクライアントを持ちます。プロジェクトのデータベースは Spring Data のリポジトリ (REST API、または spring.supabase.db.url による SQL)、Auth は Spring Security、Realtime はストリーム、Storage はテンプレートと宣言したバケット、Edge Functions は宣言したインターフェースです。データ、キャッシュ、Feign、WebSocket の各スターターと spring_security_core を持ち込みます。

spring_boot_starter_supabase: ^0.9.0
# lib/resources/application.yml
spring:
  supabase:
    url: https://abcd.supabase.co
    anon-key: ${SUPABASE_ANON_KEY}
abstract interface class Todos implements ListCrudRepository<Todo, int> {
  Future<List<Todo>> findByDoneOrderByCreatedAtDesc(bool done);
}

ドキュメント: spring_boot_starter_supabase。

Edge

spring_boot_starter_edge

同じアプリケーションを関数として実行します。Supabase Edge Functions、Cloudflare Workers、AWS Lambda、Deno Deploy、Netlify Edge Functions、Vercel Functions で動きます。JavaScript (または WebAssembly) にコンパイルされ、ソケットの代わりにプラットフォームの fetch API で応答します。コントローラー、フィルター、Spring Security、Feign クライアント、その他のスターターは、サーバーのものと同じです。Web スターターを持ち込み、再エクスポートします。

spring_boot_starter_edge: ^0.9.0
@SpringBootApplication()
void main() => runFetchApplication(() => springApplication);
dart run build_runner build
dart run spring_boot_starter_edge:build --platform supabase --name api

ドキュメント: spring_boot_starter_edge。

スターターが持ち込むライブラリ

三つのパッケージは、スターターではなくライブラリです。アプリケーションはスターターを通してそれらを得て、列挙することはまれです。

パッケージ 保持するもの 持ち込むもの
spring_web_dart サーバーとクライアントの HTTP の語彙: マッピングのアノテーション、ResponseEntity、ProblemDetail、HttpHeaders、HTTP と WebSocket のクライアントのトランスポート。spring_web_dart を参照 Web、WebSocket、Feign、OAuth 2.0 クライアント、アクチュエーター、テスト、Flutter のパッケージ
spring_security_core ユーザー、パスワードのハッシュ化、AuthenticationManager、@PreAuthorize とその他のメソッドセキュリティのアノテーション。spring_security_core を参照 セキュリティ、OAuth 2.0 クライアント、Flutter のセキュリティのパッケージ
spring_boot_actuator HTTP なしの、アクチュエーターのエンドポイントとヘルスのモデル。アクチュエーター を参照 アクチュエーター、データ、セキュリティのスターター。データスターターの db ヘルスインジケーターはこれを基盤とする

Flutter チームのデザインライブラリーは逆です。デザインのスターターはそれらを再エクスポートしないので、アプリは使うウィジェットのために、spring_boot_starter_flutter_material の隣に material_ui を、または spring_boot_starter_flutter_cupertino の隣に cupertino_ui を列挙します。

独自のもの

どのパッケージもスターターになれます。ジェネレーターに見つけてもらうには、lib/spring_auto_configuration.dart ファイルがあれば十分です。独自のスターター を参照してください。

関連項目