Migrate from iOS 17 Observation to iOS 16-compatible Combine architecture.
Lower deployment target to iOS 16, replace @Observable with ObservableObject, add navigation and UI compatibility shims, and include login smoke UI tests. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
337
iOS16兼容迁移记录.md
Normal file
337
iOS16兼容迁移记录.md
Normal file
@ -0,0 +1,337 @@
|
||||
# iOS 16 兼容迁移记录
|
||||
|
||||
记录日期：2026-06-26
|
||||
工程：`suixinkan_ios_new`
|
||||
目标：将新 iOS 工程从 iOS 17 Observation 架构迁到 iOS 16 可运行的 Combine/SwiftUI 架构，同时保留 iOS 17+ 新 API 的局部增强能力。
|
||||
|
||||
## 背景
|
||||
|
||||
本次迁移前，工程大量使用 iOS 17 的 Observation 体系：
|
||||
|
||||
- `@Observable`
|
||||
- `@Bindable`
|
||||
- `@Environment(Type.self)`
|
||||
- `.environment(object)`
|
||||
- 双参数 `.onChange(of:) { oldValue, newValue in ... }`
|
||||
- iOS 17-only SwiftUI API，例如 `ContentUnavailableView`、`navigationDestination(item:)`
|
||||
|
||||
为了让 App 最低支持 iOS 16.0，统一迁移到 iOS 16 可用的 `ObservableObject + @Published + EnvironmentObject/EnvironmentKey` 体系。没有维护两套 RootView，也没有做运行时双架构分支。
|
||||
|
||||
## 本次完成的改动
|
||||
|
||||
### 1. Deployment Target
|
||||
|
||||
文件：
|
||||
|
||||
- `suixinkan.xcodeproj/project.pbxproj`
|
||||
|
||||
改动：
|
||||
|
||||
- App target Debug/Release：`IPHONEOS_DEPLOYMENT_TARGET = 16`
|
||||
- Test target Debug/Release：`IPHONEOS_DEPLOYMENT_TARGET = 16`
|
||||
|
||||
说明：
|
||||
|
||||
- 项目级 SDK 行里仍可看到 `26.5`，这是当前 Xcode/SDK 生成配置，不等于 app/test target 的最低系统版本。
|
||||
|
||||
### 2. 状态体系：Observation -> Combine
|
||||
|
||||
迁移规则：
|
||||
|
||||
- `@Observable class Xxx` -> `final class Xxx: ObservableObject`
|
||||
- 会驱动 UI 的字段 -> `@Published var`
|
||||
- 不驱动 UI 的依赖、client、常量、配置 -> 普通属性
|
||||
- View 持有 ViewModel：
|
||||
- `@State private var viewModel = XxxViewModel()` -> `@StateObject private var viewModel = XxxViewModel()`
|
||||
- 子视图接收 ViewModel -> `@ObservedObject`
|
||||
- 移除 `@Bindable`
|
||||
|
||||
典型文件：
|
||||
|
||||
- `suixinkan/App/State/AppSession.swift`
|
||||
- `suixinkan/App/State/AccountContext.swift`
|
||||
- `suixinkan/App/State/PermissionContext.swift`
|
||||
- `suixinkan/App/State/ScenicSpotContext.swift`
|
||||
- `suixinkan/App/State/ToastCenter.swift`
|
||||
- `suixinkan/App/Navigation/NavigationRouter.swift`
|
||||
- 各业务 `Features/*/ViewModels/*.swift`
|
||||
|
||||
保留为 `ObservableObject` 的对象主要是 UI 状态或运行时状态：
|
||||
|
||||
- `AppSession`
|
||||
- `AccountContext`
|
||||
- `PermissionContext`
|
||||
- `ScenicSpotContext`
|
||||
- `AppRouter`
|
||||
- `RouterPath`
|
||||
- `ToastCenter`
|
||||
- `ScenicQueueRuntime`
|
||||
- `ForegroundLocationProvider`
|
||||
- 各业务 ViewModel
|
||||
|
||||
已清回普通 class 的对象：
|
||||
|
||||
- `APIClient`
|
||||
- 各业务 `*API`
|
||||
- `OSSUploadService`
|
||||
- `UploadAPI`
|
||||
- token/snapshot/preferences store
|
||||
- `AuthSessionCoordinator`
|
||||
- `SessionBootstrapper`
|
||||
- `PushAPI`
|
||||
|
||||
### 3. 环境注入迁移
|
||||
|
||||
新增文件：
|
||||
|
||||
- `suixinkan/App/AppServiceEnvironment.swift`
|
||||
|
||||
状态对象使用：
|
||||
|
||||
```swift
|
||||
.environmentObject(appSession)
|
||||
.environmentObject(accountContext)
|
||||
.environmentObject(permissionContext)
|
||||
.environmentObject(scenicSpotContext)
|
||||
.environmentObject(appRouter)
|
||||
.environmentObject(toastCenter)
|
||||
.environmentObject(scenicQueueRuntime)
|
||||
```
|
||||
|
||||
页面读取：
|
||||
|
||||
```swift
|
||||
@EnvironmentObject private var appSession: AppSession
|
||||
@EnvironmentObject private var router: RouterPath
|
||||
@EnvironmentObject private var toastCenter: ToastCenter
|
||||
```
|
||||
|
||||
服务对象使用自定义 `EnvironmentKey`：
|
||||
|
||||
```swift
|
||||
.environment(\.ordersAPI, ordersAPI)
|
||||
.environment(\.profileAPI, profileAPI)
|
||||
.environment(\.ossUploadService, ossUploadService)
|
||||
```
|
||||
|
||||
页面读取：
|
||||
|
||||
```swift
|
||||
@Environment(\.ordersAPI) private var ordersAPI
|
||||
@Environment(\.ossUploadService) private var uploadService
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- `AppServiceEnvironment.swift` 里的 key 提供默认实例，避免 SwiftUI/test runner 在环境装配阶段读取 key 时崩溃。
|
||||
- RootView 仍会注入真实共享实例，默认实例主要用于 preview/test fallback。
|
||||
|
||||
### 4. RootView 和 MainTabsView
|
||||
|
||||
核心文件：
|
||||
|
||||
- `suixinkan/App/RootView.swift`
|
||||
- `suixinkan/Features/Main/Views/MainTabsView.swift`
|
||||
|
||||
主要变化：
|
||||
|
||||
- `RootView` 中全局 UI 状态改为 `@StateObject`
|
||||
- service/API 继续作为稳定引用由 RootView 创建并下发
|
||||
- `MainTabsView` 中 `AppRouter` 改为 `@EnvironmentObject`
|
||||
- 每个 tab 的 `RouterPath` 用 `.environmentObject(appRouter.router(for: tab))` 注入
|
||||
- `TabView(selection:)` 和自定义 tab 绑定改用 `$appRouter.selectedTab`
|
||||
|
||||
### 5. iOS 16 SwiftUI 兼容
|
||||
|
||||
新增文件：
|
||||
|
||||
- `suixinkan/Core/Design/AppContentUnavailableView.swift`
|
||||
- `suixinkan/App/Navigation/NavigationCompatibility.swift`
|
||||
|
||||
兼容点：
|
||||
|
||||
- `ContentUnavailableView` -> `AppContentUnavailableView`
|
||||
- `navigationDestination(item:)` -> `appNavigationDestination(item:)`
|
||||
- 双参数 `.onChange(of:)` -> iOS 16 可用的单参数形式
|
||||
|
||||
`AppContentUnavailableView` 行为：
|
||||
|
||||
- iOS 17+：内部走系统 `ContentUnavailableView`
|
||||
- iOS 16：降级为项目风格的 VStack 空状态 UI
|
||||
|
||||
`appNavigationDestination(item:)` 行为：
|
||||
|
||||
- 使用 iOS 16 可用的 `navigationDestination(isPresented:)` 包一层 optional item
|
||||
- 保留原来 optional item push 的页面行为
|
||||
|
||||
### 6. StateObject 不能直接替换实例的修复
|
||||
|
||||
迁移到 `@StateObject` 后，不能再写：
|
||||
|
||||
```swift
|
||||
viewModel = SomeViewModel(...)
|
||||
```
|
||||
|
||||
已改成 ViewModel 内部原地回填：
|
||||
|
||||
- `ProjectEditorViewModel.apply(_:)`
|
||||
- `StoreProjectEditorViewModel.apply(_:)`
|
||||
- `PunchPointEditorViewModel.apply(_:)`
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `suixinkan/Features/Projects/ViewModels/ProjectViewModels.swift`
|
||||
- `suixinkan/Features/Projects/Views/ProjectViews.swift`
|
||||
- `suixinkan/Features/PunchPoint/ViewModels/PunchPointViewModels.swift`
|
||||
- `suixinkan/Features/PunchPoint/Views/PunchPointViews.swift`
|
||||
|
||||
### 7. 推送迁移保留
|
||||
|
||||
本次 iOS 16 兼容迁移没有回退之前完成的 APNs 推送迁移。
|
||||
|
||||
相关文件仍保留：
|
||||
|
||||
- `suixinkan/Core/Push/PushAPI.swift`
|
||||
- `suixinkan/Core/Push/PushPayload.swift`
|
||||
- `suixinkan/Core/Push/PushNotificationManager.swift`
|
||||
- `suixinkan/App/AppDelegate.swift`
|
||||
- `suixinkan/suixinkan.entitlements`
|
||||
- `suixinkan/Info.plist`
|
||||
- `suixinkanTests/PushNotificationTests.swift`
|
||||
|
||||
## 验证命令
|
||||
|
||||
App build：
|
||||
|
||||
```bash
|
||||
/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild build \
|
||||
-quiet \
|
||||
-workspace suixinkan.xcworkspace \
|
||||
-scheme suixinkan \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 17'
|
||||
```
|
||||
|
||||
全量测试：
|
||||
|
||||
```bash
|
||||
/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild test \
|
||||
-quiet \
|
||||
-workspace suixinkan.xcworkspace \
|
||||
-scheme suixinkan \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 17'
|
||||
```
|
||||
|
||||
验证结果：
|
||||
|
||||
- App build：通过
|
||||
- 全量 tests：通过
|
||||
|
||||
已知 warning：
|
||||
|
||||
- Pods 里部分 AMap target 的 deployment target 为 9.0，当前 Xcode 提示支持范围为 12.0 到 26.5.99。
|
||||
- Pods dummy object 有 “built for newer iOS-simulator version 17.0 than being linked 16.0” 警告。
|
||||
- 若干 Swift 6 未来并发检查 warning，目前不影响 Swift 5 build/test。
|
||||
|
||||
## 以后从 iOS 16 迁回 iOS 17 的建议
|
||||
|
||||
如果未来确定最低版本重新升回 iOS 17，可以考虑反向迁移，但建议分阶段做。
|
||||
|
||||
### 阶段 1：先改工程配置
|
||||
|
||||
- App target Debug/Release：`IPHONEOS_DEPLOYMENT_TARGET = 17`
|
||||
- Test target Debug/Release：`IPHONEOS_DEPLOYMENT_TARGET = 17`
|
||||
|
||||
先跑：
|
||||
|
||||
```bash
|
||||
xcodebuild build -workspace suixinkan.xcworkspace -scheme suixinkan -destination 'platform=iOS Simulator,name=iPhone 17'
|
||||
xcodebuild test -workspace suixinkan.xcworkspace -scheme suixinkan -destination 'platform=iOS Simulator,name=iPhone 17'
|
||||
```
|
||||
|
||||
### 阶段 2：是否迁回 Observation
|
||||
|
||||
不一定必须迁回。即使最低版本是 iOS 17，`ObservableObject + @Published` 仍然可以继续使用。
|
||||
|
||||
只有在明确想利用 Observation 的简化语法时，再迁回：
|
||||
|
||||
- `ObservableObject` 状态/ViewModel -> `@Observable`
|
||||
- `@Published` -> 普通 `var`
|
||||
- `@StateObject` -> `@State`
|
||||
- `@ObservedObject` -> 普通属性或 `@Bindable`
|
||||
- `@EnvironmentObject` -> `@Environment(Type.self)`
|
||||
- `.environmentObject(object)` -> `.environment(object)`
|
||||
|
||||
建议优先迁回这些核心状态：
|
||||
|
||||
- `AppSession`
|
||||
- `AccountContext`
|
||||
- `PermissionContext`
|
||||
- `ScenicSpotContext`
|
||||
- `AppRouter`
|
||||
- `RouterPath`
|
||||
- `ToastCenter`
|
||||
- `ScenicQueueRuntime`
|
||||
|
||||
然后再考虑业务 ViewModel。
|
||||
|
||||
### 阶段 3：服务注入可以不迁回
|
||||
|
||||
即使回到 iOS 17，也建议保留当前 `AppServiceEnvironment.swift` 的 service key 注入方式。
|
||||
|
||||
原因：
|
||||
|
||||
- service/API 本质不是 UI 状态
|
||||
- 自定义 EnvironmentKey 更清晰地区分 service 与 observable state
|
||||
- 对测试和 preview 更稳定
|
||||
|
||||
### 阶段 4：恢复 iOS 17 SwiftUI API
|
||||
|
||||
可选恢复：
|
||||
|
||||
- `AppContentUnavailableView(...)` -> `ContentUnavailableView(...)`
|
||||
- `.appNavigationDestination(item:)` -> `.navigationDestination(item:)`
|
||||
- 单参数 `.onChange(of:)` 可继续保留；iOS 17 兼容单参数版本
|
||||
|
||||
建议：
|
||||
|
||||
- `AppContentUnavailableView` 可以继续保留，因为它内部 iOS 17+ 已经走系统 `ContentUnavailableView`。
|
||||
- `appNavigationDestination(item:)` 也可以继续保留，除非想彻底减少兼容层。
|
||||
|
||||
## 给未来 Codex 的提示词
|
||||
|
||||
如果未来要迁回 iOS 17，可以把下面这段发给 Codex：
|
||||
|
||||
```text
|
||||
请基于仓库中的 iOS16兼容迁移记录.md，帮我评估并执行从 iOS 16 兼容架构迁回 iOS 17 的改造。
|
||||
|
||||
要求：
|
||||
1. 先检查当前代码和 git diff，不要假设记录完全最新。
|
||||
2. 先把 app/test target 的 IPHONEOS_DEPLOYMENT_TARGET 改到 17。
|
||||
3. 优先判断是否真的需要迁回 Observation；如果迁回，先迁核心状态对象，再迁业务 ViewModel。
|
||||
4. service/API/store 继续保持普通 class + EnvironmentKey 注入，除非有明确收益。
|
||||
5. 可以把 AppContentUnavailableView 和 appNavigationDestination 视情况恢复为 iOS 17 原生 API。
|
||||
6. 迁移完成后跑 xcodebuild build 和 xcodebuild test。
|
||||
7. 不要删除现有 APNs 推送迁移代码。
|
||||
```
|
||||
|
||||
## 快速检查命令
|
||||
|
||||
检查是否还有 iOS 17 Observation 残留语法：
|
||||
|
||||
```bash
|
||||
rg -n "import Observation|@Observable|@ObservationIgnored|@Environment\\([A-Za-z0-9_]+\\.self\\)|@Bindable|onChange\\(of:.*\\{\\s*_,|navigationDestination\\(item:" suixinkan --glob '*.swift'
|
||||
```
|
||||
|
||||
检查 target deployment：
|
||||
|
||||
```bash
|
||||
rg -n "IPHONEOS_DEPLOYMENT_TARGET" suixinkan.xcodeproj/project.pbxproj
|
||||
```
|
||||
|
||||
检查 service/API 是否误变成 ObservableObject：
|
||||
|
||||
```bash
|
||||
rg -n "class .*ObservableObject" suixinkan/Core suixinkan/App/State suixinkan/Features/*/API
|
||||
```
|
||||
|
||||
正常情况下，service/API/store 不应出现在最后这个结果里；UI 状态对象和 ViewModel 可以是 `ObservableObject`。
|
||||
Reference in New Issue
Block a user