跳到正文
CH 16综合与交付Flutter7 分钟阅读

综合项目(上):架构设计、数据层、依赖注入

第 16 章 · 综合项目(上):架构设计、数据层、依赖注入

本章示例examples/ch16-bookmarks/(ch16 与 ch17 共用这一个工程)在线阅读源码下载 zip

run

$cd examples/ch16-bookmarks && flutter run -d macos

已验证

  • flutter analyze 0 告警、flutter test 20 个用例全绿、debug 与 **release** 构建均真实启动成功
  • 完整工程已打包:打包下载
本章目录 · 19 节

从这一章开始,我们不再讲"单个知识点",而是把前 15 章的零件拼成一个能交付的应用:离线优先的书签管理器。

16.1 需求与验收标准

功能 验收
书签列表(收藏优先、按创建时间倒序) 有 0/1/N 条都正确显示
新建(标题必填、URL 必须是 http(s)) 非法输入不落库
搜索标题/备注/链接 命中过滤,空结果有区分文案
收藏 / 取消收藏 立即生效并持久化
删除(带确认) 删除后列表与详情一致
从远程导入 去重、失败不污染本地数据
离线可用 断网时列表照常(SQLite 是唯一数据源)

技术栈就是前面各章的组合:Riverpod(状态/DI)+ drift(持久化)+ http(网络)+ go_router(路由),没有引入任何新概念。

16.2 分层:依赖只能单向流动

text
presentation/   (pages/widgets:只认识 providers)
      │
      ▼
application/    (providers:DI、派生状态、actions)
      │
      ▼
domain/         (实体 + 仓储接口:不依赖 Flutter/drift/http)
      ▲
      │
data/           (drift/http 实现:唯一 import 数据库和网络的地方)

三条铁律:

  1. domain 不 import 任何实现(连 drift 都不行)。这样领域逻辑可以被任何数据源复用,测试也不需要搭数据库。
  2. presentation 不 import data。UI 只 ref.watch(...),永远不 AppDatabase/http.Client 直连。
  3. 依赖方向指向抽象:application 依赖 BookmarkRepository 接口,data 提供实现,Riverpod 的 overrideWith 完成注入(等同于 Go 的接口注入、C 的函数指针表)。

16.3 目录结构

text
examples/ch16-bookmarks/
├── lib/
│   ├── main.dart                        # ProviderScope + MaterialApp.router
│   └── src/
│       ├── core/config.dart             # --dart-define 注入的配置
│       ├── domain/
│       │   ├── bookmark.dart            # Bookmark 实体 + BookmarkDraft(含校验)
│       │   └── bookmark_repository.dart # 仓储接口 + 远程 API 接口 + SyncException
│       ├── data/
│       │   ├── database.dart            # drift 表、查询、文件位置
│       │   ├── database.g.dart          # 生成
│       │   ├── remote_api.dart          # http 实现
│       │   └── drift_bookmark_repository.dart  # 行 ↔ 实体映射
│       ├── application/providers.dart   # DI + 派生状态 + sync/actions
│       └── presentation/
│           ├── router.dart              # go_router
│           ├── pages/{home,editor,detail}_page.dart
│           └── widgets/{bookmark_tile,empty_state}.dart
├── test/                                # 单元 + widget 测试(20 个)
├── integration_test/app_test.dart       # 真机/桌面端到端(不随 flutter test 跑)
└── pubspec.yaml

对照 Go 项目:domain 类似 internal/model + internal/repository(interface),data 类似 internal/store,application 类似 internal/service,presentation 类似 cmd/ + handler。层名不同,依赖规则一样。

16.4 领域层:实体与校验

dartlib/src/domain/bookmark.dart源文件
// examples/ch16-bookmarks/lib/src/domain/bookmark.dart
@immutable
class Bookmark {
  const Bookmark({
    required this.id,
    required this.title,
    required this.url,
    this.note = '',
    this.favorite = false,
    required this.createdAt,
  });
  // copyWith / == / hashCode ...
}

class BookmarkDraft {
  const BookmarkDraft({required this.title, required this.url, this.note = ''});

  /// 表单校验:返回 null 表示合法。
  String? validate() {
    if (title.trim().isEmpty) return '标题不能为空';
    // 注意:不能用 hasAbsolutePath 判断——`https://a.test` 的 path 是空串,
    // hasAbsolutePath 为 false。正确的检查是 scheme + host。
    final Uri? uri = Uri.tryParse(url.trim());
    if (uri == null || uri.host.isEmpty || (uri.scheme != 'http' && uri.scheme != 'https')) {
      return '需要一个 http(s) 链接';
    }
    return null;
  }
}

真实踩坑:示例第一版用 uri.hasAbsolutePath 判断 URL,结果 https://dart.cn 被判非法(path 为空),保存按钮永远失败。Uri 的语义和直觉不一致,这类校验必须有测试(见 test/repository_test.dart 的"草稿校验")。

仓储接口:

dart
abstract interface class BookmarkRepository {
  Stream<List<Bookmark>> watchAll();
  Future<int> add(BookmarkDraft draft);
  Future<void> setFavorite(int id, {required bool favorite});
  Future<void> delete(int id);
  Future<int> importFromRemote({int limit = 10});
}

abstract interface class BookmarkRemoteApi {
  Future<List<BookmarkDraft>> fetchDrafts({int limit = 10});
}

watchAll() 返回 Stream 而不是 Future<List>:这是离线优先的基石——数据源一变 UI 就变,不需要"手动刷新"。

16.5 数据层:drift + http

表与查询

dartlib/src/data/database.dart源文件
// examples/ch16-bookmarks/lib/src/data/database.dart
@DataClassName('BookmarkRow')     // 改名,避免与领域实体 Bookmark 冲突
class Bookmarks extends Table {
  IntColumn get id => integer().autoIncrement()();
  TextColumn get title => text().withLength(min: 1, max: 200)();
  TextColumn get url => text()();
  TextColumn get note => text().withDefault(const Constant(''))();
  BoolColumn get favorite => boolean().withDefault(const Constant(false))();
  DateTimeColumn get createdAt => dateTime().withDefault(currentDateAndTime)();
}

Stream<List<BookmarkRow>> watchAllRows() => (select(bookmarks)
      ..orderBy(<OrderClauseGenerator<$BookmarksTable>>[
        (t) => OrderingTerm(expression: t.favorite, mode: OrderingMode.desc),
        (t) => OrderingTerm(expression: t.createdAt, mode: OrderingMode.desc),
      ]))
    .watch();

/// 插入(按 url 去重)。返回 (id, created),导入统计时用。
Future<({int id, bool created})> insertRow({
  required String title, required String url, String note = '',
}) async {
  final BookmarkRow? existing = await (select(bookmarks)
        ..where((t) => t.url.equals(url))..limit(1)).getSingleOrNull();
  if (existing != null) return (id: existing.id, created: false);

  final int id = await into(bookmarks).insert(BookmarksCompanion.insert(
    title: title, url: url, note: Value<String>(note)));
  return (id: id, created: true);
}

为什么把 created 一起返回:导入功能需要告诉用户"新增了几条",而 insert 对已存在的 url 会返回旧 id,光看 id 是分不出来的。这类"把语义写进返回值"的设计,比事后查一遍要省事得多。

踩坑:drift 默认把 Bookmarks 表生成的行类叫 Bookmark,与领域实体同名 → 编译期 ambiguous_import。用 @DataClassName('BookmarkRow') 显式改名。

仓储实现:行 ↔ 实体

dartlib/src/data/drift_bookmark_repository.dart源文件
// examples/ch16-bookmarks/lib/src/data/drift_bookmark_repository.dart
@override
Stream<List<Bookmark>> watchAll() => _db.watchAllRows()
    .map((List<BookmarkRow> rows) => rows.map(_toEntity).toList(growable: false));

static Bookmark _toEntity(BookmarkRow row) => Bookmark(
      id: row.id, title: row.title, url: row.url,
      note: row.note, favorite: row.favorite, createdAt: row.createdAt,
    );

映射层看起来很薄,但它让"换存储"变成可能:以后把 drift 换成 sqflite 或远程 API,只改这个文件。

远程 API:把 HTTP 错误翻译成领域异常

dartlib/src/data/remote_api.dart源文件
// examples/ch16-bookmarks/lib/src/data/remote_api.dart
final http.Response response = await client
    .get(uri, headers: {'Accept': 'application/json'})
    .timeout(config.requestTimeout);

if (response.statusCode < 200 || response.statusCode >= 300) {
  throw SyncException('服务器返回 ${response.statusCode}');
}
final Object? decoded = jsonDecode(utf8.decode(response.bodyBytes));

错误一律是 SyncException(领域异常),UI 层只显示它的 message——不会看到 SocketException/FormatException 这种东西(ch13 的原则)。

16.6 应用层:依赖注入与派生状态

dartlib/src/application/providers.dart源文件
// examples/ch16-bookmarks/lib/src/application/providers.dart
final appConfigProvider = Provider<AppConfig>((Ref ref) => AppConfig.fromEnvironment());

final httpClientProvider = Provider<http.Client>((Ref ref) {
  final http.Client client = http.Client();
  ref.onDispose(client.close);
  return client;
});

final databaseProvider = Provider<AppDatabase>((Ref ref) {
  final AppDatabase db = AppDatabase.open();   // LazyDatabase,不阻塞启动
  ref.onDispose(db.close);
  return db;
});

final remoteApiProvider = Provider<BookmarkRemoteApi>((Ref ref) => HttpBookmarkRemoteApi(
      client: ref.watch(httpClientProvider),
      config: ref.watch(appConfigProvider),
    ));

final repositoryProvider = Provider<BookmarkRepository>((Ref ref) => DriftBookmarkRepository(
      ref.watch(databaseProvider), ref.watch(remoteApiProvider),
    ));

依赖链是声明式的:repositoryProvider 只是说"我需要数据库和远程 API",Riverpod 负责按需创建、缓存、在无人使用时销毁。测试里替换最底层(数据库/远程 API),上面整条链自动用替身。

派生状态:

dart
final bookmarksProvider = StreamProvider<List<Bookmark>>(
  (Ref ref) => ref.watch(repositoryProvider).watchAll(),
);

final filteredBookmarksProvider = Provider<AsyncValue<List<Bookmark>>>((Ref ref) {
  final String query = ref.watch(searchQueryProvider).trim().toLowerCase();
  return ref.watch(bookmarksProvider).whenData((List<Bookmark> items) {
    if (query.isEmpty) return items;
    return items.where((Bookmark b) =>
        b.title.toLowerCase().contains(query) ||
        b.note.toLowerCase().contains(query) ||
        b.url.toLowerCase().contains(query)).toList(growable: false);
  });
});

whenData 让 AsyncValue 的 loading/error 状态原样穿过,只对 data 做变换——这比手写三态判断少一大坨代码。

同步状态:把"进行中/失败/成功"建模成状态

dart
class SyncState {
  const SyncState({this.running = false, this.error, this.lastImported});
  final bool running;
  final String? error;
  final int? lastImported;
}

class SyncNotifier extends Notifier<SyncState> {
  @override
  SyncState build() => const SyncState();

  Future<void> run() async {
    if (state.running) return;                 // 防重复点击
    state = const SyncState(running: true);
    try {
      final int imported = await ref.read(repositoryProvider).importFromRemote(limit: 10);
      state = SyncState(lastImported: imported);
    } on SyncException catch (e) {
      state = SyncState(error: e.message);
    }
  }
}

注意 state = SyncState(...) 每次都是新对象(不可变更新,ch11 的规矩)。

16.7 路由:go_router

dartlib/src/presentation/router.dart源文件
// examples/ch16-bookmarks/lib/src/presentation/router.dart
final routerProvider = Provider<GoRouter>((Ref ref) {
  final GoRouter router = GoRouter(
    initialLocation: '/',
    routes: <RouteBase>[
      GoRoute(
        path: '/',
        builder: (BuildContext context, GoRouterState state) => const HomePage(),
        routes: <RouteBase>[
          GoRoute(path: 'new', builder: (_, __) => const EditorPage()),
          GoRoute(
            path: 'bookmark/:id',
            builder: (BuildContext context, GoRouterState state) =>
                DetailPage(id: int.tryParse(state.pathParameters['id'] ?? '') ?? -1),
          ),
        ],
      ),
    ],
    errorBuilder: (BuildContext context, GoRouterState state) => const NotFoundPage(),
  );
  ref.onDispose(router.dispose);
  return router;
});
项 Navigator 1.0(ch09) go_router
路由表 routes map + onGenerateRoute 声明式树,一个地方看全
参数 arguments 是 Object? 路径参数 :id + state.pathParameters
深链接 需要额外配置 天然支持(/bookmark/3)
返回 Navigator.pop context.pop()
测试 push 流程 直接 go('/bookmark/3')

16.8 UI:三件必须做好的事

① 空状态要区分"没有数据"和"搜不到"

dart
if (items.isEmpty) {
  final bool searching = ref.watch(searchQueryProvider).trim().isNotEmpty;
  return EmptyState(
    message: searching ? '没有匹配「${ref.watch(searchQueryProvider)}」的书签' : '还没有书签',
    hint: searching ? '换个关键字试试' : '点右下角 + 新建,或用右上角从远程导入',
  );
}

用户分不清这两种情况,就会以为数据丢了。

② 表单校验放在领域层,UI 只负责显示

dart
validator: (String? v) {
  final Uri? uri = Uri.tryParse((v ?? '').trim());
  if (uri == null || uri.host.isEmpty || !(uri.scheme == 'http' || uri.scheme == 'https')) {
    return '需要 http(s) 链接';
  }
  return null;
}

BookmarkDraft.validate() 和表单 validator 是同一套规则——真实项目应该抽成共用函数(示例中两处保持字面一致,注释里也标了原因)。

③ 删除要有确认,且删除后要正确处理"数据已不存在"

dart
if (b == null) {
  return Center(child: Text('书签不存在(可能已被删除)', key: Key('missing')));
}

详情页监听的是同一个 bookmarksProvider。如果别的页面删除了这条书签,详情页会立刻变成"不存在"——这比显示一堆 null 崩溃好得多。

16.9 测试策略(上):单元 + widget

层次 测什么 怎么 mock
远程 API URL 拼装、状态码、JSON 映射、超时 MockClient
仓储 增删查、去重、导入统计、排序 AppDatabase.memory() + FakeRemoteApi
领域 校验规则 纯函数,直接调
UI 空状态、新建流程、搜索、收藏、删除、404 ProviderScope(overrides: [...])
dart
Widget testApp({required AppDatabase db, required BookmarkRemoteApi remote}) => ProviderScope(
      overrides: [
        databaseProvider.overrideWithValue(db),
        remoteApiProvider.overrideWithValue(remote),
      ],
      child: const BookmarksApp(),
    );

只替换最底层,上面的 providers、路由、页面全是真实代码——这就是分层的回报:装配成本极低。

16.10 运行与验证

bash
cd examples/ch16-bookmarks
flutter pub get
dart run build_runner build
flutter analyze     # No issues found!
flutter test        # All tests passed! (20 个用例)

flutter run -d macos
flutter build macos --debug

本次真实验证:

text
✓ Built build/macos/Build/Products/Debug/ch16_bookmarks.app
flutter: The Dart VM service is listening on http://127.0.0.1:51094/...

$ find ~/Library/Containers -name "bookmarks.sqlite"
.../com.dartbook.ch16Bookmarks/Data/Library/Application Support/.../bookmarks.sqlite

界面上可以完成:新建 → 搜索 → 收藏 → 进详情 → 删除 → 右上角从 jsonplaceholder 导入(需要联网)。

附:C/Go 代码对照:分层装配

go
// Go:main 负责装配,service 只依赖接口
type Repository interface {
    WatchAll(ctx context.Context) (<-chan Bookmark, error)
    Add(ctx context.Context, d Draft) (int, error)
}

type Service struct{ repo Repository }

func main() {
    db := store.Open("bookmarks.sqlite")
    repo := store.NewBookmarkRepo(db)     // 实现 Repository
    svc := service.NewBookmarkService(repo) // 只依赖接口
    mux := http.NewServeMux()
    mux.HandleFunc("/bookmarks", handler.List(svc))
    log.Fatal(http.ListenAndServe(":8080", mux))
}
dart
// Flutter / Riverpod:装配写在 provider 里,UI 只 watch
final databaseProvider = Provider<AppDatabase>((ref) {
  final db = AppDatabase.open();
  ref.onDispose(db.close);
  return db;
});

final repositoryProvider = Provider<BookmarkRepository>(
  (ref) => DriftBookmarkRepository(ref.watch(databaseProvider), ref.watch(remoteApiProvider)),
);

final bookmarksProvider = StreamProvider<List<Bookmark>>(
  (ref) => ref.watch(repositoryProvider).watchAll(),
);

结构完全同构:main ↔ provider 图,interface ↔ 抽象类,NewService(repo) ↔ ref.watch(repositoryProvider),测试注入 ↔ overrideWith。区别只是 Flutter 还要把"数据变化"传播到 UI。

16.11 本章小结 + C/Go 对照清单

主题 Go C Flutter 项目 陷阱
目录分层 internal/{model,store,service} include/src + 头文件 domain/data/application/presentation 跨层 import
接口注入 interface + 构造注入 函数指针表 Riverpod overrideWith 在 UI 里 new 数据库
配置 flag / env getenv --dart-define + AppConfig 把密钥写进代码
路由 http.ServeMux 手写分发 go_router 路径参数强转失败
数据一致性 事务 事务 drift 事务/watch 手动刷新列表
校验 手写 if 手写 if 领域方法 + 表单 validator Uri 语义踩坑

三句话:

  1. 分层不是为了好看,是为了能替换、能测试:本例替换一个 provider 就能测整个 App。
  2. watch()(流式数据)是离线优先的核心,别用 Future + 手动刷新。
  3. 领域层保持纯净(不 import Flutter/drift/http),它就能被复用、被快速单测。

下一章(下):测试金字塔的完整形态、性能优化与真机验证、打包发布——把这个项目真正交付出去。