# 移动开发指南 ## 概述本指南涵盖原生 iOS/Android 开发（SwiftUI、Jetpack Compose）和跨平台框架（React Native、Flutter）以及离线优先架构、平台集成和性能优化的模式。在选择平台策略、构建移动 UI 或集成设备功能时使用它。 ## 平台选择指南 * 当应用程序需要深度平台集成（小部件、扩展、AR、自定义相机管道）时，使用 **native** (SwiftUI/Compose)。 * 当团队规模较小且应用程序主要用于数据显示和表单时，请使用 **React Native 或 Flutter**。 * 对于 iOS，将 SwiftUI 与 `@Observable` (iOS 17+) 或 `@StateObject`/`@ObservedObject` (iOS 15+) 结合使用；仅针对不支持的功能回退到 UIKit。 * 对于 Android，使用 Jetpack Compose 和 Hilt 进行 DI，使用 `StateFlow` 进行响应式状态；避免在新屏幕中使用 XML 布局。 * 对于导航，请使用带有类型化路线的“NavigationStack”（iOS）或“Navigation Compose”（Android）。 ## 性能和用户体验规则 * 中端设备上的冷启动时间必须低于 2 秒；推迟第一帧不需要的初始化。如果冷启动超过 1.5 秒，请使用 Instruments (iOS) 或“reportFullyDrawn()” (Android) 进行分析，并将繁重的工作移至后台。 * 在落后当前设备两代的设备上保持 60fps 滚动。如果发生丢帧：在 iOS 上，检查主线程外图像解码并使用“prefetchDataSource”；在 Android 上，启用“compositionStrategy = ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed”并使用布局检查器检查是否存在不必要的重新组合。 * 动画：使用 SwiftUI `.animation()` / 编写 `animateFloatAsState`；保持持续时间 200-350 毫秒。切勿对布局属性（帧大小、填充）进行动画处理 - 仅对不透明度和偏移进行动画处理。 * 离线优先：本地数据库（Core Data、Room、SQLite/Drift）作为单一事实来源，后台服务器同步。如果应用程序具有 >3 个具有关系的实体类型，请使用 Core Data (iOS) 或 Room (Android) — 切勿使用原始 SQLite。 * 使用 Xcode Energy Diagnostics 或 Android Battery Historian 分析电池；修复任何使 CPU 处于唤醒状态 >2 秒而无需用户交互的操作。 * 批量网络请求；使用后台会话（URLSession / WorkManager）进行大量传输。如果有效负载>1MB，则使用后台传输；如果 >10MB，则添加断点续传支持。 * 与时间戳或更改令牌的增量同步而不是完整集合获取。如果集合有>500个项目，则分页与光标同步；永远不要获取全部。 * 带有缓存的延迟加载图像（iOS 上的 Kingfisher/SDWebImage，Android 上的 Coil）；缩小至显示尺寸。如果列表显示 >20 个图像，请实现内存缓存上限（iOS 50MB，Android 100MB）和磁盘缓存上限（200MB）。 * 应用程序二进制大小：目标 <50MB iOS，<30MB APK（或对 Android 使用 AAB）。如果超过阈值，请使用“scripts/check_app_size.sh”进行审核，删除未使用的资产，并启用应用程序精简（iOS）或动态功能模块（Android）。 * 网络超时：API调用10秒，文件上传30秒。如果请求失败，请使用指数退避（1 秒、2 秒、4 秒）重试，最多尝试 3 次。切勿重试非幂等请求（没有幂等密钥的 POST）。 * 内存：使用 `os_signpost` (iOS) / `Debug.getNativeHeapAllocationSize()` (Android) 进行监控。如果中端设备上的内存超过 200MB，请使用 Instruments Allocations 或 Android Studio Memory Profiler 进行调查。在发货前修复保留周期 (iOS) 或泄漏的 ViewModel (Android)。 ## 平台集成规则 * 生物识别身份验证：`LAContext` (iOS) / `BiometricPrompt` (Android)，带密码回退；切勿存储原始生物识别数据。如果设备缺乏生物识别技术，请使用设备密码——切勿完全跳过身份验证。使用 setUserAuthenticationRequired(true) 将身份验证令牌存储在 Keychain (iOS) / AndroidKeystore 中。 * 相机：及时请求权限，通过设置深层链接处理拒绝。如果权限被拒绝两次，则使用“打开设置”按钮显示内联解释 - 永远不会通过系统对话框重新提示（iOS 会阻止它）。 * 推送通知：APNs (iOS) / FCM (Android) 以及基于主题的订阅。仅在用户执行受益于通知的操作后请求权限 - 切勿在首次启动时请求权限。如果用户拒绝，则存储首选项并显示应用内切换；仅在 30 天后重新提示。 * 请勿通过此技能实施或触发购买、计费、支付或其他资金流动流程。如果用户需要应用内购买，请将指导限制在权利建模、收据验证架构、审计要求和平台政策审查方面；将交易执行详细信息发送至专门的付款审核。 * 深层链接：使用通用链接 (iOS) / 应用程序链接 (Android) — 而不是自定义 URL 方案。验证“apple-app-site-association”和“assetlinks.json”是否由具有正确内容类型的域提供。为单击链接后安装的用户测试延迟深层链接。 ## 特定于平台的 UI * iOS：SF 符号、系统字体（旧金山）、动态类型支持。如果需要自定义字体，则最多限制为 2 个系列。支持从“xSmall”到“accessibility5”的所有动态字体大小 - 切勿使用固定字体大小。 * Android：Material Design 3 令牌，Compose 中的“MaterialTheme”。对所有颜色使用“MaterialTheme.colorScheme”——切勿对十六进制值进行硬编码。从第一天起就通过“isSystemInDarkTheme()”支持深色主题。 * 触摸目标：最小 44x44pt (iOS) / 48x48dp (Android)。如果交互式元素较小，请使用“.contentShape()”(SwiftUI) 或“Modifier.minimumInteractiveComponentSize()”(Compose) 扩展点击区域。 * 敏感数据：钥匙串 (iOS) / EncryptedSharedPreferences (Android)。切勿将令牌、密码或 PII 存储在 UserDefaults/SharedPreferences 中。如果数据必须在应用程序重新安装后保留，请将钥匙串与“kSecAttrAccessibleAfterFirstUnlock”一起使用。 * 权限：在系统提示之前解释，优雅地处理拒绝，绝不阻止整个应用程序。如果需要 >3 个权限，请在使用功能时逐步请求它们 - 切勿在启动时批量请求。 ## 代码示例请参阅 [SwiftUI 指南]()，获取包含 NavigationStack、搜索、分页和下拉刷新的完整产品列表。有关 Hilt、StateFlow、LazyColumn 和去抖动搜索的完整产品列表，请参阅 [Jetpack Compose 指南]()。有关包含 FlatList、react-query 无限滚动和平台样式的完整产品列表，请参阅 [React Native 指南]()。请参阅 [Flutter 指南]()，获取包含 Riverpod、ListView.builder、去抖搜索、分页和下拉刷新的完整产品列表。有关离线队列系统（NetInfo + AsyncStorage、Core Data + CloudKit、Room + WorkManager）、冲突解决（LWW、字段级合并、CRDT）和带回滚功能的乐观 UI，请参阅[离线优先架构]()。请参阅 [性能模式]() 了解 Hermes 引擎配置、FlatList 优化（getItemLayout、windowSize）、SwiftUI 惰性堆栈和图像缓存、使用 Coil 进行的 Compose 重组控制、电池优化、内存泄漏预防和冷启动优化。请参阅[状态管理]()，了解具有 MMKV 持久性的 Zustand、TanStack 查询乐观突变、具有环境注入的 SwiftUI @Observable、Compose ViewModel + StateFlow + SavedStateHandle、导航深度链接、身份验证状态机和表单验证。有关推送通知（APNs、FCM、react-native-firebase）、相机/照片（CameraX、AVFoundation、vision-camera）、生物识别身份验证（FaceID/TouchID、 BiometricPrompt）、后台任务（BGTaskScheduler、WorkManager）以及应用商店订阅的非事务性权利架构说明。 ## 平台特定的陷阱 ### iOS 后台任务限制 * `BGAppRefreshTask`：系统授予约 30 秒的执行时间。如果任务未在该窗口内调用“setTaskCompleted”，系统将终止它并降低未来请求的优先级。 * `BGProcessingTask`：最多 3 分钟，但仅在设备充电且连接 Wi-Fi 时运行。不要依赖它来进行时间敏感的同步。 * 推送通知唤醒应用程序后（“内容可用：1”），您大约需要 30 秒。如果工作需要更长的时间，请启动“URLSession”后台下载。 * 系统学习用户行为。如果用户从未在上午 8 点打开您的应用程序，则您的上午 8 点后台刷新将不会运行。针对错过的刷新进行设计 - 始终在前台进行完整的追赶同步。 ### Android 后台限制 * **打瞌睡模式** (Android 6+)：屏幕关闭+静止后，网络访问将批量进入维护窗口（约每 15 分钟一次，增加到约 1 小时）。具有“NetworkType.CONNECTED”约束的“WorkManager”将推迟到下一个窗口。对于紧急消息，请使用 FCM 高优先级消息（限制前限制为每天约 10 条）。 * **应用程序待机存储桶** (Android 9+)：应用程序按“活跃”→“工作集”→“频繁”→“稀有”→“受限”排序。稀有/受限应用程序的工作和警报受到严格限制。如果您的应用程序位于受限存储桶中，则“WorkManager”定期工作可能每 24 小时仅运行一次。 * **精确闹钟** (Android 12+)：`setExactAndAllowWhileIdle()` 需要 `SCHEDULE_EXACT_ALARM` 权限。用户可以在“设置”中撤销它。在调度之前始终检查“canScheduleExactAlarms()”并回退到不精确。 * **前台服务类型** (Android 14+)：必须在清单中声明 `foregroundServiceType`。类型：`camera`、`location`、`mediaPlayback`、`dataSync` 等。使用错误的类型 → 崩溃。 `dataSync` 类型限制为 6 小时。 ### Flutter 特定的陷阱 * **`const` 构造函数**：对于无状态小部件和不变的小部件子树，始终使用 `const`。如果没有 `const`，Flutter 会在父重建时重建整个子树。这是 Flutter 的第一大性能问题。 * **`Keys`** ：当列表可以重新排序、插入或删除时，在列表项上使用 `ValueKey`。如果没有键，Flutter 会错误地重用状态 - 用户在 TextField A 中键入，删除项目，然后文本出现在项目 B 中。 * **平台通道** ：Dart 和本机（iOS/Android）之间的调用是异步和序列化的。如果您在紧密循环中调用平台通道（>100 次调用/秒），请将数据批处理到单个调用中。将“BasicMessageChannel”与二进制编解码器结合使用以实现大负载。 * **隔离** ：Dart 是单线程的。对于 >16ms 的 CPU 工作（JSON 解析大型响应、图像处理），请使用 `Isolate.run()` (Dart 2.19+) 或 `compute()`。切勿在主隔离区上解析 >100KB JSON。 * **图像缓存** ：Flutter 默认的“Image”小部件将解码后的图像缓存在内存中，没有限制。对于包含 > 50 个图像的列表，请使用“cached_network_image”和“memCacheHeight”/“memCacheWidth”来缩小规模，否则内存将无限增长。 * **状态恢复** ：在 Android 上，系统会主动杀死后台应用程序。使用“RestorationMixin”或将关键状态保存到磁盘。如果用户填写了 10 个字段的表单，切换到另一个应用程序，然后返回到空白表单 - 这就是一个错误。 ### 特定于 Compose 的陷阱 * **重组** ：任何捕获可变值的 lambda 都会触发其父级的重组。传递“remember”-ed lambdas 或使用“drivenStateOf”进行昂贵的计算。使用布局检查器 >“显示重组计数”来查找热点。 * **稳定性** ：Compose 会跳过“@Stable”或“@Immutable”类型的重组。如果您的数据类使用“List”（不稳定），Compose 每次都会重新组合。如果保证不变性，请使用“kotlinx.collections.immutable.ImmutableList”或使用“@Immutable”进行注释。 * **`LazyColumn` 项目键**：始终在 `items(key = { it.id })` 中提供 `key`。如果没有键，滚动位置会在列表突变时中断，并且动画会失败。 ## 离线同步决策规则 ### 冲突解决策略 * **最后写入优先 (LWW)** ：当数据归用户所有且很少同时编辑（用户配置文件、设置、个人注释）时使用。简单：比较时间戳、最新胜利。风险：如果两台设备同时编辑，则无声数据丢失。 * **字段级合并** ：当可以在不同设备上编辑同一记录的不同字段时使用（例如，用户在手机上编辑“姓名”，在平板电脑上编辑“电子邮件”）。合并非冲突的字段更改，标记冲突字段以供手动解决。需要跟踪每个字段的时间戳。 * **操作转换/CRDT**：仅用于实时协作编辑（共享文档、协作白板）。实现起来很复杂——使用库（Yjs、Automerge）。切勿构建自定义 OT/CRDT。 * **排队并重试**：用于只写操作（表单提交、分析事件、聊天消息）。在本地排队，在线时发送，使用幂等键重试。不可能发生冲突，因为每个操作都是独立的。 ### 同步架构决策规则 * 如果应用程序的实体类型少于 5 个，并且同步仅在用户到服务器之间进行（无协作）：使用基于时间戳的增量同步。客户端发送“lastSyncTimestamp”，服务器返回自该时间戳以来更改的记录。 * 如果应用程序有 5-15 个实体类型或需要服务器到客户端推送：使用更改令牌 (CloudKit) 或服务器发送的事件。客户端存储同步游标，服务器推送增量。 * 如果应用程序支持实时协作（多个用户编辑相同数据）：使用带有 OT/CRDT 库的 WebSocket。这是简单同步复杂性的 10 倍 — 仅当协作是核心要求时才选择它。 ## 应用程序生命周期决策规则 ### 强制更新策略 * **关键安全补丁**：使用全屏模式强制阻止应用程序。没有解雇选项。根据远程配置（`/api/min-version`）检查每个应用程序的启动。 * **重大 API 更改**：显示带有链接到商店的“立即更新”按钮的阻止模式。在阻止之前允许有 2 周的宽限期，并带有可关闭的横幅。 * **新功能** ：切勿强制更新功能。显示可关闭的横幅。如果用户忽略 3 次，则停止显示 30 天。 * **实现** ：将 `minSupportedVersion` 存储在远程配置中（Firebase 远程配置、LaunchDarkly 或简单的 API 端点）。与应用程序启动时的内部版本号进行比较。切勿对版本检查进行硬编码。 ### 应用程序版本之间的迁移 * 如果本地数据库架构发生更改：使用版本化迁移（Room `@Database(version = N)`、Core Data 轻量级迁移、Drift 架构版本控制、Hive 类型适配器）。始终测试从版本 N-2 到 N 的迁移（用户跳过版本）。 * 如果身份验证令牌更改格式：同时支持新旧令牌格式 2 个发布周期。永远不要使单个版本中的所有会话失效——用户会大量支持。 * 如果切换后端端点：使用远程配置逐渐转移流量。 1 周内 10% → 50% → 100%。如果任何阶段的错误率 >1%，请暂停并进行调查。 ## 反模式 * 切勿将“@ObservedObject”用于当前视图拥有的状态 - 使用“@StateObject”(iOS 15) 或“@State”与“@Observable”(iOS 17+)。 `@ObservedObject` 仅适用于注入的依赖项。 * 切勿在 Compose 中的 ViewModel 之外使用 `mutableStateOf` — 所有可变状态都存在于 ViewModel 中，UI 通过 `collectAsStateWithLifecycle()` 进行观察。 * 切勿在 Flutter 中已处置的小部件上调用 `setState` — 始终在异步状态更新之前检查 `mounted`。在 Riverpod 中，使用 ref.onDispose() 取消异步工作。 * 在 React Native 中，切勿在没有“keyExtractor”和“getItemLayout”的情况下使用“FlatList”——如果没有这些，列表 > 50 个项目上的滚动性能会急剧下降。 * 切勿将导航状态存储在全局存储中 - 使用平台导航堆栈。全局导航状态会导致后退按钮错误和深层链接失败。 * 切勿通过同步数据库读取来阻塞主线程 - 使用 `withContext(Dispatchers.IO)` (Android) / 后台 actor (iOS) / `InteractionManager.runAfterInteractions` (React Native) / `Isolate.run()` (Flutter)。 * 切勿在 Flutter 的主线程上解析大型 JSON（>100KB）——使用“compute()”或“Isolate.run()”。在 Android 上，切勿在主线程上执行网络或磁盘 I/O - `StrictMode` 将在调试版本中捕获此情况。 * 切勿在没有后备的情况下使用特定于平台的代码。如果插件仅适用于 iOS，则 Android 版本不得崩溃——它应该正常降级或显示“在此平台上不可用”。 ## 工作流程 ### 第 1 步：平台策略和设置 * 选择本机还是跨平台：如果应用程序需要 AR、自定义相机或小部件，请选择本机。如果应用程序是数据显示+具有<3个平台特定功能的表单，请跨平台。 * 设置最低操作系统版本：iOS 16+（如果是企业则为 15+）、Android API 26+ (Android 8.0)。如果目标年龄较大，请记录原因。 * 配置构建工具：Xcode + SwiftPM (iOS)、带有版本目录的 Gradle (Android)、带有 EAS Build 的 Expo (React Native) 或带有 `flutter_lints` 的 Flutter 和用于 CI 的 Fastlane/Codemagic。 ### 第 2 步：架构和设计 * 如果应用程序离线工作，请在 API 架构之前设计本地优先架构。定义冲突解决策略（LWW 用于简单，字段级合并用于协作）。 * 在构建 UI 之前定义包含所有屏幕、模式和深层链接路线的导航图。 * 选择状态管理：`@Observable` \+ SwiftData (iOS 17+)、ViewModel + StateFlow (Android)、Zustand + TanStack Query (React Native)、Riverpod + Drift/Isar (Flutter)。 ### 步骤 3：开发和集成 * 首先构建关键用户流程（入职 → 核心行动 → 结果）。在核心流程端到端运行之前，请勿构建设置、配置文件或辅助流程。 * 一次集成一项平台功能（摄像头、通知、生物识别）。在移动到下一个之前，请在真实设备上测试每个设备。 * 在第一次 TestFlight/内部跟踪发布之前添加崩溃报告（Crashlytics/Sentry）和基本分析。 ### 步骤 4：测试和部署 * 在真实设备上进行测试：至少 2 台 iOS 设备（最旧支持的 + 当前）和 3 台 Android 设备（低端、中端、旗舰）。 * 对 CI 上的关键流程运行 UI 测试。单元测试 ViewModels/存储库，覆盖率 >80%。 * 设置 Fastlane (iOS) 或 Gradle Play Publisher (Android) 以自动提交商店。 ## 自验证协议完成任何移动实施后，请在提交审核之前进行验证： * 在真实设备（不仅仅是模拟器）上运行应用程序。模拟器隐藏了性能、内存和手势问题。 * 离线测试核心流程：启用飞行模式、执行操作、重新启用网络、验证同步。如果应用程序崩溃或离线丢失数据，则说明它还没有准备好。 * 中档设备上的配置文件内存。如果峰值内存超过 200MB，请在发货前进行调查。 * 测量最旧的受支持设备上的冷启动时间。如果 >2 秒，则将初始化推迟到第一帧之后。 * 通过用手指而不是鼠标光标点击每个交互元素来验证所有触摸目标 >=44pt (iOS) / >=48dp (Android)。 * 在每个屏幕上检查深色模式。如果任何文本不可读或任何元素不可见，请在合并之前修复。 * 使用动态类型 (iOS) / 字体比例 200% (Android) 进行测试。如果文本截断或重叠，请修复布局。 * 在核心流程上使用 VoiceOver (iOS) / TalkBack (Android) 运行应用程序。每个互动元素都必须有意义地宣布。 * 检查日志中是否出现敏感数据（令牌、密码、PII）。在流程中运行 `adb logcat` (Android) 或 Console.app (iOS)。 ## 故障恢复 * **应用程序在启动时崩溃**：检查崩溃日志中的确切行。常见原因：强制解开 nil (Swift)、未初始化的 Lateinit (Kotlin)、缺少本机模块 (React Native)。如果崩溃发生在第三方库中，请固定以前的版本并提交问题。 * **Xcode/Gradle 更新后构建失败**：清理派生数据（`rm -rf ~/Library/Developer/Xcode/DerivedData`）或 Gradle 缓存（`./gradlew clean`）。如果仍然失败，请检查发行说明以了解构建工具中的重大更改。将工具链版本固定在项目中，直到问题得到解决。 * **UI 在设备与模拟器上的渲染方式不同**：模拟器使用 Mac GPU。在真实设备上进行测试。对于布局问题，请检查硬编码像素值（使用 pt/dp 代替）和安全区域插图。 * **添加功能后性能下降**：使用 Instruments (iOS) 或 Android Studio Profiler 进行分析。检查：主线程阻塞、过度重组/重新渲染、没有缓存的大图像加载或泄漏的订阅/观察者。 * **推送通知未到达**：验证：(1) 有效的 APN/FCM 令牌，(2) 正确的捆绑包 ID/包名称，(3) 证书/密钥未过期，(4) 设备未处于抑制后台活动的低功耗模式。在调试应用程序代码之前，通过“curl”手动推送到 APNs/FCM 进行测试。 * **应用程序被 App Store / Play Store 拒绝**：准确阅读拒绝原因。常见：缺少隐私政策 URL、不完整的应用程序隐私详细信息 (iOS)、缺少数据安全表单 (Android) 或无正当理由的后台位置使用。修复元数据——不要猜测。 ## 现有应用程序方向接管或加入现有移动项目时： 1. **构建并运行**（15 分钟）— 克隆、安装 deps、构建并在真实设备上运行。如果失败，请先修复构建。 2. **确定架构模式**（10 分钟）——MVC、MVVM、MVI 还是非结构化？检查：状态住在哪里？数据如何从API流向UI？ 3. **绘制导航图**（10 分钟）— 列出所有屏幕及其连接方式。检查深层链接处理程序。记下正在使用的任何导航库。 4. **检查依赖项列表**（5 分钟）— Podfile/SPM (iOS)、build.gradle (Android)、package.json (React Native)。标记过时或废弃的依赖项。 5. **运行现有测试**（5 分钟）— 注意覆盖范围、测试类型以及哪些流程未经测试。 6. **检查特定于平台的债务**（5 分钟）— 已弃用的 API（检查 Xcode 警告、Android lint）、缺少权限声明、硬编码字符串（本地化准备情况）。 7. **分析应用程序**（10 分钟）— 冷启动时间、内存使用情况、最重列表屏幕上的滚动性能。这些数字是您的基线。 ## 脚本 ### `scripts/check_app_size.sh` 分析移动应用程序构建输出目录的大小问题。将构建输出目录作为参数，查找应用程序二进制文件/捆绑包（.app、.apk、.aab、.ipa），报告总大小、最大文件和按类别划分的资产细分。如果总数超过常见阈值（iOS 为 50MB，Android 为 150MB），则会发出警告。脚本/check_app_size.sh ./build/outputs/apk/release 脚本/check_app_size.sh --threshold-ios 40 --top-files 10 ./DerivedData/Build/Products/Release-iphoneos ### `scripts/check_permissions.py` 从 AndroidManifest.xml 或 Info.plist 中提取并审核权限。识别请求的权限，标记潜在危险的权限（摄像机、位置、联系人等）并进行说明，并报告总权限计数。支持JSON输出。脚本/check_permissions.py 应用程序/src/main/AndroidManifest.xml 脚本/check_permissions.py --format json ios/Runner/Info.plist

工程移动应用程序生成器

包含技能