SuperAPI AI 工具集

expo-data-fetching

编程与开发

查看项目

更新于 10-27 13:02

技能介绍

用途

该技能用于 Expo / React Native 应用中的网络请求与数据获取工作。资料明确要求:在实现或调试任何网络请求、API 调用或数据获取时都必须使用本技能,包括 API 请求、数据获取、缓存或网络调试。

主要能力

技能覆盖以下方面:

  • 基础 fetch API 使用(GET、POST、请求头、请求体)
  • React Query(TanStack Query)的安装配置、数据获取、变更(mutation)
  • SWR 或自定义 hooks(用于较简单需求)
  • 错误处理:类型化错误(ApiError)、网络错误与 HTTP 错误区分、指数退避重试
  • 认证:使用 expo-secure-store 存储令牌、令牌刷新流程
  • 离线支持:NetInfo 网络状态检测、离线优先的 React Query 配置
  • 环境变量:EXPO_PUBLIC_ 前缀、多环境配置、API 客户端封装
  • 请求取消:AbortController、React Query 自动取消
  • Expo Router 数据加载器(useLoaderData,Web,SDK 55+)

技能还提供决策树,帮助判断在路由级数据加载、基础 fetch、缓存/状态管理、认证、错误处理、离线支持、环境配置和性能等场景下应选择哪种方案。

使用方式

技能以参考文档和代码示例的形式组织。资料中列出的参考资源包括:

  • references/expo-router-loaders.md:使用 Expo Router loaders 进行路由级数据加载(Web,SDK 55+)
  • references/offline-and-cancellation.md:NetInfo 网络状态、离线优先 React Query、AbortController

技能给出偏好:避免使用 axios,优先使用 expo/fetch。

技能提出“每个屏幕都有四种状态”的设计原则:为加载数据的屏幕设计加载、错误、空和内容四种状态,这些状态可以重叠(例如刷新错误应与缓存内容共存)。加载不等于空:空表示已解析但零条目,而非数据缺失。在检查列表长度前应处理初始加载、失败和水合。在 TanStack Query v5 中,isLoading 表示首次请求正在进行;被禁用或离线暂停的查询可能没有数据但也不处于加载状态,此时应显示前置条件或离线状态。空状态应使用 FlatList/FlashList 的 ListEmptyComponent 进行设计,解释为空原因并提供下一步操作。重新获取时保留旧内容:即使刷新失败也渲染缓存数据,并显示非阻塞错误与重试。使用 isLoading 表示首次加载的加载指示器,isFetching 表示后台活动;对于已知布局的慢速初始加载优先使用骨架屏,用户主动刷新使用 RefreshControl。当初始 UI 或重定向依赖持久化状态(认证令牌、引导标记)时,根布局应渲染空内容或启动屏,直到该状态加载完成。保存时应保留工作:变更进行中禁用重复提交;失败时保留草稿、显示内联错误并允许重试;仅在成功后清除或关闭。若采用乐观更新,失败时应恢复先前值或将编辑标记为未同步。

适用场景

资料列出的适用场景包括:实现 API 请求;设置数据获取(React Query、SWR);使用 Expo Router 数据加载器(useLoaderData,Web SDK 55+);调试网络失败;实现缓存策略;处理离线场景;认证/令牌管理;配置 API URL 和环境变量。

示例调用包括:如何在 React Native 中进行 API 调用;应使用 React Query 还是 SWR;应用需要离线工作;如何处理认证令牌;API 调用很慢;如何为开发和生产配置不同的 API URL;API 密钥应放在哪里;如何在 Expo Router 中为页面加载数据。

限制与注意事项

资料中列出的重要注意事项包括:只有以 EXPO_PUBLIC_ 为前缀的变量才会暴露到客户端包中;绝不要将机密(具有写权限的 API 密钥、数据库密码)放入 EXPO_PUBLIC_ 变量,因为它们会在构建后的应用中可见;环境变量在构建时内联,而非运行时;更改 .env 文件后需重启开发服务器;API 路由中的服务端机密应使用不带 EXPO_PUBLIC_ 前缀的变量。

常见错误示例:不进行错误处理(错误做法:直接 fetch 后 json;正确做法:检查 response.ok 并抛出错误);将令牌存储在 AsyncStorage(不安全,应使用 SecureStore 存储敏感数据)。

关于反馈:若遇到错误、误导性或过时信息,可通过 npx --yes submit-expo-feedback@latest --category skills --subject "expo-data-fetching" "<actionable feedback>" 提交反馈,仅在具体且可操作时提交。若 AI 代理反复失败或用户不得不接管 Expo 任务,应加载 expo-skill-feedback 技能并遵循其 eval-candidate 流程。

关于 Expo Router 数据加载器,资料注明其适用于 Web 和 SDK 55+;原生端应使用 React Query 或 fetch。