Chili Labs Flutter 测试任务实战:基于 Giphy API 的 GIF 搜索应用完整实现指南
Chili Labs Flutter 测试任务实战:基于 Giphy API 的 GIF 搜索应用完整实现指南
本指南以 ru-test-assignments 仓库 收录的 Chili Labs Flutter 开发测试任务 为蓝本,从任务验收标准出发,给出一个可运行的 GIF 搜索应用的端到端实现方案:涵盖防抖自动搜索、无限滚动分页、网格与详情双视图、横竖屏适配、错误处理,以及 BLoC/Riverpod 状态管理、Coordinator 导航模式、网络可用性检测与单元测试等加分项。
读完本文,你将掌握如何把一份面向 iOS 与 Android 双平台的 Flutter 测试任务,拆解为清晰的技术清单,并逐项落实到可提交评审的工程代码与 README 交付物。
任务全景:你要交付什么
原始任务只用一句话定义了产品形态:基于 Giphy 服务创建一个 GIF 搜索应用(原文 Create a gif search application using the Giphy service)。但真正决定工作量的,是紧随其后的 Primary Requirements——它们被划分为"技术"与"UI"两组硬性验收点,外加一组明确的加分项。交付前建议把下面三张清单当作自己的验收标准逐条核对。
技术要求清单(Primary Requirements – Technical)
| 要求 | 原文 | 验收要点 |
|---|---|---|
| 双平台 | Primary platforms - iOS & Android | 一份 Flutter 代码需同时覆盖 iOS 与 Android,且均能正常编译运行 |
| 自动搜索 | Auto search – requests ... automatically with a small delay after user stops typing | 用户停止输入后延迟发起请求(防抖 Debounce),而非每次按键都请求 |
| 分页 | Pagination – loading more results when scrolling | 滚动接近底部时自动加载下一页结果 |
| 横竖屏 | Vertical & horizontal orientation support | 旋转屏幕后布局不崩坏,网格仍可正常浏览 |
| 错误处理 | Error handling | API 失败、超时等异常需被捕获并反馈给用户 |
| 单元测试 | Unit tests – as much as you see fit | 对核心逻辑(防抖、分页、仓储层)编写单测,数量自定 |
UI 要求清单(Primary Requirements – UI)
| 要求 | 原文 | 验收要点 |
|---|---|---|
| 平台规范 | Responsive & matching platform guidelines | 布局自适应,符合 iOS/Android 平台交互习惯 |
| 双视图 | At least 2 views sourced by data from Giphy | 至少两个页面:搜索结果列表页 + GIF 详情页 |
| 网格布局 | Results are displayed in a grid | 结果以网格(Grid)而非列表呈现 |
| 详情导航 | Clicking on a grid item should navigate to a detailed Gif view | 点击网格项进入 GIF 详情视图 |
| 加载指示 | Loading indicators | 初次加载与分页加载都要有可见的 loading 状态 |
| 错误展示 | Error display | 错误要有 UI 呈现,而非静默失败 |
加分项(Bonus points)
- 状态管理:使用 BLoC(flutter_bloc)、Riverpod 等状态管理方案或库;
- 架构模式:采用清晰易懂的架构分层(如 Clean Architecture、Repository + UseCase);
- 导航解耦:页面导航与页面 Widget 代码分离,采用 Coordinator 模式或类似方案;
- 网络可用性:处理断网/离线状态,例如给出离线提示或引导重试。
交付规则与约束(Notes)
任务原文还包含四条直接影响交付方式的约束:
- 无时间限制,质量优先(No time limit. Quality > Speed)——不必赶工,架构与可读性比速度重要;
- 以 Giphy 官方 API 文档为准——请求参数、响应结构以 Giphy 开发者文档为准(原文指向
developers.giphy.com/docs/api); - UI 自由发挥——除清单列出的强制项外,视觉与交互细节可自行设计;
- README 必须注明 Flutter 版本(Flutter version MUST be noted in repository ReadMe file)——这是硬性要求;
- 未完成项需说明——若某项主需求未能完成,必须在代码注释中写明尝试过什么方案、结果如何;
- 交付方式——回复发送任务的邮件或
studio@chililabs.io,附上公开可访问的仓库链接与个人简历(CV)。
技术选型:一份代码覆盖 iOS 与 Android
Flutter 天然契合"Primary platforms - iOS & Android"的要求:flutter create 生成的项目直接产出双端工程,一份 Dart 代码即可完成双平台交付,同时满足"Responsive & matching platform guidelines"中跨平台自适应的大前提。
项目的 pubspec.yaml 是依赖清单的起点。以下是一个贴合任务需求的参考声明(版本号按安装时的最新稳定版调整):
name: giphy_search
description: Chili Labs Flutter test task - Giphy GIF search app.
environment:
sdk: ">=3.0.0 <4.0.0"
dependencies:
flutter:
sdk: flutter
http: ^1.1.0 # 轻量 HTTP 客户端,调用 Giphy API
flutter_bloc: ^8.1.3 # 状态管理(加分项 1)
equatable: ^2.0.5 # 便于 Bloc 状态相等性比较
connectivity_plus: ^5.0.2 # 网络可用性检测(加分项 4)
cached_network_image: ^3.3.0 # 网格中高效加载 GIF 缩略/动图
dev_dependencies:
flutter_test:
sdk: flutter
bloc_test: ^9.1.5 # Bloc 单元测试辅助
mocktail: ^1.0.1 # 仓储/客户端层 mock
按任务约束,还需在仓库根目录的 README.md 中明确写出 Flutter 版本(例如记录 flutter --version 的完整输出或至少注明 major.minor.patch)。
数据层:Giphy 客户端、模型与仓储
任务要求数据全部来自 Giphy 服务,因此数据层是整条链路的地基。按 Giphy API 文档的通用约定,搜索与热门接口的分页均由 limit / offset 控制,响应体包含 data(结果数组)与 pagination(分页元数据)。为了可测试,建议把"网络客户端 → 数据模型 → 仓储"三层分开。
首先是模型与客户端(参考实现):
class GifItem {
final String id;
final String title;
final String previewUrl; // 网格用的小尺寸动图地址
final String detailUrl; // 详情页用的高清动图地址
const GifItem({
required this.id,
required this.title,
required this.previewUrl,
required this.detailUrl,
});
factory GifItem.fromJson(Map<String, dynamic> json) {
final images = json['images'] as Map<String, dynamic>;
return GifItem(
id: json['id'] as String,
title: (json['title'] as String?) ?? '',
previewUrl: (images['fixed_width'] as Map<String, dynamic>)['url'] as String,
detailUrl: (images['original'] as Map<String, dynamic>)['url'] as String,
);
}
}
class GiphyClient {
final http.Client _http;
final String apiKey;
GiphyClient({required this.apiKey, http.Client? http})
: _http = http ?? http.Client();
Future<SearchResult> search({
required String query,
int limit = 20,
int offset = 0,
}) async {
final uri = Uri.parse(
'https://api.giphy.com/v1/gifs/search',
).replace(queryParameters: {
'api_key': apiKey,
'q': query,
'limit': '$limit',
'offset': '$offset',
});
final response = await _http.get(uri);
if (response.statusCode != 200) {
throw GiphyException(response.statusCode);
}
return SearchResult.fromJson(
jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>,
);
}
}
仓储层再包一层,把"分页游标(当前 offset)"与"下一页是否还有数据"的判定收敛到一处,供上层状态管理调用:
class GiphyRepository {
GiphyRepository(this._client);
final GiphyClient _client;
Future<SearchPage> searchPage(String query, int offset, {int limit = 20}) async {
final result = await _client.search(query: query, limit: limit, offset: offset);
return SearchPage(
items: result.items,
hasMore: offset + result.items.length < result.totalCount,
);
}
}
将网络层收敛在 Repository 之后,单元测试就可以用 mock 的 GiphyClient 精确验证分页与异常分支,而不必触碰真实网络。
自动搜索:用户停止输入后的防抖请求
"停止输入后延迟请求"本质是 debounce(防抖)。Flutter 中最直接的实现是 Timer:每次输入变化都取消上一个 Timer,重新开启一个短延迟的 Timer,只有用户真正停顿后 Timer 才到期并触发搜索。同任务的 Android 版本 给出了 300–500ms 的经验区间,Flutter 侧同样适用。
防抖应放在状态管理层而非 Widget 里,保证可单测。以下是一个基于 flutter_bloc 的 Cubit 参考实现:
class SearchCubit extends Cubit<SearchState> {
SearchCubit(this._repository) : super(const SearchState.initial());
final GiphyRepository _repository;
Timer? _debounce;
int _offset = 0;
void onQueryChanged(String query) {
_debounce?.cancel();
_debounce = Timer(const Duration(milliseconds: 350), () => _search(query));
}
Future<void> _search(String query) async {
if (query.trim().isEmpty) {
emit(const SearchState.initial());
return;
}
emit(SearchState.loading());
try {
_offset = 0;
final page = await _repository.searchPage(query, _offset);
emit(SearchState.success(items: page.items, hasMore: page.hasMore));
} on Exception {
emit(const SearchState.error('搜索失败,请检查网络后重试'));
}
}
@override
void close() {
_debounce?.cancel();
super.close();
}
}
注意两个细节:其一,close() 里必须取消未触发的 Timer,否则测试与页面销毁时会出现泄漏;其二,防抖逻辑被放在 Cubit 中后,可以直接用 fakeAsync / tester.pump(Duration(...)) 验证"输入→等待→仅发一次请求"的行为。
无限滚动分页:滚动到底加载更多
分页要求在滚动过程中持续加载更多结果。常见做法是给 ScrollController 挂监听:当滚动位置接近内容底部(如超过 maxScrollExtent 的 80%)且当前没有正在加载、还有下一页时,触发下一页请求。依旧把逻辑收敛在状态层,Widget 只负责上报滚动事件:
class SearchCubit extends Cubit<SearchState> {
// ...接上文
void onScrollNearEnd() {
final current = state;
if (current is! SearchSuccess || !current.hasMore || current.isLoadingMore) return;
_loadMore();
}
Future<void> _loadMore() async {
_offset += 20;
emit(state.copyWith(isLoadingMore: true));
try {
final page = await _repository.searchPage(_query, _offset);
emit((state as SearchSuccess).append(page));
} on Exception {
emit(state.copyWith(isLoadingMore: false, loadMoreFailed: true));
}
}
}
分页状态需要与防抖状态互相配合:换关键词时必须重置 offset 与结果列表,否则新关键词会接在旧结果的尾巴上;滚动加载失败时则应允许"滚动再触发一次重试",而不是直接丢弃。
UI:网格、详情视图与加载/错误态
网格结果页
结果用 GridView.builder 呈现,配合 ScrollController 触发分页:
GridView.builder(
controller: _scrollController,
padding: const EdgeInsets.all(8),
gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
maxCrossAxisExtent: 200, // 自适应列数,兼顾横竖屏
mainAxisSpacing: 8,
crossAxisSpacing: 8,
),
itemCount: items.length + (hasMore ? 1 : 0), // 末尾留一个加载占位
itemBuilder: (context, index) {
if (index >= items.length) return const _GridLoader(); // 分页 loading
return _GifTile(item: items[index], onTap: () => onItemTap(items[index]));
},
)
满足"至少两个视图"要求的最简拆分是:SearchScreen(网格) 与 GifDetailScreen(详情)。点击网格项通过导航层进入详情页,详情页展示大尺寸动图与标题信息。
加载与错误状态
任务要求 Loading indicators 与 Error display 同时覆盖。建议把状态机显式建模,UI 按状态分支渲染:
SearchState.loading()→ 居中CircularProgressIndicator(初次加载);SearchState.success()→ 网格 + 底部_GridLoader(分页加载);SearchState.error()→ 错误提示视图 + "重试"按钮;- 下拉刷新或重试时回到 loading,再进入 success/error。
错误视图至少要给出可理解的文案与重试入口,满足"错误要有 UI 呈现"的验收点。
横竖屏适配
"Vertical & horizontal orientation support"的工程含义是:屏幕旋转后应用不崩溃、网格重排且交互可用。落地要点:
- 自适应网格:优先用
SliverGridDelegateWithMaxCrossAxisExtent(按可用宽度推导列数)而非固定列数,横屏自然从 2 列变为更多列; - 依赖
MediaQuery:获取MediaQuery.of(context).orientation或size来决定边距、详情页图文排布(竖屏上下堆叠、横屏左右并排); - 状态不随旋转丢失:搜索词、结果列表、offset 都保存在状态层(Cubit/Riverpod),而非 Widget 局部变量,旋转时状态自然保留;
- 在
MaterialApp保持默认的旋转支持,不要在SystemChrome里强制锁定方向。
状态管理落地:BLoC 与 Riverpod 两种示例
任务明确点名了 BLoC(flutter_bloc)与 Riverpod,二者择一即可。上文已展示 Cubit 形态;如果用 Riverpod,防抖可以收敛为一个可组合的 provider:
final searchQueryProvider = StateProvider<String>((ref) => '');
final debounceProvider = Provider<Debouncer>((ref) => Debouncer(
duration: const Duration(milliseconds: 350),
onFire: (String query) => ref.read(searchResultsProvider.notifier).search(query),
));
无论选哪种,核心要求是同一个:状态管理必须承载防抖、分页、加载/错误状态机,让 Widget 保持"纯渲染 + 事件上报"的薄层。这也直接呼应了加分项里"清晰易懂的架构"。
导航协调器:把导航从 Widget 代码中剥离
加分项要求"Page navigation is separate from page widget code (a Coordinator pattern or similar)"。常规 Navigator.push 直接写在 onTap 回调里虽然简单,但会让导航逻辑散落在各个 Widget。Coordinator 的思路是把"跳转哪个页面、传什么参数"收拢到独立对象,Widget 只调用一个方法:
class AppCoordinator {
AppCoordinator(this._navigatorKey);
final GlobalKey<NavigatorState> _navigatorKey;
void openSearch() {
_navigatorKey.currentState!.pushReplacement(
MaterialPageRoute<void>(builder: (_) => const SearchScreen()),
);
}
void openGifDetail(GifItem item) {
_navigatorKey.currentState!.push(
MaterialPageRoute<void>(
builder: (_) => GifDetailScreen(item: item),
),
);
}
}
通过 InheritedWidget 或 Provider 把 AppCoordinator 注入 Widget 树,网格项的 onTap 只写一行 coordinator.openGifDetail(item)。好处是导航流程可读、可复用、可独立测试,也便于后续接入深层链接或路由库。
网络可用性处理
加分项要求处理断网场景。常用方案是用 connectivity_plus 监听网络状态流,在断网时展示离线横幅(如 MaterialBanner/SnackBar),恢复后自动隐藏并允许重试:
StreamBuilder<ConnectivityResult>(
stream: Connectivity().onConnectivityChanged,
builder: (context, snapshot) {
final online = snapshot.data != ConnectivityResult.none;
return Column(
children: [
if (!online) const OfflineBanner(), // 顶部离线提示
Expanded(child: searchBody(online: online)),
],
);
},
)
离线提示与"错误显示"可以联动:请求失败时若已知处于离线状态,优先提示"网络不可用",而不是笼统的"请求失败"。
单元测试策略:测什么、怎么测
"Unit tests - as much as you see fit"给足了自由度,建议优先覆盖风险最高、收益最大的三层:
- 模型解析测试:给定 Giphy 响应 JSON fixture,验证
GifItem.fromJson字段映射正确,缺失字段不会抛异常; - 仓储/客户端测试:用
mocktailmockhttp.Client,验证请求 URL 中q、limit、offset参数正确,非 200 响应抛出预期异常; - 状态管理测试:用
bloc_test+fakeAsync验证防抖只发一次请求、分页追加结果、加载失败进入 error 状态:
test('debounce 后仅发起一次搜索请求', () {
final client = MockGiphyClient();
when(() => client.search(query: any(named: 'query'), limit: any(named: 'limit'), offset: any(named: 'offset')))
.thenAnswer((_) async => fakePage);
final cubit = SearchCubit(GiphyRepository(client));
cubit.onQueryChanged('flut');
cubit.onQueryChanged('flutt');
cubit.onQueryChanged('flutter');
verify(client.search(query: 'flutter', ...), times: 1);
});
再配合少量 Widget test(网格渲染、错误视图出现/重试)即可覆盖任务中的 UI 验收点。
完成度自查与交付清单
提交前对照下表逐项自检,并把结果写进仓库 README:
| 任务要求 | 验收点 | 自查 |
|---|---|---|
| iOS & Android | 双平台编译通过 | ☐ |
| 自动搜索(防抖) | 停止输入 300–500ms 后发起一次请求 | ☐ |
| 分页 | 滚动到底加载更多,且不重复加载 | ☐ |
| 横竖屏 | 旋转后布局自适应、状态保留 | ☐ |
| 错误处理 | API 失败有 UI 反馈与重试 | ☐ |
| 至少 2 个视图 | 网格列表 + GIF 详情 | ☐ |
| 网格布局 | GridView 呈现结果 | ☐ |
| 详情导航 | 点击网格项进入详情 | ☐ |
| 加载指示 | 初次加载与分页加载均有指示 | ☐ |
| 错误展示 | 错误视图可见 | ☐ |
| 状态管理 | BLoC / Riverpod 承载状态机 | ☐(加分) |
| 架构模式 | 分层清晰、可读 | ☐(加分) |
| Coordinator | 导航与 Widget 代码分离 | ☐(加分) |
| 网络可用性 | 离线提示与恢复 | ☐(加分) |
| 单元测试 | 防抖/分页/仓储至少覆盖核心逻辑 | ☐ |
| README 注明 Flutter 版本 | 记录 flutter --version | ☐(强制) |
| 未完成项说明 | 注释或 README 写明尝试与结果 | ☐(强制) |
最后按任务要求交付:回复发送任务的邮件或 studio@chililabs.io,附上公开仓库链接(仓库需包含 README、代码与测试)与 CV。
延伸:同一任务在 Android / iOS 的对照版本
这份 Flutter 任务并非孤立存在——Chili Labs 在 other/chili-labs 目录下为同一款 Giphy GIF 搜索应用发布了多平台版本,对照阅读可以反哺 Flutter 方案的细节:
- Android 版任务:明确了 Kotlin + Compose、MVVM/MVI、Hilt/Koin、Retrofit/Ktor、Coroutines 的固定技术栈,且对防抖给出 300–500ms 的量化建议;
- iOS 版任务:要求 Swift、禁用第三方网络库、推荐 RxSwift/Combine 响应式方案。
对比可见,Flutter 版任务刻意不锁死技术栈,把"状态管理、架构、导航解耦、网络可用性"留给候选人自行决策——这正是 Flutter 生态开放性的体现,也是面试官考察工程判断力的地方。若想在同一仓库里再练手一个 Flutter 方向的难题,还可参考 Smartlook 的 Flutter 面试测试任务(从 Flutter 渲染树中提取当前屏幕元素树并输出 JSON)。