 生产级移动应用架构实战)
AAS android-dev 技能深度解析React Native (TypeScript) 生产级移动应用架构实战【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本文基于 Agentic Awesome SkillsAAS仓库中 android-dev 技能的 React Native 参考文档系统讲解一套 TypeScript 技术栈下的 React Native 生产级应用架构feature-first 目录结构、React Navigation v7 类型化导航、Zustand React Query 双轨状态管理、带安全 Token 注入的 Axios 拦截器、Zod 响应校验、Bridgeless 新架构要点以及 Jest MSW 测试策略。读完本文你可以直接在 Android 项目中落地这套完整可复制的架构模板。这套参考文档位于 AAS 的 android-dev 技能包内react-native.md是 SKILL.md 定义的六大技术栈参考文档之一。技能主入口要求 Agent 在执行前先阅读 detailed-guide.md并按需加载references/目录下对应技术栈的深潜文档——React Native 就是其中之一。一、技术栈定位React Native 在 AAS 技能中的坐标在 detailed-guide.md 的 §1 Stack Selection 中React Native 的定位是适用场景Best forWeb Android 代码共享、JS/TS 团队、丰富的生态语言TypeScript官方推荐优于 JavaScriptUIReact Native 核心组件 NativeWind / React Native Paper核心库React Navigation、Zustand/Redux Toolkit、React Query、MMKV参考文档references/react-native.md即本文主题文档。从文档中的决策矩阵Decision Matrix看React Native 在「Android Web 双端」「JS/TS 团队」两项上标记为 ✅ Best在「原生性能」上标记为 ⚠️——这决定了本文档的技术选型逻辑用类型安全和架构纪律弥补跨端性能短板把性能关键路径交给新架构Bridgeless与 UI 线程动画库。该参考文档同样收录在通用插件包中路径为 react-native.md两份内容保持一致分别服务于 Claude 专属插件与通用插件两个分发渠道。二、项目目录结构feature-first 分层原文档给出的目录骨架是整套架构的地基完整继承如下src/ ├── app/ │ ├── App.tsx # Root component, providers │ ├── navigation/ # React Navigation stacks types │ └── store/ # RTK store setup ├── features/ │ └── home/ │ ├── api/ # RTK Query endpoints │ ├── components/ # Screen-specific components │ ├── hooks/ # Feature-level custom hooks │ ├── screens/ # Screen components │ ├── store/ # Zustand slice or RTK slice │ └── types.ts # Feature types ├── shared/ │ ├── components/ # Design system components │ ├── hooks/ # Shared hooks │ ├── theme/ # Colors, typography, spacing constants │ └── utils/ # Utilities └── services/ ├── api/ # Axios/fetch client interceptors └── storage/ # MMKV wrapper从源码结构看这套划分遵循 detailed-guide.md §2 Architecture 的核心原则——UI、业务逻辑与数据三层独立可测app/是入口层App.tsx集中装配 providersQueryClientProvider、SafeAreaProvider 等导航栈类型集中在navigation/全局 store 配置在store/。业务代码永远不直接 import 页面只经过导航类型跳转保证导航图可静态推导。features/是 feature-first 核心每个 feature如home内部自带api/、components/、hooks/、screens/、store/与types.ts一个功能域的全部代码同目录内聚。这与 detailed-guide 中「React Native (Redux Toolkit or Zustand)RTK Query 或 React Query 管服务端状态、Zustand 切片管客户端状态、自定义 hook 封装每个 feature 的业务逻辑」的三段式架构完全对应。shared/是设计系统层组件、hooks、主题常量颜色/字体/间距与工具函数跨 feature 复用避免各 feature 私有 UI 漂移。services/是基础设施层HTTP 客户端含拦截器与存储封装MMKV wrapper集中管理feature 代码不直接触碰 axios 或原生存储 API。三、导航配置React Navigation v7 类型化栈参考文档采用 React Navigation v7 的 native-stack完整代码如下export type RootStackParamList { Auth: undefined; Home: undefined; Detail: { id: string }; Settings: undefined; }; export type RootStackScreenPropsT extends keyof RootStackParamList NativeStackScreenPropsRootStackParamList, T; const Stack createNativeStackNavigatorRootStackParamList(); export const RootNavigator () { const isLoggedIn useAuthStore((s) s.isLoggedIn); return ( Stack.Navigator screenOptions{{ headerShown: false }} {isLoggedIn ? ( Stack.Screen nameHome component{HomeScreen} / Stack.Screen nameDetail component{DetailScreen} / / ) : ( Stack.Screen nameAuth component{AuthScreen} / )} /Stack.Navigator ); };这段代码包含三个关键设计点路由参数全类型化RootStackParamList以映射类型声明每条路由的参数签名Detail需要{ id: string }其余为undefined。navigation.navigate(Detail, { id })在编译期即可校验参数结构跳转写错字段名会直接报 TypeScript 错误这是跨端项目里替代原生「页面传参靠约定」的重要手段。RootStackScreenProps泛型派生用NativeStackScreenPropsRootStackParamList, T派生每个屏幕的 props 类型屏幕组件即可从props.navigation拿到强类型的导航对象。认证态条件渲染导航树根据 ZustanduseAuthStore中的isLoggedIn在「已登录视图Home/Detail」与「未登录视图Auth」之间切换实现无需手动reset跳转的登录墙——状态变化时导航树自动重建。配套依赖上v7 栈依赖react-navigation/nativereact-navigation/native-stack运行时需要react-native-screens原生屏幕管理与react-native-safe-area-context安全区适配均已在第七节依赖清单中锁定版本。四、状态管理Zustand 客户端状态 React Query 服务端状态参考文档将状态管理拆成两条轨道完整代码如下// Client state — Zustand // Do not persist bearer or refresh tokens in AsyncStorage/plain MMKV. // Store secrets with a platform-backed module such as react-native-keychain // or expo-secure-store, and persist only non-sensitive UI state here. interface AuthState { isLoggedIn: boolean; setLoggedIn: (value: boolean) void; logout: () void; } export const useAuthStore createAuthState()( persist( (set) ({ isLoggedIn: false, setLoggedIn: (value) set({ isLoggedIn: value }), logout: () set({ isLoggedIn: false }), }), { name: auth-ui-storage, storage: createJSONStorage(() mmkvStorage) } ) ); // Keep tokens outside persisted app state. const getSecureToken () Keychain.getGenericPassword().then((r) (r ? r.password : null)); const saveSecureToken (token: string) Keychain.setGenericPassword(auth, token); const clearSecureToken () Keychain.resetGenericPassword(); // Server state — React Query export const useItems () useQuery({ queryKey: [items], queryFn: itemsApi.getAll, staleTime: 5 * 60 * 1000, // 5 minutes }); export const useRefreshItems () useMutation({ mutationFn: itemsApi.refresh, onSuccess: () queryClient.invalidateQueries({ queryKey: [items] }), });这段代码里有三个值得展开的细节Zustand 持久化的安全边界文档明确注释「不要把 bearer/refresh token 放进 AsyncStorage 或普通 MMKV」只用react-native-keychain这类平台级安全模块iOS Keychain / Android Keystore存放凭据Zustandpersist中间件经createJSONStorage(() mmkvStorage)只持久化isLoggedIn这类非敏感 UI 状态存储键为auth-ui-storage。MMKV 作为持久化后端也是 detailed-guide 中 RN 栈的核心库之一相比 AsyncStorage 是同步读写、基于 mmap 的高性能存储。React Query 管服务端状态useItems用[items]作为 queryKeystaleTime: 5 * 60 * 10005 分钟控制数据新鲜度窗口窗口内重复挂载不会重新请求。useRefreshItems是useMutation成功后invalidateQueries({ queryKey: [items] })使缓存失效并触发重新拉取——这正是「mutation 不直接改缓存靠失效驱动一致性」的标准 React Query 用法。双轨分工客户端状态登录态、UI 开关、表单草稿走 Zustand 切片服务端状态列表、详情、计数一律走 React Query/RTK Query。detailed-guide 中 RN 的架构描述「RTK Query or React Query for server state, Zustand slices for client state」与此一一对应。五、屏幕模式加载/错误/数据三态 下拉刷新原文档的 Screen Pattern 是一个完整的可复制模板type HomeScreenProps RootStackScreenPropsHome; export const HomeScreen: FCHomeScreenProps ({ navigation }) { const { data: items, isLoading, isError, refetch } useItems(); if (isLoading) return LoadingView /; if (isError) return ErrorView onRetry{refetch} /; return ( SafeAreaView style{styles.container} FlatList data{items} keyExtractor{(item) item.id} renderItem{({ item }) ( ItemCard item{item} onPress{() navigation.navigate(Detail, { id: item.id })} / )} ListEmptyComponent{EmptyView /} refreshControl{ RefreshControl refreshing{isLoading} onRefresh{refetch} / } / /SafeAreaView ); };该模式固化了若干生产约定三态短路渲染isLoading→LoadingView、isError→ErrorView携带onRetry{refetch}的重试回调、其余才渲染数据视图。屏幕组件不持有加载逻辑全部来自useItems()的解构。SafeAreaView包裹内容区对应react-native-safe-area-context依赖处理刘海屏/灵动岛。FlatList标准四件套keyExtractor用稳定 id、ListEmptyComponent空态兜底、refreshControl绑定refetch实现下拉刷新、renderItem内的ItemCard通过navigation.navigate(Detail, { id: item.id })完成类型化跳转——与第三节的路由类型闭环衔接。六、API 客户端Axios 拦截器与安全 Token 注入原文档给出的 Axios 客户端封装了请求/响应两层拦截器const apiClient axios.create({ baseURL: Config.API_BASE_URL, timeout: 10_000, headers: { Content-Type: application/json }, }); // Auth token injection apiClient.interceptors.request.use(async (config) { const token await getSecureToken(); if (token) config.headers.Authorization Bearer ${token}; return config; }); // Token refresh on 401 apiClient.interceptors.response.use( (res) res, async (error: AxiosError) { if (error.response?.status 401) { const newToken await refreshToken(); if (newToken) { await saveSecureToken(newToken); useAuthStore.getState().setLoggedIn(true); return apiClient(error.config!); } await clearSecureToken(); useAuthStore.getState().logout(); } return Promise.reject(error); } );从实现细节看这条调用链的设计意图是请求侧每次请求异步从 Keychain 读取 token 并注入Authorization: Bearer头token 全程不落 JS 层全局变量、不进任何持久化 JS 存储。响应侧 401 处理命中 401 时先尝试refreshToken()刷新成功则保存新 token、保持登录态并return apiClient(error.config!)重放原始请求对调用方透明的自愈刷新失败则清 token 并logout()把状态同步回 Zustand导航树随即切回 Auth 视图。超时与基地址timeout: 10_000统一 10 秒超时baseURL从Config.API_BASE_URL注入与 detailed-guide §7 中 debug/staging/release 构建变体使用不同 API 地址buildConfigfor environment-specific constants的思路一致。七、API 响应校验Zod 契约防御跨端应用里服务端契约漂移是常见故障源参考文档用 Zod 在数据进入 UI 前做运行时校验const ItemSchema z.object({ id: z.string(), title: z.string(), description: z.string().optional(), createdAt: z.string().datetime(), }); const ItemsResponseSchema z.array(ItemSchema); type Item z.infertypeof ItemSchema; const getItems async (): PromiseItem[] { const { data } await apiClient.get(/items); return ItemsResponseSchema.parse(data); // throws ZodError on invalid shape };要点在于z.infer让 TypeScript 类型直接由 schema 推导单一事实来源而parse在数据形状非法时抛出ZodError——错误在queryFn内被 React Query 捕获后自然进入第五节的isError态形成「校验失败 → 错误视图 → 用户可重试」的完整闭环。createdAt: z.string().datetime()同时约束了 ISO 8601 格式防止脏时间戳流入 UI。八、关键依赖与版本锁定参考文档给出的依赖清单版本以其为基准实际落地时应核对各库当前兼容版本{ dependencies: { react-native: 0.74.x, react-navigation/native: ^7.0.0, react-navigation/native-stack: ^7.0.0, tanstack/react-query: ^5.45.0, zustand: ^4.5.4, axios: ^1.7.2, zod: ^3.23.8, react-native-keychain: ^8.2.0, react-native-mmkv: ^2.12.2, react-native-safe-area-context: ^4.10.1, react-native-screens: ^3.32.0 }, devDependencies: { typescript: ^5.4.5, testing-library/react-native: ^12.5.1, msw: ^2.3.1, jest: ^29.7.0 } }各依赖在前文各节的角色对照依赖架构角色react-native0.74.x运行时基座New Architecture 默认开启的版本线react-navigation/*v7类型化导航栈第三节tanstack/react-queryv5服务端状态、失效重取第四节zustand客户端状态 persist 持久化第四节axiosHTTP 客户端 拦截器第六节zod响应契约校验第七节react-native-keychain平台级凭据存储第四节安全边界react-native-mmkv高性能本地存储Zustand 持久化后端react-native-screens/-safe-area-context导航与布局的原生依赖testing-library/react-nativemswjest单元测试三件套第九节值得注意的组合约束React Navigation v7 要求react-native-screens≥ 3.32 与react-native-safe-area-context≥ 4.10清单中锁定的版本正好满足该前置条件react-native-mmkvv2 是同步 API 版本线与文档中mmkvStorage直接注入createJSONStorage的同步读写用法匹配。九、New ArchitectureBridgeless注意事项参考文档对新架构给出四条硬性要求原文继承在android/gradle.properties中开启newArchEnabledtrue原生模块一律使用TurboModules避免遗留的 NativeModules API自定义原生视图使用Fabric渲染器始终在HermesJS 引擎下测试。这四条对应 RN 0.74 时代的方向性转变Bridge 被移除后JS 与原生通过 C 层直连TurboModules 按需懒加载原生模块改善冷启动、Fabric 取代旧视图树改善首帧渲染。从依赖清单看react-native: 0.74.x正是 New Architecture 默认开启的版本因此newArchEnabledtrue属于「显式对齐默认值 CI 防回退」的配置纪律。对本文架构而言影响面主要在两处自定义原生模块如推送、生物识别必须按 TurboModule 规范编写任何依赖旧桥事件的第三方库需要确认其 Fabric 兼容状态。十、性能优化清单原文档的五条性能建议完整保留并补充其作用机理useCallbackmemo作用于renderItem/ 列表项组件FlatList会反复调用renderItem匿名函数与未 memo 的子组件会导致整列 diff 放大这是列表卡顿的首要来源。调参windowSize、initialNumToRender、maxToRenderPerBatch控制离屏预渲染窗口与批量渲染节奏在首屏速度与内存占用间取平衡。避免 JSX 中的匿名内联函数如onPress{() ...}每次渲染都产生新引用破坏memo的引用相等判断。InteractionManager.runAfterInteractions把重活导航后拉数据、写存储推迟到过渡动画结束后执行避免动画期间主线程拥塞。react-native-reanimated动画在 UI 线程执行不阻塞 JS 线程是 60fps 动画的推荐路径。detailed-guide §8 对 UI 性能的目标是 60fps支持设备上 90/120fps零卡顿RN 栈下这套清单就是达成该目标的对应手段。十一、测试策略Jest Testing Library MSW参考文档给出的屏幕级集成测试示例describe(HomeScreen, () { it(shows items when query succeeds, async () { server.use( http.get(${API_URL}/items, () HttpResponse.json([{ id: 1, title: Test Item }]) ) ); const { getByText } render( QueryClientProvider client{testQueryClient} HomeScreen navigation{mockNavigation} route{mockRoute} / /QueryClientProvider ); expect(await findByText(Test Item)).toBeTruthy(); }); });这个用例把前文所有层串起来验证MSW 的server.use(http.get(...))在测试粒度覆盖全局 handler拦截/items返回受控数据render时外层包上QueryClientProvider与生产App.tsx的 providers 装配一致并注入mockNavigation/mockRoute替代真实导航上下文断言则用异步findByText等待查询完成后的渲染结果——恰好覆盖了「React Query 拉取 → Zod 校验 → 三态渲染」整条链路。在 detailed-guide §6 Testing 的测试金字塔中RN 的单测组合被明确记为「Jest testing-library/react-nativemswfor API mocking」与 native 栈的 JUnit5/MockK 平行域层与表现层的覆盖率目标为≥ 80%E2E 层则推荐 Maestro 跨 Flutter/RN 覆盖关键用户旅程。十二、适用边界与落地提醒结合 SKILL.md 的 Limitations 章节落地这套参考文档时应注意技能范围限定在 Android 及 Android 相邻交付路径不覆盖 iOS-only 架构与 App Store 发布操作RN 双端场景下 iOS 侧需另行对齐依赖版本号、Play Console 策略阈值会随时间变化发布关键信息需对照当前 Android / Google Play / 各库文档核实文中代码片段是架构模式而非完整应用包名、依赖版本、权限声明、隐私披露与安全控制都需要按实际项目适配该指导不能替代真机 QA、无障碍审查、安全审查、法务/隐私审查与商店合规检查。延伸阅读完整的跨栈决策、架构、构建发布与性能体系见 detailed-guide.md同目录下的 native-android.md、flutter.md、kmm.md、hybrid.md、java-android.md 覆盖其余技术栈可对照选型后按需加载。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AAS android-dev 技能深度解析：React Native (TypeScript) 生产级移动应用架构实战
AAS android-dev 技能深度解析React Native (TypeScript) 生产级移动应用架构实战【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本文基于 Agentic Awesome SkillsAAS仓库中 android-dev 技能的 React Native 参考文档系统讲解一套 TypeScript 技术栈下的 React Native 生产级应用架构feature-first 目录结构、React Navigation v7 类型化导航、Zustand React Query 双轨状态管理、带安全 Token 注入的 Axios 拦截器、Zod 响应校验、Bridgeless 新架构要点以及 Jest MSW 测试策略。读完本文你可以直接在 Android 项目中落地这套完整可复制的架构模板。这套参考文档位于 AAS 的 android-dev 技能包内react-native.md是 SKILL.md 定义的六大技术栈参考文档之一。技能主入口要求 Agent 在执行前先阅读 detailed-guide.md并按需加载references/目录下对应技术栈的深潜文档——React Native 就是其中之一。一、技术栈定位React Native 在 AAS 技能中的坐标在 detailed-guide.md 的 §1 Stack Selection 中React Native 的定位是适用场景Best forWeb Android 代码共享、JS/TS 团队、丰富的生态语言TypeScript官方推荐优于 JavaScriptUIReact Native 核心组件 NativeWind / React Native Paper核心库React Navigation、Zustand/Redux Toolkit、React Query、MMKV参考文档references/react-native.md即本文主题文档。从文档中的决策矩阵Decision Matrix看React Native 在「Android Web 双端」「JS/TS 团队」两项上标记为 ✅ Best在「原生性能」上标记为 ⚠️——这决定了本文档的技术选型逻辑用类型安全和架构纪律弥补跨端性能短板把性能关键路径交给新架构Bridgeless与 UI 线程动画库。该参考文档同样收录在通用插件包中路径为 react-native.md两份内容保持一致分别服务于 Claude 专属插件与通用插件两个分发渠道。二、项目目录结构feature-first 分层原文档给出的目录骨架是整套架构的地基完整继承如下src/ ├── app/ │ ├── App.tsx # Root component, providers │ ├── navigation/ # React Navigation stacks types │ └── store/ # RTK store setup ├── features/ │ └── home/ │ ├── api/ # RTK Query endpoints │ ├── components/ # Screen-specific components │ ├── hooks/ # Feature-level custom hooks │ ├── screens/ # Screen components │ ├── store/ # Zustand slice or RTK slice │ └── types.ts # Feature types ├── shared/ │ ├── components/ # Design system components │ ├── hooks/ # Shared hooks │ ├── theme/ # Colors, typography, spacing constants │ └── utils/ # Utilities └── services/ ├── api/ # Axios/fetch client interceptors └── storage/ # MMKV wrapper从源码结构看这套划分遵循 detailed-guide.md §2 Architecture 的核心原则——UI、业务逻辑与数据三层独立可测app/是入口层App.tsx集中装配 providersQueryClientProvider、SafeAreaProvider 等导航栈类型集中在navigation/全局 store 配置在store/。业务代码永远不直接 import 页面只经过导航类型跳转保证导航图可静态推导。features/是 feature-first 核心每个 feature如home内部自带api/、components/、hooks/、screens/、store/与types.ts一个功能域的全部代码同目录内聚。这与 detailed-guide 中「React Native (Redux Toolkit or Zustand)RTK Query 或 React Query 管服务端状态、Zustand 切片管客户端状态、自定义 hook 封装每个 feature 的业务逻辑」的三段式架构完全对应。shared/是设计系统层组件、hooks、主题常量颜色/字体/间距与工具函数跨 feature 复用避免各 feature 私有 UI 漂移。services/是基础设施层HTTP 客户端含拦截器与存储封装MMKV wrapper集中管理feature 代码不直接触碰 axios 或原生存储 API。三、导航配置React Navigation v7 类型化栈参考文档采用 React Navigation v7 的 native-stack完整代码如下export type RootStackParamList { Auth: undefined; Home: undefined; Detail: { id: string }; Settings: undefined; }; export type RootStackScreenPropsT extends keyof RootStackParamList NativeStackScreenPropsRootStackParamList, T; const Stack createNativeStackNavigatorRootStackParamList(); export const RootNavigator () { const isLoggedIn useAuthStore((s) s.isLoggedIn); return ( Stack.Navigator screenOptions{{ headerShown: false }} {isLoggedIn ? ( Stack.Screen nameHome component{HomeScreen} / Stack.Screen nameDetail component{DetailScreen} / / ) : ( Stack.Screen nameAuth component{AuthScreen} / )} /Stack.Navigator ); };这段代码包含三个关键设计点路由参数全类型化RootStackParamList以映射类型声明每条路由的参数签名Detail需要{ id: string }其余为undefined。navigation.navigate(Detail, { id })在编译期即可校验参数结构跳转写错字段名会直接报 TypeScript 错误这是跨端项目里替代原生「页面传参靠约定」的重要手段。RootStackScreenProps泛型派生用NativeStackScreenPropsRootStackParamList, T派生每个屏幕的 props 类型屏幕组件即可从props.navigation拿到强类型的导航对象。认证态条件渲染导航树根据 ZustanduseAuthStore中的isLoggedIn在「已登录视图Home/Detail」与「未登录视图Auth」之间切换实现无需手动reset跳转的登录墙——状态变化时导航树自动重建。配套依赖上v7 栈依赖react-navigation/nativereact-navigation/native-stack运行时需要react-native-screens原生屏幕管理与react-native-safe-area-context安全区适配均已在第七节依赖清单中锁定版本。四、状态管理Zustand 客户端状态 React Query 服务端状态参考文档将状态管理拆成两条轨道完整代码如下// Client state — Zustand // Do not persist bearer or refresh tokens in AsyncStorage/plain MMKV. // Store secrets with a platform-backed module such as react-native-keychain // or expo-secure-store, and persist only non-sensitive UI state here. interface AuthState { isLoggedIn: boolean; setLoggedIn: (value: boolean) void; logout: () void; } export const useAuthStore createAuthState()( persist( (set) ({ isLoggedIn: false, setLoggedIn: (value) set({ isLoggedIn: value }), logout: () set({ isLoggedIn: false }), }), { name: auth-ui-storage, storage: createJSONStorage(() mmkvStorage) } ) ); // Keep tokens outside persisted app state. const getSecureToken () Keychain.getGenericPassword().then((r) (r ? r.password : null)); const saveSecureToken (token: string) Keychain.setGenericPassword(auth, token); const clearSecureToken () Keychain.resetGenericPassword(); // Server state — React Query export const useItems () useQuery({ queryKey: [items], queryFn: itemsApi.getAll, staleTime: 5 * 60 * 1000, // 5 minutes }); export const useRefreshItems () useMutation({ mutationFn: itemsApi.refresh, onSuccess: () queryClient.invalidateQueries({ queryKey: [items] }), });这段代码里有三个值得展开的细节Zustand 持久化的安全边界文档明确注释「不要把 bearer/refresh token 放进 AsyncStorage 或普通 MMKV」只用react-native-keychain这类平台级安全模块iOS Keychain / Android Keystore存放凭据Zustandpersist中间件经createJSONStorage(() mmkvStorage)只持久化isLoggedIn这类非敏感 UI 状态存储键为auth-ui-storage。MMKV 作为持久化后端也是 detailed-guide 中 RN 栈的核心库之一相比 AsyncStorage 是同步读写、基于 mmap 的高性能存储。React Query 管服务端状态useItems用[items]作为 queryKeystaleTime: 5 * 60 * 10005 分钟控制数据新鲜度窗口窗口内重复挂载不会重新请求。useRefreshItems是useMutation成功后invalidateQueries({ queryKey: [items] })使缓存失效并触发重新拉取——这正是「mutation 不直接改缓存靠失效驱动一致性」的标准 React Query 用法。双轨分工客户端状态登录态、UI 开关、表单草稿走 Zustand 切片服务端状态列表、详情、计数一律走 React Query/RTK Query。detailed-guide 中 RN 的架构描述「RTK Query or React Query for server state, Zustand slices for client state」与此一一对应。五、屏幕模式加载/错误/数据三态 下拉刷新原文档的 Screen Pattern 是一个完整的可复制模板type HomeScreenProps RootStackScreenPropsHome; export const HomeScreen: FCHomeScreenProps ({ navigation }) { const { data: items, isLoading, isError, refetch } useItems(); if (isLoading) return LoadingView /; if (isError) return ErrorView onRetry{refetch} /; return ( SafeAreaView style{styles.container} FlatList data{items} keyExtractor{(item) item.id} renderItem{({ item }) ( ItemCard item{item} onPress{() navigation.navigate(Detail, { id: item.id })} / )} ListEmptyComponent{EmptyView /} refreshControl{ RefreshControl refreshing{isLoading} onRefresh{refetch} / } / /SafeAreaView ); };该模式固化了若干生产约定三态短路渲染isLoading→LoadingView、isError→ErrorView携带onRetry{refetch}的重试回调、其余才渲染数据视图。屏幕组件不持有加载逻辑全部来自useItems()的解构。SafeAreaView包裹内容区对应react-native-safe-area-context依赖处理刘海屏/灵动岛。FlatList标准四件套keyExtractor用稳定 id、ListEmptyComponent空态兜底、refreshControl绑定refetch实现下拉刷新、renderItem内的ItemCard通过navigation.navigate(Detail, { id: item.id })完成类型化跳转——与第三节的路由类型闭环衔接。六、API 客户端Axios 拦截器与安全 Token 注入原文档给出的 Axios 客户端封装了请求/响应两层拦截器const apiClient axios.create({ baseURL: Config.API_BASE_URL, timeout: 10_000, headers: { Content-Type: application/json }, }); // Auth token injection apiClient.interceptors.request.use(async (config) { const token await getSecureToken(); if (token) config.headers.Authorization Bearer ${token}; return config; }); // Token refresh on 401 apiClient.interceptors.response.use( (res) res, async (error: AxiosError) { if (error.response?.status 401) { const newToken await refreshToken(); if (newToken) { await saveSecureToken(newToken); useAuthStore.getState().setLoggedIn(true); return apiClient(error.config!); } await clearSecureToken(); useAuthStore.getState().logout(); } return Promise.reject(error); } );从实现细节看这条调用链的设计意图是请求侧每次请求异步从 Keychain 读取 token 并注入Authorization: Bearer头token 全程不落 JS 层全局变量、不进任何持久化 JS 存储。响应侧 401 处理命中 401 时先尝试refreshToken()刷新成功则保存新 token、保持登录态并return apiClient(error.config!)重放原始请求对调用方透明的自愈刷新失败则清 token 并logout()把状态同步回 Zustand导航树随即切回 Auth 视图。超时与基地址timeout: 10_000统一 10 秒超时baseURL从Config.API_BASE_URL注入与 detailed-guide §7 中 debug/staging/release 构建变体使用不同 API 地址buildConfigfor environment-specific constants的思路一致。七、API 响应校验Zod 契约防御跨端应用里服务端契约漂移是常见故障源参考文档用 Zod 在数据进入 UI 前做运行时校验const ItemSchema z.object({ id: z.string(), title: z.string(), description: z.string().optional(), createdAt: z.string().datetime(), }); const ItemsResponseSchema z.array(ItemSchema); type Item z.infertypeof ItemSchema; const getItems async (): PromiseItem[] { const { data } await apiClient.get(/items); return ItemsResponseSchema.parse(data); // throws ZodError on invalid shape };要点在于z.infer让 TypeScript 类型直接由 schema 推导单一事实来源而parse在数据形状非法时抛出ZodError——错误在queryFn内被 React Query 捕获后自然进入第五节的isError态形成「校验失败 → 错误视图 → 用户可重试」的完整闭环。createdAt: z.string().datetime()同时约束了 ISO 8601 格式防止脏时间戳流入 UI。八、关键依赖与版本锁定参考文档给出的依赖清单版本以其为基准实际落地时应核对各库当前兼容版本{ dependencies: { react-native: 0.74.x, react-navigation/native: ^7.0.0, react-navigation/native-stack: ^7.0.0, tanstack/react-query: ^5.45.0, zustand: ^4.5.4, axios: ^1.7.2, zod: ^3.23.8, react-native-keychain: ^8.2.0, react-native-mmkv: ^2.12.2, react-native-safe-area-context: ^4.10.1, react-native-screens: ^3.32.0 }, devDependencies: { typescript: ^5.4.5, testing-library/react-native: ^12.5.1, msw: ^2.3.1, jest: ^29.7.0 } }各依赖在前文各节的角色对照依赖架构角色react-native0.74.x运行时基座New Architecture 默认开启的版本线react-navigation/*v7类型化导航栈第三节tanstack/react-queryv5服务端状态、失效重取第四节zustand客户端状态 persist 持久化第四节axiosHTTP 客户端 拦截器第六节zod响应契约校验第七节react-native-keychain平台级凭据存储第四节安全边界react-native-mmkv高性能本地存储Zustand 持久化后端react-native-screens/-safe-area-context导航与布局的原生依赖testing-library/react-nativemswjest单元测试三件套第九节值得注意的组合约束React Navigation v7 要求react-native-screens≥ 3.32 与react-native-safe-area-context≥ 4.10清单中锁定的版本正好满足该前置条件react-native-mmkvv2 是同步 API 版本线与文档中mmkvStorage直接注入createJSONStorage的同步读写用法匹配。九、New ArchitectureBridgeless注意事项参考文档对新架构给出四条硬性要求原文继承在android/gradle.properties中开启newArchEnabledtrue原生模块一律使用TurboModules避免遗留的 NativeModules API自定义原生视图使用Fabric渲染器始终在HermesJS 引擎下测试。这四条对应 RN 0.74 时代的方向性转变Bridge 被移除后JS 与原生通过 C 层直连TurboModules 按需懒加载原生模块改善冷启动、Fabric 取代旧视图树改善首帧渲染。从依赖清单看react-native: 0.74.x正是 New Architecture 默认开启的版本因此newArchEnabledtrue属于「显式对齐默认值 CI 防回退」的配置纪律。对本文架构而言影响面主要在两处自定义原生模块如推送、生物识别必须按 TurboModule 规范编写任何依赖旧桥事件的第三方库需要确认其 Fabric 兼容状态。十、性能优化清单原文档的五条性能建议完整保留并补充其作用机理useCallbackmemo作用于renderItem/ 列表项组件FlatList会反复调用renderItem匿名函数与未 memo 的子组件会导致整列 diff 放大这是列表卡顿的首要来源。调参windowSize、initialNumToRender、maxToRenderPerBatch控制离屏预渲染窗口与批量渲染节奏在首屏速度与内存占用间取平衡。避免 JSX 中的匿名内联函数如onPress{() ...}每次渲染都产生新引用破坏memo的引用相等判断。InteractionManager.runAfterInteractions把重活导航后拉数据、写存储推迟到过渡动画结束后执行避免动画期间主线程拥塞。react-native-reanimated动画在 UI 线程执行不阻塞 JS 线程是 60fps 动画的推荐路径。detailed-guide §8 对 UI 性能的目标是 60fps支持设备上 90/120fps零卡顿RN 栈下这套清单就是达成该目标的对应手段。十一、测试策略Jest Testing Library MSW参考文档给出的屏幕级集成测试示例describe(HomeScreen, () { it(shows items when query succeeds, async () { server.use( http.get(${API_URL}/items, () HttpResponse.json([{ id: 1, title: Test Item }]) ) ); const { getByText } render( QueryClientProvider client{testQueryClient} HomeScreen navigation{mockNavigation} route{mockRoute} / /QueryClientProvider ); expect(await findByText(Test Item)).toBeTruthy(); }); });这个用例把前文所有层串起来验证MSW 的server.use(http.get(...))在测试粒度覆盖全局 handler拦截/items返回受控数据render时外层包上QueryClientProvider与生产App.tsx的 providers 装配一致并注入mockNavigation/mockRoute替代真实导航上下文断言则用异步findByText等待查询完成后的渲染结果——恰好覆盖了「React Query 拉取 → Zod 校验 → 三态渲染」整条链路。在 detailed-guide §6 Testing 的测试金字塔中RN 的单测组合被明确记为「Jest testing-library/react-nativemswfor API mocking」与 native 栈的 JUnit5/MockK 平行域层与表现层的覆盖率目标为≥ 80%E2E 层则推荐 Maestro 跨 Flutter/RN 覆盖关键用户旅程。十二、适用边界与落地提醒结合 SKILL.md 的 Limitations 章节落地这套参考文档时应注意技能范围限定在 Android 及 Android 相邻交付路径不覆盖 iOS-only 架构与 App Store 发布操作RN 双端场景下 iOS 侧需另行对齐依赖版本号、Play Console 策略阈值会随时间变化发布关键信息需对照当前 Android / Google Play / 各库文档核实文中代码片段是架构模式而非完整应用包名、依赖版本、权限声明、隐私披露与安全控制都需要按实际项目适配该指导不能替代真机 QA、无障碍审查、安全审查、法务/隐私审查与商店合规检查。延伸阅读完整的跨栈决策、架构、构建发布与性能体系见 detailed-guide.md同目录下的 native-android.md、flutter.md、kmm.md、hybrid.md、java-android.md 覆盖其余技术栈可对照选型后按需加载。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考