スターター
スターター とは、pubspec.yaml に追加するとアプリケーションに機能を加えるパッケージです。Web サーバー、キャッシュ、スケジュールされたタスク、セキュリティです。デフォルトを持ち、プロパティで設定される既製の Bean を持ち込み、それぞれは同じ型の自分の Bean を宣言すると身を引きます。追加したら dart run build_runner build を実行します。ジェネレーターがそれを見つけ、その Bean を追加します (すべてのスターターのための一つのコンテキスト を参照)。
機能ごとに一つの依存関係
スターターは、その基盤となるパッケージを持ち込んで再エクスポートするので、スターターを一つインポートするだけで、その機能、Spring のアノテーション、@SpringBootApplication、ロガーが手に入ります。Web サーバーは spring_boot_starter_web だけを列挙し、それが持ち込む spring_core_dart、spring_boot_dart、ロギングスターターは列挙しません。
ルール:
- コードが使う機能のスターターはすべて列挙します。別のスターターがそれを持ち込んでいてもです。セキュリティスターターは Web スターターを持ち込みますが、コントローラーを持つサーバーは両方を列挙します。スターターが何に依存するかはバージョン間で変わりうるからです。
- スターターが持ち込むというだけの理由でパッケージを列挙しないでください。
- テストは開発用の依存関係として
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 ファイルがあれば十分です。独自のスターター を参照してください。