综合项目(上):架构设计、数据层、依赖注入
第 16 章 · 综合项目(上):架构设计、数据层、依赖注入
run
$cd examples/ch16-bookmarks && flutter run -d macos已验证
- flutter analyze 0 告警、flutter test 20 个用例全绿、debug 与 **release** 构建均真实启动成功
- 完整工程已打包:打包下载
本章目录 · 19 节
- 16.1 需求与验收标准
- 16.2 分层:依赖只能单向流动
- 16.3 目录结构
- 16.4 领域层:实体与校验
- 16.5 数据层:drift + http
- 表与查询
- 仓储实现:行 ↔ 实体
- 远程 API:把 HTTP 错误翻译成领域异常
- 16.6 应用层:依赖注入与派生状态
- 同步状态:把"进行中/失败/成功"建模成状态
- 16.7 路由:go_router
- 16.8 UI:三件必须做好的事
- ① 空状态要区分"没有数据"和"搜不到"
- ② 表单校验放在领域层,UI 只负责显示
- ③ 删除要有确认,且删除后要正确处理"数据已不存在"
- 16.9 测试策略(上):单元 + widget
- 16.10 运行与验证
- 附:C/Go 代码对照:分层装配
- 16.11 本章小结 + C/Go 对照清单
从这一章开始,我们不再讲"单个知识点",而是把前 15 章的零件拼成一个能交付的应用:离线优先的书签管理器。
16.1 需求与验收标准
| 功能 | 验收 |
|---|---|
| 书签列表(收藏优先、按创建时间倒序) | 有 0/1/N 条都正确显示 |
| 新建(标题必填、URL 必须是 http(s)) | 非法输入不落库 |
| 搜索标题/备注/链接 | 命中过滤,空结果有区分文案 |
| 收藏 / 取消收藏 | 立即生效并持久化 |
| 删除(带确认) | 删除后列表与详情一致 |
| 从远程导入 | 去重、失败不污染本地数据 |
| 离线可用 | 断网时列表照常(SQLite 是唯一数据源) |
技术栈就是前面各章的组合:Riverpod(状态/DI)+ drift(持久化)+ http(网络)+ go_router(路由),没有引入任何新概念。
16.2 分层:依赖只能单向流动
presentation/ (pages/widgets:只认识 providers)
│
▼
application/ (providers:DI、派生状态、actions)
│
▼
domain/ (实体 + 仓储接口:不依赖 Flutter/drift/http)
▲
│
data/ (drift/http 实现:唯一 import 数据库和网络的地方)
三条铁律:
- domain 不 import 任何实现(连
drift都不行)。这样领域逻辑可以被任何数据源复用,测试也不需要搭数据库。 - presentation 不 import data。UI 只
ref.watch(...),永远不AppDatabase/http.Client直连。 - 依赖方向指向抽象:
application依赖BookmarkRepository接口,data提供实现,Riverpod 的overrideWith完成注入(等同于 Go 的接口注入、C 的函数指针表)。
16.3 目录结构
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 领域层:实体与校验
// 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的"草稿校验")。
仓储接口:
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
表与查询
// 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')显式改名。
仓储实现:行 ↔ 实体
// 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 错误翻译成领域异常
// 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 应用层:依赖注入与派生状态
// 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),上面整条链自动用替身。
派生状态:
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 做变换——这比手写三态判断少一大坨代码。
同步状态:把"进行中/失败/成功"建模成状态
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
// 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:三件必须做好的事
① 空状态要区分"没有数据"和"搜不到"
if (items.isEmpty) {
final bool searching = ref.watch(searchQueryProvider).trim().isNotEmpty;
return EmptyState(
message: searching ? '没有匹配「${ref.watch(searchQueryProvider)}」的书签' : '还没有书签',
hint: searching ? '换个关键字试试' : '点右下角 + 新建,或用右上角从远程导入',
);
}
用户分不清这两种情况,就会以为数据丢了。
② 表单校验放在领域层,UI 只负责显示
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 是同一套规则——真实项目应该抽成共用函数(示例中两处保持字面一致,注释里也标了原因)。
③ 删除要有确认,且删除后要正确处理"数据已不存在"
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: [...]) |
Widget testApp({required AppDatabase db, required BookmarkRemoteApi remote}) => ProviderScope(
overrides: [
databaseProvider.overrideWithValue(db),
remoteApiProvider.overrideWithValue(remote),
],
child: const BookmarksApp(),
);
只替换最底层,上面的 providers、路由、页面全是真实代码——这就是分层的回报:装配成本极低。
16.10 运行与验证
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
本次真实验证:
✓ 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: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))
}
// 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 语义踩坑 |
三句话:
- 分层不是为了好看,是为了能替换、能测试:本例替换一个 provider 就能测整个 App。
watch()(流式数据)是离线优先的核心,别用Future+ 手动刷新。- 领域层保持纯净(不 import Flutter/drift/http),它就能被复用、被快速单测。
下一章(下):测试金字塔的完整形态、性能优化与真机验证、打包发布——把这个项目真正交付出去。