在 Expo/React Native…

适用于 Expo/React Native 项目中实现或调试任何 API 请求、数据获取、缓存、离线与鉴权场景。

适用场景

解决思路

1. 优先使用 expo/fetch，避免使用 axios。
2. 为每个加载数据的屏幕设计四种状态：loading、error、empty、content，且允许重叠（例如刷新失败时仍展示缓存内容）。
3. 区分 loading 与 empty：empty 表示请求已成功返回但结果为零条，而非数据缺失；在检查列表长度前先处理初始加载、失败与 hydration。
4. 在 TanStack Query v5 中，isLoading 仅表示首次请求进行中；被禁用或离线暂停的查询可能无数据但并非 loading，此时应展示前置条件或离线状态。
5. empty 是设计过的状态而非空白列表：在 FlatList/FlashList 上使用 ListEmptyComponent，说明为空的原因并提供相应下一步操作（如“暂无内容”提供创建，“无结果”提供修改或清除搜索/筛选）。
6. 重新获取时保留旧内容：即使刷新失败也渲染缓存的 data，并展示非阻塞错误与重试；用 isLoading 控制首次加载 spinner，用 isFetching 表示后台活动；已知布局的慢速首次加载优先用骨架屏，用户主动刷新用 RefreshControl。
7. 基于 hydration 做门控：当初始 UI 或重定向依赖持久化状态（鉴权 token、onboarding 标记）时，根布局在该状态加载完成前不渲染任何内容或只渲染 splash；否则每次冷启动会闪现错误屏幕，并会错误路由在 hydration 前到达的深链接。
8. 保存操作要保留用户工作：mutation 进行中禁用重复提交；失败时保留草稿、展示内联错误并允许重试，仅在成功后清除或关闭；若使用乐观更新，失败时恢复之前的值或将编辑标记为未同步；用一次失败的保存加重试来验证。
9. 基本 GET 请求：用 fetch 请求 URL，检查 response.ok，不 ok 则抛出包含 status 的错误，否则返回 response.json()。
10. 带 body 的 POST 请求：设置 method: "POST"、Content-Type: application/json、Authorization: Bearer token 头，body 用 JSON.stringify，不 ok 时解析错误 JSON 并抛出其 message。
11. React Query 初始化：在 app/_layout.tsx 中用 QueryClientProvider 包裹，创建 QueryClient 并设置 defaultOptions.queries 的 staleTime（如 5 分钟）与 retry（如 2 次）。
12. React Query 取数：用 useQuery 传入 queryKey 与 queryFn，解构 data、fetchStatus、error、refetch；当 data 为 undefined 时，若有 error 展示 ErrorState 并重试，若 fetchStatus === "paused" 展示 OfflineState，否则展示 Loading；有 data 时若有 error 展示内联错误并重试，data 为 null 展示 EmptyState，否则渲染内容。
13. React Query mutation：用 useMutation 传入 mutationFn，在 onSuccess 中调用 queryClient.invalidateQueries 使相关 queryKey 失效并重新获取；提交时若 mutation.isPending 则直接返回，表单在错误时保留草稿并在 isLoading 时禁用提交按钮。
14. 综合错误处理：定义 ApiError 类（含 message、status、code）；封装 fetchWithErrorHandling，在 response 不 ok 时解析错误 JSON 并抛出 ApiError，捕获非 ApiError 的网络错误时抛出 ApiError("Network error", 0, "NETWORK_ERROR")。
15. 重试逻辑：封装 fetchWithRetry，循环最多 retries 次调用 fetchWithErrorHandling，最后一次仍失败则抛出，否则用指数退避（Math.pow(2, i) * 1000 毫秒）等待后重试。
16. Token 管理：用 expo-secure-store 封装 auth 对象，提供 getToken/setToken/removeToken，分别调用 SecureStore.getItemAsync/setItemAsync/deleteItemAsync。
17. 鉴权请求封装：authFetch 先从 auth.getToken() 取 token，再调用 fetch 并在 headers 中带上 Authorization: Bearer token。
18. Token 刷新：用 isRefreshing 标志与 refreshPromise 保证并发刷新只执行一次；getValidToken 中若 token 不存在或已过期，则在未刷新时启动 refreshToken 并缓存 promise，刷新完成后重置标志与 promise，返回该 promise。
19. 离线支持：用 NetInfo 检测网络状态，配合 React Query 持久化实现离线优先，详见 references/offline-and-cancellation.md。
20. 环境变量：Expo 支持 EXPO_PUBLIC_ 前缀的环境变量，构建时内联到 JS 代码中；在 .env 中定义如 EXPO_PUBLIC_API_URL，代码中用 process.env.EXPO_PUBLIC_API_URL 读取。
21. 按环境区分配置：在 .env.development 与 .env.production 中分别设置 EXPO_PUBLIC_API_URL，实现开发与生产不同 API 地址。
22. 创建 API 客户端：在 api/client.ts 中读取 BASE_URL，若未定义则抛出错误；导出 apiClient，提供 get 与 post 泛型方法，内部用 fetch 并在不 ok 时抛出 HTTP 状态错误。
23. 环境变量注意事项：只有 EXPO_PUBLIC_ 前缀的变量会暴露到客户端 bundle；绝不要把有写权限的 API key、数据库密码等机密放进 EXPO_PUBLIC_ 变量；环境变量在构建时而非运行时内联；修改 .env 后需重启 dev server；服务端机密用不带前缀的变量且仅在 API routes 中使用。
24. TypeScript 支持：在 types/env.d.ts 中通过 declare global 扩展 NodeJS.ProcessEnv，声明 EXPO_PUBLIC_API_URL 等变量类型。
25. 请求取消：组件卸载时用 AbortController 取消请求（React Query 会自动取消），详见 references/offline-and-cancellation.md。
26. 按决策树选择方案：路由级数据加载（web、SDK 55+）用 Expo Router loaders；基本请求用 fetch 加错误处理；复杂应用用 React Query，简单需求用 SWR 或自定义 hooks；鉴权用 expo-secure-store 加刷新流程；错误处理区分网络错误（先查连通性）、HTTP 错误（解析响应抛类型化错误）与重试（指数退避）；离线用 NetInfo 加 React Query 持久化；环境配置客户端 URL 用 EXPO_PUBLIC_ 前缀、服务端机密用无前缀变量、多环境用 .env.development 与 .env.production；性能上缓存用 React Query staleTime、去重由 React Query 处理、取消用 AbortController 或 React Query。
27. 避免常见错误：不要不做错误处理直接 fetch(...).then(r => r.json())，要先检查 response.ok；不要把 token 存在 AsyncStorage，敏感数据要用 SecureStore。

适用边界 · 注意事项

• 非 Expo/React Native 项目（如纯 Web 或其它移动框架）不适用本技能中的 expo-secure-store、EXPO_PUBLIC_ 环境变量、Expo Router loaders 等特定能力。
• 需要服务端机密（写权限 API key、数据库密码）时，不能使用 EXPO_PUBLIC_ 前缀变量，因为它们会暴露在客户端 bundle 中。
• Expo Router 路由级 loaders 仅适用于 web 且 SDK 55+，原生端应改用 React Query 或 fetch。