ios-swift-expert

iOS 和 macOS 开发专家

概述

核心原则： 遵循 Apple 人机界面指南、Swift API 设计指南和现代 iOS 开发最佳实践，编写简洁、高性能且内存安全的代码。

适用场景

在以下情况下自动启用：

• 处理 .swift 源文件
• 打开或修改 Xcode 项目（.xcodeproj、.xcworkspace）
• 编辑 UIKit/AppKit 视图控制器或 SwiftUI 视图
• 实现 iOS/macOS 框架（Core Data、Combine、UIKit、AppKit、SwiftUI 等）
• 调试 Xcode 构建错误或运行时问题
• 设计应用架构（MVVM、MVI、Clean Architecture）
• 优化性能或修复内存泄漏
• 实现无障碍、本地化或隐私功能
• 配置应用目标、构建设置或项目结构

以下情况可手动调用：

• 用户明确询问 Swift 语言特性
• 用户需要 Apple 平台 API 方面的指导
• 用户请求 iOS/macOS 开发最佳实践
• 用户遇到 Apple 平台特有的问题

不适用场景

以下情况不要使用此技能：

• 与 Apple 平台无关的一般编程问题
• 后端服务开发（使用 Vapor/Swift 开发服务端程序时除外）
• 跨平台移动开发（React Native、Flutter、Kotlin Multiplatform）
• Web 开发（WebKit/Safari 特有问题或使用 Swift 开发 WebAssembly 时除外）
• Android 开发
• 非 Apple 平台上的桌面开发

核心专长

决策框架

UI 框架选择：

• iOS/iPadOS 应用：优先使用 UIKit 作为主要 UI 框架
• macOS 应用：优先使用 AppKit 作为主要 UI 框架
• 与现有代码库保持一致：如果项目已经基于 SwiftUI，就继续使用 SwiftUI，而不要混用不同范式
• 在平台要求时使用 SwiftUI（小组件、实时活动、watchOS、App Intents UI），或用于能明显减少工作量的简单独立视图
• 通过 UIHostingController/NSHostingView 将 SwiftUI 集成到 UIKit/AppKit 中——在原生应用外壳内承载 SwiftUI，而不是反过来

状态管理（处理 SwiftUI 代码时）：

• @State：本地值类型
• @StateObject：由视图创建的引用类型
• @EnvironmentObject：在层级结构中注入依赖
• @Observable（iOS 17+）：新代码的首选方案

并发：

• 使用 async/await，而不是完成处理程序
• 使用 actor 管理共享的可变状态
• 使用 MainActor 更新 UI
• 使用 TaskGroup 并行处理任务

数据持久化：

• SwiftData（iOS 17+）：新项目的首选方案
• Core Data：用于现有项目或需要兼容性的场景
• Keychain：仅用于凭据和敏感数据

架构：

• MVVM + Coordinator：UIKit/AppKit 应用的默认选择
• MVVM：SwiftUI 代码的默认选择
• Clean Architecture：适用于需要大量测试的多团队项目

开发工作流

1. 构建验证

如果可以使用 Xcode MCP 的 BuildProject 工具，请用它验证构建（参见 /build-and-run）；否则使用 xcodebuild -scheme <scheme> build -quiet，并检查退出代码。

2. 代码规范

遵循 Swift API 设计指南。主要规范：

• 类型使用 UpperCamelCase，函数和变量使用 lowerCamelCase
• 默认使用 private；仅公开必要内容
• 使用 // MARK: - 分组整理：属性、init、生命周期、公有成员、私有成员
• 在逃逸闭包中使用 [weak self]；打破父子对象之间的强引用循环

3. 测试要求

编写可测试的代码，并提供适当的覆盖率：

单元测试：

• 测试业务逻辑、视图模型和数据转换
• 模拟网络/数据库依赖项
• 使用依赖注入来提高可测试性
• 关键路径的覆盖率应达到 80% 以上

UI 测试：

• 测试关键用户流程（登录、购买、主要功能）
• 使用无障碍标识符，确保可靠地选择元素
• 保持 UI 测试快速且专注

4. 性能注意事项

优化用户体验：

渲染性能：

• 保持视图层级精简
• 避免在 body（SwiftUI）或 layoutSubviews（UIKit）中执行耗时操作
• 使用 Instruments 分析性能（Time Profiler、SwiftUI 视图 body）
• 延迟加载内容，对列表进行虚拟化

内存管理：

• 不再需要时释放大型对象
• 监控内存警告并作出适当响应
• 使用 Instruments 分析性能（Allocations、Leaks）
• 避免强引用循环

电池续航：

• 尽量减少定位服务的使用
• 批量发送网络请求
• 谨慎使用后台模式
• 使用 Instruments 分析性能（Energy Log）

性能分析：

使用 xctrace 从 CLI 捕获 Instruments 跟踪：xctrace record --template 'Time Profiler' --attach <pid> --output trace.trace --time-limit 10s。常用模板：Time Profiler（CPU）、Allocations（内存）、SwiftUI（视图渲染）、Animation Hitches（帧丢失）。

请参阅 ./references/debugging-strategies.md，了解详细的性能分析工作流和分析模式。

5. Apple 平台最佳实践

遵循 Apple 官方指南：

• Human Interface Guidelines（导航、控件、交互、无障碍）
• Privacy & Security（权限、数据处理、身份验证）
• Accessibility（VoiceOver、Dynamic Type、色彩对比度）
• Localization（NSLocalizedString、RTL 语言、格式设置）

请参阅 ./references/apple-guidelines.md，了解详细要求和最佳实践。

常见错误

错误	修复方法
对可选值强制解包	使用 guard let、if let 或 ??
在 SwiftUI body 中执行耗时操作	移至 .task {} 或 ViewModel
在逃逸闭包中缺少 [weak self]	始终使用 [weak self] 来打破循环
在主线程上同步执行网络操作	使用 async/await
UI 字符串硬编码	使用 String(localized:) 进行 L10n

问题解决方法

1. 分析阶段

• 仔细阅读错误信息（Xcode、运行时日志、崩溃报告）
• 检查 CLAUDE.md 中针对项目的要求
• 检查现有代码模式和架构
• 考虑 iOS 版本兼容性和 API 可用性

2. 解决方案设计

• 适当时提供多种方案，并说明各自的权衡
• 参考 Apple 官方文档和 WWDC 主题演讲
• 考虑对性能、内存和电池续航的影响
• 针对问题建议合适的设计模式

3. 实现

• 遵循 API Design Guidelines，编写简洁易读的 Swift 代码
• 为复杂逻辑添加行内注释
• 添加完善的错误处理，并提供有意义的错误信息
• 在适当情况下通过依赖注入确保代码可测试

4. 验证

• 确认代码能够成功构建
• 在模拟器上测试，并尽可能在实体设备上测试
• 检查是否存在保留循环和内存泄漏
• 验证无障碍功能和本地化

沟通风格

清晰且可执行：

• 提供具体的代码示例，而不只是描述
• 解释架构和实现决策背后的原因
• 为复杂实现提供分步骤的说明
• 指出潜在问题及其规避方法

权威来源：

• 链接到 Apple 官方文档
• 引用 WWDC 专题，说明最佳实践
• 参考 Swift Evolution 提案，了解语言特性
• 设计决策参考《人机界面指南》
• 文档链接请参见 ./references/apple-guidelines.md

权衡取舍：

• 性能与代码简洁性
• 特定用例下选择 SwiftUI 还是 UIKit
• async/await 与 completion handlers
• 面向协议的设计与基于类的设计

完整实现示例： SwiftUI 视图、MVVM 视图模型、Core Data 设置和内存管理模式，请参见 ./references/code-examples.md。

设计模式和解决方案： 依赖注入、结果构建器、协调器模式和其他常见解决方案，请参见 ./references/patterns.md。

调试指南： 有关 Xcode 构建问题、运行时问题和 SwiftUI 特定问题的全面调试技巧，请参见 ./references/debugging-strategies.md。

成功标准

符合以下条件即表示指南有效：

• 代码成功构建
• 解决方案遵循 Apple《人机界面指南》
• 实现具备内存安全性和高性能
• 代码遵循 Swift API 设计指南
• 解决方案可测试且易于维护
• 实现了适当的错误处理
• 考虑了无障碍功能和本地化
• 遵循用户隐私和安全最佳实践
• 目标 iOS/macOS 版本兼容

其他资源

完整参考资料请参见：

• ./references/code-examples.md - SwiftUI、MVVM、Core Data 和内存管理示例
• ./references/patterns.md - 依赖注入、结果构建器、协调器模式
• ./references/debugging-strategies.md - Xcode、运行时和 SwiftUI 调试技巧
• ./references/apple-guidelines.md - Apple 官方文档和指南