Chili Labs Flutter 测试任务实战:基于 Giphy API 的 GIF 搜索应用完整实现指南

原创2026-10-09 21:08:452,159 阅读
文章标签:教程

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)

任务原文还包含四条直接影响交付方式的约束:

  1. 无时间限制,质量优先(No time limit. Quality > Speed)——不必赶工,架构与可读性比速度重要;
  2. 以 Giphy 官方 API 文档为准——请求参数、响应结构以 Giphy 开发者文档为准(原文指向 developers.giphy.com/docs/api);
  3. UI 自由发挥——除清单列出的强制项外,视觉与交互细节可自行设计;
  4. README 必须注明 Flutter 版本(Flutter version MUST be noted in repository ReadMe file)——这是硬性要求;
  5. 未完成项需说明——若某项主需求未能完成,必须在代码注释中写明尝试过什么方案、结果如何;
  6. 交付方式——回复发送任务的邮件或 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"的工程含义是:屏幕旋转后应用不崩溃、网格重排且交互可用。落地要点:

  1. 自适应网格:优先用 SliverGridDelegateWithMaxCrossAxisExtent(按可用宽度推导列数)而非固定列数,横屏自然从 2 列变为更多列;
  2. 依赖 MediaQuery:获取 MediaQuery.of(context).orientation 或 size 来决定边距、详情页图文排布(竖屏上下堆叠、横屏左右并排);
  3. 状态不随旋转丢失:搜索词、结果列表、offset 都保存在状态层(Cubit/Riverpod),而非 Widget 局部变量,旋转时状态自然保留;
  4. 在 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"给足了自由度,建议优先覆盖风险最高、收益最大的三层:

  1. 模型解析测试:给定 Giphy 响应 JSON fixture,验证 GifItem.fromJson 字段映射正确,缺失字段不会抛异常;
  2. 仓储/客户端测试:用 mocktail mock http.Client,验证请求 URL 中 q、limit、offset 参数正确,非 200 响应抛出预期异常;
  3. 状态管理测试:用 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)。

登录后查看全文
ru-test-assignments