AtomGit Flutter鸿蒙客户端：仓库搜索

概述

搜索是代码托管平台最核心的功能之一。用户通过搜索发现感兴趣的开源项目、查找特定技术栈的代码库、或者评估技术方案的社区活跃度。AtomGit Flutter 客户端实现了全功能仓库搜索，包括关键词检索、排序筛选、无限滚动分页，以及多搜索入口的交互设计。

搜索入口的多场景设计

应用中有四个不同的搜索触发点，各有不同的交互行为和适用场景：

首页搜索栏

首页搜索栏的位置设计考虑了两种用户状态：

未登录时，搜索栏位于欢迎页的引导按钮下方，访客无需登录即可搜索。这是一种低门槛设计——让用户先体验核心功能，再决定是否登录。

// 首页搜索栏（未登录页面中）TextField(decoration:InputDecoration(hintText:'搜索仓库...',prefixIcon:constIcon(Icons.search),),onSubmitted:(value){if(value.trim().isNotEmpty){Navigator.pushNamed(context,'/search',arguments:value.trim(),);}},)

已登录时，搜索栏位于 AppBar 的操作区，通过搜索图标按钮触发。这是为了在已登录首页中节省垂直空间（已登录首页需要展示用户仓库和热门仓库两个区域）。

发现 Tab 搜索

发现 Tab 的搜索栏设计为内嵌搜索——不需要导航到独立页面：

// 发现 Tab 中的搜索（Tab 内直接搜索）TextField(onSubmitted:(value){if(value.trim().isNotEmpty){context.read<ExploreProvider>().search(value.trim());}},)

这种就地搜索的体验更流畅——用户不需要离开当前 Tab，搜索结果直接在输入框下方展示。

搜索页面

搜索页面是最完整的搜索入口，拥有独立的页面空间和专有的 Provider：

classSearchScreenextendsStatelessWidget{@overrideWidgetbuild(BuildContextcontext){finalquery=ModalRoute.of(context)!.settings.argumentsasString???'';finalisLoggedIn=context.read<AuthProvider>().isLoggedIn;returnChangeNotifierProvider(create:(_)=>RepoSearchProvider(context.read<AtomGitApiClient>(),)..search(query),child:_SearchBody(query:query,isLoggedIn:isLoggedIn),);}}

搜索页面接收上一页传来的query参数，在创建 Provider 时立即通过..search(query)触发首次搜索。如果 query 为空，Provider 不会发起 API 请求（search()方法内部有空值检查）。

搜索 API 的设计

搜索 API 使用 AtomGit 的仓库搜索端点：

finalresponse=await_apiClient.get('/search/repositories',queryParams:{'q':query,'sort':'stars','order':'desc','per_page':'30','page':page.toString(),},);

查询参数详解

q（查询关键词）：这是核心参数。AtomGit 的搜索语法支持多种限定符：

• 关键词搜索：flutter匹配仓库名和描述中的 flutter
• 语言过滤：language:dart只搜索 Dart 项目
• 组合搜索：flutter language:dart stars:>100搜索星级超过 100 的 Dart Flutter 项目

当前的实现使用纯文本搜索（用户输入什么就发什么），但架构上支持未来扩展高级搜索语法。

sort（排序字段）：支持三种排序依据：

order（排序方向）：desc（降序）或asc（升序）。默认使用降序，将最热/最新的仓库排在最前面。

per_page（每页数量）：设置为 30。这是在性能和用户体验之间的平衡——太少会增加请求次数，太多会加长单次加载时间。

page（页码）：从 1 开始计数，用于分页加载。

API 响应的数据提取

搜索 API 的响应结构具有特殊性——结果包裹在items数组中：

{"data":{"total_count":150,"incomplete_results":false,"items":[{"id":12345,"full_name":"flutter/flutter","stargazers_count":"150000",// ...}]}}

项目使用的parseList安全解析函数自动处理这种结构：

finalitems=parseList<dynamic>(response.data,'items')??[];_repositories=items.whereType<Map<String,dynamic>>().map(Repository.fromJson).toList();

parseList在response.data这个 Map 中查找items键，提取列表。然后再通过whereType过滤掉非 Map 元素（防止 API 返回异常数据导致崩溃），最后用Repository.fromJson转换。

RepoSearchProvider 的完整实现

classRepoSearchProviderextendsChangeNotifier{finalAtomGitApiClient_apiClient;List<Repository>_repositories=[];bool _isLoading=false;String?_error;String_currentQuery='';bool _hasMore=false;int _page=1;// 公开 getter，使用 UnmodifiableListView 防止外部修改List<Repository>getrepositories=>List.unmodifiable(_repositories);boolgetisLoading=>_isLoading;String?geterror=>_error;StringgetcurrentQuery=>_currentQuery;boolgethasMore=>_hasMore;}

search 方法（首次搜索/重新搜索）

Future<void>search(Stringquery)async{// 空查询不发起请求if(query.trim().isEmpty)return;_currentQuery=query.trim();_page=1;_isLoading=true;_error=null;notifyListeners();try{finalresponse=await_apiClient.get('/search/repositories',queryParams:{'q':_currentQuery,'sort':'stars','order':'desc','per_page':'30','page':'1',},);finalitems=parseList<dynamic>(response.data,'items')??[];_repositories=items.whereType<Map<String,dynamic>>().map(Repository.fromJson).toList();// 判断是否还有更多数据_hasMore=_repositories.length>=30;}onApiExceptioncatch(e){_error=e.message;}catch(e){_error='搜索失败:$e';}finally{_isLoading=false;notifyListeners();}}

执行顺序：

1. 记录查询词（_currentQuery）、重置页码（_page = 1）
2. 设置 loading 状态，清除旧错误
3. 发起 API 请求
4. 安全解析响应，替换结果列表
5. 通过返回数量是否等于 per_page 来判断是否有下一页

loadMore 方法（无限滚动）

Future<void>loadMore()async{if(_isLoading||!_hasMore)return;_page++;_isLoading=true;notifyListeners();try{finalresponse=await_apiClient.get('/search/repositories',queryParams:{'q':_currentQuery,'sort':'stars','order':'desc','per_page':'30','page':_page.toString(),},);finalitems=parseList<dynamic>(response.data,'items')??[];finalnewRepos=items.whereType<Map<String,dynamic>>().map(Repository.fromJson).toList();_repositories.addAll(newRepos);_hasMore=newRepos.length>=30;}onApiExceptioncatch(e){_error=e.message;_page--;// 翻页失败时回退页码}catch(e){_page--;}finally{_isLoading=false;notifyListeners();}}

页码回退是 loadMore 最关键的设计细节。

假设没有回退：用户滚动到底部触发 loadMore →_page从 2 变为 3 → API 请求失败（网络抖动）→_page停留在 3。网络恢复后用户再次滚动 → loadMore 请求第 3 页 → 第 2 页的数据永远丢失。

有回退时：API 请求失败 →_page--回到 2 → 下次重试从第 2 页开始 → 数据完整。

无限滚动的 ScrollController 实现

class_SearchBodyStateextendsState<_SearchBody>{final_scrollController=ScrollController();@overridevoidinitState(){super.initState();_scrollController.addListener(_onScroll);}@overridevoiddispose(){_scrollController.dispose();super.dispose();}void_onScroll(){finalprovider=context.read<RepoSearchProvider>();if(_scrollController.position.pixels>=_scrollController.position.maxScrollExtent-200&&provider.hasMore&&!provider.isLoading){provider.loadMore();}}}

触发条件有三个：

1. 滚动到距底部 200px：pixels >= maxScrollExtent - 200。200px 的预加载距离让用户感觉不到加载延迟
2. 还有更多数据：provider.hasMore。没有更多数据时不发起无效请求
3. 不在加载中：!provider.isLoading。防止重复触发（在加载完成前用户可能多次滚动到底部）

为什么需要 dispose ScrollController？

ScrollController 在 Widget 销毁后如果仍然存活，其 listener 可能会尝试访问已销毁的 Widget 的 context，导致内存泄漏或运行时错误。在 dispose 中移除 listener 并销毁 controller 是防止这类问题的标准做法。

搜索 UI 状态管理

Widget_buildBody(BuildContextcontext,RepoSearchProviderprovider){// 状态 1：错误（无缓存数据）if(provider.error!=null&&provider.repositories.isEmpty){returnErrorRetryWidget(message:provider.error!,onRetry:()=>provider.search(provider.currentQuery),);}// 状态 2：首次加载中if(provider.isLoading&&provider.repositories.isEmpty){returnconstLoadingIndicator(message:'搜索中...');}// 状态 3：空结果if(provider.repositories.isEmpty&&!provider.isLoading){returnconstCenter(child:Column(mainAxisAlignment:MainAxisAlignment.center,children:[Icon(Icons.search_off,size:64,color:Colors.grey),SizedBox(height:16),Text('未找到仓库'),SizedBox(height:8),Text('试试其他关键词',style:TextStyle(color:Colors.grey)),],),);}// 状态 4：结果列表returnListView.builder(controller:_scrollController,itemCount:provider.repositories.length+(provider.hasMore?1:0),itemBuilder:(context,index){if(index>=provider.repositories.length){returnconstPadding(padding:EdgeInsets.all(16),child:Center(child:CircularProgressIndicator()),);}finalrepo=provider.repositories[index];return_buildRepoItem(repo);},);}

四种状态的展示逻辑：

1. 有错误且列表为空：展示 ErrorRetryWidget。但如果有旧数据（之前搜索成功），不展示错误——用户在旧结果上继续浏览比看错误页面好
2. 加载中且列表为空：展示 LoadingIndicator。如果列表已有数据（loadMore 场景），不切换为全屏 loading
3. 加载完成但列表为空：展示"未找到仓库"，引导用户换关键词
4. 有数据：展示结果列表，底部根据 hasMore 决定是否显示加载指示器

登录状态感知

搜索页面需要检测登录状态，未登录时引导登录：

if(!widget.isLoggedIn&&query.isEmpty){return_buildLoginPrompt(context);}

这里的判断条件是!isLoggedIn && query.isEmpty。如果用户从首页传入了一个搜索词（query 不为空），即使未登录也显示搜索结果——让访客体验搜索功能。

但如果 query 为空且未登录，展示登录引导而非空白页面：

Widget_buildLoginPrompt(BuildContextcontext){returnCenter(child:Padding(padding:constEdgeInsets.all(32),child:Column(mainAxisAlignment:MainAxisAlignment.center,children:[Icon(Icons.search,size:64,color:Colors.grey[400]),constSizedBox(height:16),Text('搜索 AtomGit 仓库',style:Theme.of(context).textTheme.titleMedium),constSizedBox(height:8),Text('登录后可搜索并发现更多仓库',style:Theme.of(context).textTheme.bodyMedium?.copyWith(color:Colors.grey)),constSizedBox(height:24),FilledButton.icon(onPressed:()=>Navigator.pushNamed(context,'/login'),icon:constIcon(Icons.login),label:constText('立即登录'),),],),),);}

搜索流程的完整时序

用户输入关键词 → onSubmitted → (如果来自首页) Navigator.pushNamed('/search', query) → SearchScreen 构建 → ChangeNotifierProvider 创建 RepoSearchProvider → provider.search(query) → notifyListeners() → UI 显示 loading → API 请求 /search/repositories?q=xxx → 解析响应 → 更新 _repositories → notifyListeners() → UI 显示结果列表 → 用户滚动到底部 → _onScroll 检测触发 → provider.loadMore() → _page++ → API 请求第 N 页 → 追加到 _repositories → notifyListeners() → ListView 追加新行

搜索性能考量

搜索的性能瓶颈主要在 API 请求延迟。客户端做了以下优化：

1. 防重复请求：_isLoading守卫防止用户快速滚动触发多次 loadMore
2. 预加载触发点：距离底部 200px 触发，而非到底部才触发，用户感知延迟更小
3. 适中的 per_page：30 条一页，既能填满 3-5 屏，又不会因为单页数据过大而增加解析时间

与 ExploreTab 搜索的关系

ExploreTab 有自己的搜索实现，不使用 RepoSearchProvider。两者对比：

两种实现并存是因为它们的交互模式不同。独立的搜索页面更利于沉浸式搜索体验，Tab 内搜索则适合快速查找。