颤振块设置

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

内容

依赖项和生成器 应用程序级提供程序 项目结构 工作流程:引导 Bloc 就绪项目 应用于 Talabat 克隆

依赖项和生成器

添加运行时依赖项。 明确固定主要版本,以便 dart run build_runner 不会因升级而中断。

应用程序级提供商

两个应用程序范围的对象属于小部件树的根。 MultiRepositoryProvider - 将数据层存储库公开给以下每个功能。从const <RepositoryProvider>[]开始(键入,而不是裸露的const [],它会导致strict-inference掉毛); flutter-bloc-async-api 将存储库添加到此列表中作为功能落地。每个存储库条目如下所示: AppBlocObserver — 一个全局 BlocObserver,在调试模式下将每个 Bloc 转换和错误记录到控制台。当状态机出现故障时,它会极大地缩短循环。将其设置为kDebugMode,以便生产构建保持安静。

项目结构

Bloc 替换了 flutter-apply-architecture-best-practices 中的 view_models/ 目录。该技能的存储库、服务和域模型层保持不变。每个功能一个文件夹,每个块三个文件。每个 Bloc 的测试都会镜像test/ui/features/<feature>/bloc/<feature>_bloc_test.dart 下的路径。

任务进度

[ ] 第 1 步 — 安装运行时依赖项。 flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider。 [ ] 步骤 2 — 安装发电机。 flutter pub add --dev build_runner freezed json_serializable。 [ ] 步骤 3 — 创建观察者。写出lib/core/bloc/app_bloc_observer.dart扩展BlocObserver。覆盖onChange和onError。 [ ] 步骤 4 — 初始化存储。在main()中,先调用WidgetsFlutterBinding.ensureInitialized(),然后调用HydratedBloc.storage = await HydratedStorage.build(storageDirectory: HydratedStorageDirectory((await getApplicationDocumentsDirectory()).path)),再调用runApp()。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Bootstrapping Bloc in a Flutter Project

Installs and wires the canonical Bloc stack so feature-level skills (`flutter-bloc-feature-pattern`, `flutter-bloc-async-api`, `flutter-bloc-stream-tracking`, `flutter-bloc-testing`, `flutter-bloc-forms`) plug into a project with no further setup. Mobile only — Android and iOS targets. Web and desktop are out of scope.

## Contents
- [Dependencies and generators](#dependencies-and-generators)
- [App-level providers](#app-level-providers)
- [Project structure](#project-structure)
- [Workflow: Bootstrap a Bloc-ready project](#workflow-bootstrap-a-bloc-ready-project)
- [Applied to Talabat-clone](#applied-to-talabat-clone)
- [Examples](#examples)

## Dependencies and generators

Add the runtime dependencies. Pin major versions explicitly so `dart run build_runner` does not break across upgrades.

```bash
flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider
```

Add the generators as `dev_dependencies`. `build_runner` drives both `freezed` and `json_serializable`.

```bash
flutter pub add --dev build_runner freezed json_serializable
```

Run the generator continuously while editing `freezed`-annotated files in a side terminal. This avoids stale `*.freezed.dart` and `*.g.dart` artifacts during development.

```bash
dart run build_runner watch -d
```

This skill does **not** duplicate HTTP setup. Android `<uses-permission android:name="android.permission.INTERNET" />` and the iOS `com.apple.security.network.client` entitlement live in `flutter-use-http-package`. Run that skill once for the project before adding any feature that calls a backend.

## App-level providers

Two app-wide objects belong at the root of the widget tree.

1. **`MultiRepositoryProvider`** — exposes data-layer repositories to every feature below. Start with `const <RepositoryProvider>[]` (typed, not bare `const []`, which trips `strict-inference` lints); `flutter-bloc-async-api` adds repositories to this list as features land. Each repository entry looks like:

   ```dart
   RepositoryProvider<AuthRepository>(
     create: (_) => AuthRepository(api: AuthApiClient(...)),
     lazy: true, // construct only on first read
   ),
   ```

2. **`AppBlocObserver`** — a global `BlocObserver` that logs every Bloc transition and error to the console in debug mode. It dramatically shortens the loop when a state machine misbehaves. Gate it on `kDebugMode` so production builds stay quiet.

`HydratedBloc.storage` must be initialized **before** `runApp()`; otherwise any `HydratedBloc` constructed during the first frame will crash with `HydratedStorageNotFound`. Use `path_provider` to resolve the storage directory on Android and iOS.

Use `getApplicationDocumentsDirectory()` (durable across app updates and OS reboots), **not** `getTemporaryDirectory()` — the latter can be cleared by the OS without warning, which would silently lose the user's cart on a low-storage device. Some upstream examples use the temp directory because it's faster for one-off demos; for a real app with persisted cart/auth state, the documents directory is the right choice.

## Project structure

Bloc replaces the `view_models/` directory from `flutter-apply-architecture-best-practices`. The Repository, Service, and Domain Model layers from that skill stay unchanged.

```
lib/
├── core/
│   ├── bloc/
│   │   └── app_bloc_observer.dart
│   └── result/
│       ├── failure.dart        # added by flutter-bloc-async-api
│       └── result.dart         # added by flutter-bloc-async-api
├── data/                        # unchanged from flutter-apply-architecture-best-practices
│   ├── models/                  # API DTOs
│   ├── repositories/            # consumed by Blocs via RepositoryProvider
│   └── services/
├── domain/                      # unchanged
│   └── models/
└── ui/
    └── features/
        └── <feature>/
            ├── bloc/
            │   ├── <feature>_bloc.dart
            │   ├── <feature>_event.dart
            │   └── <feature>_state.dart
            └── view/
                └── <feature>_view.dart
```

One folder per feature, three files per Bloc. Tests for each Bloc mirror the path under `test/ui/features/<feature>/bloc/<feature>_bloc_test.dart`.

## Workflow: Bootstrap a Bloc-ready project

### Task Progress
- [ ] **Step 1 — Install runtime deps.** `flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider`.
- [ ] **Step 2 — Install generators.** `flutter pub add --dev build_runner freezed json_serializable`.
- [ ] **Step 3 — Create the observer.** Write `lib/core/bloc/app_bloc_observer.dart` extending `BlocObserver`. Override `onChange` and `onError`.
- [ ] **Step 4 — Initialize storage.** In `main()`, call `WidgetsFlutterBinding.ensureInitialized()` then `HydratedBloc.storage = await HydratedStorage.build(storageDirectory: HydratedStorageDirectory((await getApplicationDocumentsDirectory()).path))` **before** `runApp()`.
- [ ] **Step 5 — Wire the observer.** `if (kDebugMode) Bloc.observer = const AppBlocObserver();` — only in debug builds, so production stays quiet.
- [ ] **Step 6 — Wrap the app root.** Replace your top-level widget with `MultiRepositoryProvider(providers: const <RepositoryProvider>[], child: MaterialApp(...))`. The `providers` list grows as features land.
- [ ] **Step 7 — Create the feature directory.** `mkdir -p lib/ui/features lib/core/bloc`.
- [ ] **Step 8 — Run the generator.** Open a side terminal: `dart run build_runner watch -d`. Leave it running while you work.

**Troubleshooting.** Run `flutter analyze` → if `dart run build_runner` errors, check that every freezed file imports `package:freezed_annotation/freezed_annotation.dart` and declares `part '<file>.freezed.dart';` → re-run. If `HydratedStorageNotFound` is thrown on first launch, your `HydratedBloc.storage` initialization happens after `runApp()` — move it before in `main()`.

## Applied to Talabat-clone

For a multi-store delivery app, the Blocs the family will eventually scaffold are (cross-referenced against `PRD_states.md`):

| Bloc | Persists? | Why |
|---|---|---|
| `AuthBloc` | yes (`HydratedBloc`) | Auth token + the user's `User: active` lifecycle state are both worth persisting across cold start; see `PRD_states.md §14` for the user-account state machine and `prd.md` for the auth/session flow. |
| `CartBloc` | yes (`HydratedBloc`) | One-cart / one-store / one-city rules; cart survives restart (`PRD_states.md §7`, `PRD_catalog.md §15.5`). |
| `StoreListBloc` | no | Re-fetch on launch; depends on location and operational gating (`PRD_states.md §4`). |
| `StoreDetailBloc` | no | Per-route, ephemeral. |
| `OrderBloc` | no | Authoritative source is the API. |
| `OrderTrackingBloc` | no | Stream-driven, scoped to an Order's `picked_up → delivered` window (deferred to `flutter-bloc-stream-tracking`). |
| `PromotionBloc` | no | Validity is computed from `start_date` / `end_date` / `is_paused` (`PRD_states.md §9` Promotion/Offer; siblings §8 Coupon and §10 Advertisement share the shape with minor variations). |

The root `MultiRepositoryProvider` will hold `AuthRepository`, `StoreRepository`, `OrderRepository`, `CartRepository` (cart is local-only; the repository wraps `hydrated_bloc` storage), and `PromotionRepository`.

## Examples

### Minimal `main.dart`

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:hydrated_bloc/hydrated_bloc.dart';
import 'package:path_provider/path_provider.dart';

import 'core/bloc/app_bloc_observer.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  HydratedBloc.storage = await HydratedStorage.build(
    storageDirectory: HydratedStorageDirectory(
      (await getApplicationDocumentsDirectory()).path,
    ),
  );

  if (kDebugMode) {
    Bloc.observer = const AppBlocObserver();
  }

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MultiRepositoryProvider(
      // Typed empty list — `const []` bare would fail `strict-inference`.
      providers: const <RepositoryProvider>[
        // Repositories are added here by flutter-bloc-async-api as features land.
        // Example:
        //   RepositoryProvider<AuthRepository>(
        //     create: (_) => AuthRepository(...),
        //     lazy: true,
        //   ),
      ],
      child: MaterialApp(
        title: 'Multi-Store Delivery',
        home: Scaffold(
          appBar: AppBar(title: const Text('Smoke test')),
          body: const Center(child: Text('Bloc setup OK')),
        ),
      ),
    );
  }
}
```

### `lib/core/bloc/app_bloc_observer.dart`

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

/// Logs every Bloc transition and error during development.
/// Wired in `main()` only when `kDebugMode` is true.
class AppBlocObserver extends BlocObserver {
  const AppBlocObserver();

  // Override `onTransition` (not `onChange`) so Bloc logs show the
  // `event + currentState → nextState` triple. `onChange` only sees the
  // state diff, which loses the event-causation half. Cubits (no events)
  // fall through to `onChange` automatically.
  @override
  void onTransition(
    Bloc<dynamic, dynamic> bloc,
    Transition<dynamic, dynamic> transition,
  ) {
    super.onTransition(bloc, transition);
    debugPrint('[${bloc.runtimeType}] $transition');
  }

  @override
  void onError(BlocBase<dynamic> bloc, Object error, StackTrace stackTrace) {
    debugPrint('[${bloc.runtimeType}] ERROR: $error');
    super.onError(bloc, error, stackTrace);
  }
}
```

### `pubspec.yaml` excerpt

```yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^9.0.0
  freezed_annotation: ^3.0.0
  json_annotation: ^4.9.0
  bloc_concurrency: ^0.3.0
  hydrated_bloc: ^10.0.0
  path_provider: ^2.1.0
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner: ^2.4.0
  freezed: ^3.0.0
  json_serializable: ^6.8.0
```

---
> Source: [abdallhMoukdad/flutter-bloc-skills](https://github.com/abdallhMoukdad/flutter-bloc-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。