---
title: "重构 SwiftUI 界面"
description: "说明如何让 Codex 拆分过大的 SwiftUI screen，在不改行为的前提下降低后续维护成本。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

当一个 SwiftUI file 长成巨大的 screen，`body` 里混着 layout、branching、async work 和 inline actions，每次小改都会变得高风险。这个用例的目标不是重设计 feature，也不是引入新架构，而是在不改变行为和布局的前提下，把 screen 拆成小的 subviews，让下一次修改更容易 review。

> [!CAUTION]
> SwiftUI 重构的边界是 behavior-preserving。不要借机换架构、改导航、改视觉、改 analytics 或重写业务逻辑，除非这些变化被明确列为单独任务并有验证证据。

官方页面：[https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor](https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor)

## 适合什么任务

| 场景 | Codex 应该做什么 |
|---|---|
| 巨大的 SwiftUI screen 很难 review | 拆出 meaningful section views，保持 explicit data flow |
| 现有 iOS feature 视觉和行为都不能变 | 只做结构重构，并用 build/test/simulator checks 验证 |
| `body` 里混着 side effects 和 business logic | 把 non-trivial actions 移到 methods，把业务逻辑移到 services 或 models |
| screen 里有 optional view models 或 state plumbing | 修 Observation ownership，优先 MV-first，不默认加 view model |

## 使用的能力

| 能力 | 用法 | 链接 |
|---|---|---|
| `build-ios-apps` | 使用 SwiftUI view refactor skill，抽取 subviews、稳定 data flow、简化 Observation，并保持行为不变 | [https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) |

相关官方说明：

- Build iOS Apps plugin：[https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示词

```text
请使用 Build iOS Apps plugin 和其中的 SwiftUI view refactor skill，清理 [NameOfScreen.swift]，但不要改变 screen 的行为或外观。

约束：
- 保持 behavior、layout、navigation 和 business logic 不变；如果发现必须单独指出的 bug，请明确说明。
- 默认采用 MV，而不是 MVVM。引入新 view model 前，优先使用 `@State`、`@Environment`、`@Query`、`.task`、`.task(id:)` 和 `onChange`；只有这个 feature 明确需要时，才保留 view model。
- 重新整理 view 顺序，让 stored properties、computed state、`init`、`body`、view helpers 和 helper methods 从上到下容易扫描。
- 把有意义的 sections 抽成独立 `View` types，使用小而明确的 inputs、`@Binding`s 和 callbacks。不要把一个巨大 `body` 换成一堆巨大的 computed `some View` properties。
- 把 non-trivial button actions 和 side effects 从 `body` 移到小 methods，把真正的 business logic 移到 services 或 models。
- 保持 root view tree 稳定。局部 conditional sections 或 modifiers 足够时，避免用 top-level `if/else` 切换完全不同的 screens。
- 重构时修正 Observation ownership：iOS 17+ 上 root `@Observable` models 由 owning view 用 `@State` 持有；除非 UI 确实需要这种 state shape，否则避免 optional 或 delayed-initialized view models。
- 每完成一次 extraction，运行最小有用 build 或 test check，证明 screen 行为仍然一致。

交付：
- 重构后的 screen 和抽取出的 subviews
- 简短解释新的 subview boundaries 和 data flow
- 哪些地方有意保留了 view model，以及原因
- 你运行过哪些 validation checks 来证明行为保持不变
```

这个 prompt 明确要求 behavior-preserving refactor。Codex 不能把重构变成架构重写。

## 推荐技术面

| 需要 | 推荐默认值 | 原因 |
|---|---|---|
| UI architecture | SwiftUI，MV-first，围绕 `@State`、`@Environment` 和 small dedicated `View` types 拆分 | 大 screen 通常先简化 view tree 和 state flow，再决定是否真的需要 view model |
| Refactor workflow | [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) | SwiftUI view refactor skill 提供 extraction、Observation 和 side-effect cleanup 规则 |
| Validation | `xcodebuild`、previews、focused UI checks | 每次 extraction 后跑小验证，比一次性大改更可信 |

## 要求 Codex 做什么

把这些规则直接放进 prompt：

- 按 environment dependencies、stored properties、computed non-view state、`init`、`body`、view helpers、helper methods 的顺序整理文件。
- 抽取 meaningful sections 到 dedicated `View` types。
- 子视图只接收 small explicit inputs、`@Binding`s 和 callbacks。
- computed `some View` helpers 保持少而小。
- 不要把一个巨大 `body` 改成一长串 private computed view fragments。
- non-trivial button actions 和 side effects 移出 `body`。
- 业务逻辑放进 services 或 models。
- root view tree 保持稳定，尽量使用局部 conditional sections 或 modifiers。
- iOS 17+ root `@Observable` models 由 owning view 用 `@State` 持有。

## 小验证循环

行为不变的重构必须有证据。要求 Codex 每完成一个 meaningful extraction 后，运行最小有用验证：

- build。
- preview。
- focused unit / UI test。
- simulator check。

最后让它总结：

- 结构上改了什么。
- 哪些行为、导航、业务规则、持久化、analytics semantics 和 user-visible layout 没有改。
- 哪些 view model 被保留，以及为什么。

## 实用建议

### 先拆分，再争论架构

如果 screen 太大，先抽 section views。更短、更明确的 view tree 往往会自然降低加 view model 的需求。

### 给子视图最小接口

优先传 `let` values、`@Binding`s 和单一用途 callbacks，不要把整个 parent model 传给每个 child view。

### 让 Codex 列出 intentional non-changes

安全重构最需要的是可 review。让 Codex 明确写出它没改哪些东西，能显著降低 review 成本。

## 接下来去哪

<Cards>
  <Card title="iOS 模拟器修 Bug" description="重构后需要在 simulator 里复现和验证关键流程。" href="/docs/codex/official/08-scenarios/101-ios-simulator-bug" />
  <Card title="构建 iOS 应用" description="需要从脚手架、build 和 debug 建立更完整 iOS 工作流。" href="/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="原生应用路线" description="按 iOS、macOS 和平台工具链选择后续学习顺序。" href="/docs/codex/official/07-learning-paths/77-native-app-path" />
  <Card title="官方 SwiftUI refactor" description="需要最新 use case 和插件说明时回官方页面核验。" href="https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor" />
</Cards>
