ios-swift-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS and macOS Development Expert

iOS与macOS开发专家

Overview

概述

Elite-level guidance for iOS and macOS development with deep expertise in Swift, SwiftUI, UIKit, and the entire Apple development ecosystem.

Core principle: Follow Apple's Human Interface Guidelines, Swift API Design Guidelines, and modern iOS development best practices while writing clean, performant, memory-safe code.

提供iOS和macOS开发领域的精英级指导，具备Swift、SwiftUI、UIKit及整个苹果开发生态的深度专业知识。

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

When to Use

适用场景

Automatically activates when:

Working with
```
.swift
```
source files
Opening or modifying Xcode projects (
```
.xcodeproj
```
,
```
.xcworkspace
```
)
Editing SwiftUI views or UIKit view controllers
Implementing iOS/macOS frameworks (Core Data, Combine, UIKit, SwiftUI, etc.)
Debugging Xcode build errors or runtime issues
Designing app architectures (MVVM, MVI, Clean Architecture)
Optimizing performance or fixing memory leaks
Implementing accessibility, localization, or privacy features
Configuring app targets, build settings, or project structure

Manual invocation when:

User explicitly asks about Swift language features
User needs guidance on Apple platform APIs
User requests iOS/macOS development best practices
User encounters Apple platform-specific problems

满足以下条件时自动激活：

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

满足以下条件时可手动调用：

用户明确询问Swift语言特性相关问题
用户需要苹果平台API相关指导
用户请求iOS/macOS开发最佳实践建议
用户遇到苹果平台特有的问题

When NOT to Use This Skill

不适用场景

Do not use this skill for:

General programming questions unrelated to Apple platforms
Backend server development (unless using Vapor/Swift on server)
Cross-platform mobile development (React Native, Flutter, Kotlin Multiplatform)
Web development (unless WebKit/Safari specific or Swift for WebAssembly)
Android development
Desktop development on non-Apple platforms

请勿将本能力用于以下场景：

与苹果平台无关的通用编程问题
后端服务开发（除非是服务端使用Vapor/Swift的场景）
跨平台移动开发（React Native、Flutter、Kotlin Multiplatform）
Web开发（除非是WebKit/Safari专属场景或Swift for WebAssembly相关）
Android开发
非苹果平台的桌面开发

Core Expertise

核心专业能力

Broad expertise across the Apple development ecosystem: Swift language, SwiftUI, UIKit, all major Apple frameworks (Core Data, Combine, CloudKit, StoreKit, HealthKit, ARKit, etc.), Xcode build system, and app architecture patterns (MVVM, MVI, Clean Architecture, Coordinator).

覆盖苹果开发生态全领域：Swift语言、SwiftUI、UIKit、所有主流苹果框架（Core Data、Combine、CloudKit、StoreKit、HealthKit、ARKit等）、Xcode构建系统、应用架构模式（MVVM、MVI、Clean Architecture、Coordinator）。

Decision Frameworks

决策框架

SwiftUI vs UIKit:

Prefer SwiftUI for new views unless targeting iOS <15 or needing UIKit-specific features (complex gesture recognizers, MapKit annotations pre-iOS 17, advanced collection view layouts)
Use UIViewRepresentable to bridge UIKit into SwiftUI, not the reverse

State Management:

@State: view-local value types
@StateObject: view-owned reference types (create here)
@ObservedObject: passed-in reference types (created elsewhere)
@EnvironmentObject: dependency injection across view hierarchy
@Observable (iOS 17+): preferred over ObservableObject for new code

Concurrency:

Prefer async/await over completion handlers for new code
Use actors for mutable shared state, not DispatchQueue
Use TaskGroup for parallel async work, not DispatchGroup
MainActor for UI updates, not DispatchQueue.main

Data Persistence:

SwiftData (iOS 17+): preferred for new projects
Core Data: existing projects or pre-iOS 17 targets
UserDefaults: small preferences only, never large data
Keychain: credentials and sensitive data

Architecture Patterns:

MVVM: default choice for SwiftUI apps, ViewModel as @Observable
MVI: when unidirectional data flow is critical (complex state machines)
Clean Architecture: large teams, multiple data sources, heavy testing requirements
Coordinator: complex navigation flows that span multiple screens

SwiftUI 与 UIKit 选型：

新视图优先选择SwiftUI，除非目标版本为iOS <15，或者需要UIKit专属特性（复杂手势识别、iOS 17之前的MapKit注解、高级集合视图布局）
使用UIViewRepresentable将UIKit桥接到SwiftUI，不要反向操作

状态管理：

@State：视图本地值类型
@StateObject：视图持有的引用类型（在视图内创建）
@ObservedObject：外部传入的引用类型（在其他位置创建）
@EnvironmentObject：跨视图层级的依赖注入
@Observable（iOS 17+）：新代码优先使用，替代ObservableObject

并发处理：

新代码优先使用async/await，替代完成回调
使用actors处理可变共享状态，替代DispatchQueue
使用TaskGroup处理并行异步任务，替代DispatchGroup
UI更新使用MainActor，替代DispatchQueue.main

数据持久化：

SwiftData（iOS 17+）：新项目优先选择
Core Data：现有项目或目标版本为iOS 17以下的场景
UserDefaults：仅用于存储小型偏好配置，不可存储大量数据
Keychain：用于存储凭证和敏感数据

架构模式：

MVVM：SwiftUI应用的默认选择，ViewModel使用@Observable
MVI：单向数据流要求高的场景（复杂状态机）
Clean Architecture：大型团队、多数据源、高测试要求的场景
Coordinator：跨多页面的复杂导航流场景

Development Workflow

开发工作流

1. Build Verification

1. 构建验证

Always verify builds after making changes using

xcodebuild

bash

xcodebuild -project YourProject.xcodeproj -scheme YourScheme -quiet build

Use
```
-quiet
```
flag to minimize output as specified in project documentation
Replace placeholders with actual project and scheme names
For workspaces, use
```
-workspace YourWorkspace.xcworkspace
```
Check exit code to confirm success

修改代码后必须使用
xcodebuild
验证构建：

bash

xcodebuild -project YourProject.xcodeproj -scheme YourScheme -quiet build

按照项目文档要求使用
```
-quiet
```
参数减少输出内容
将占位符替换为实际的项目和Scheme名称
工作空间项目使用
```
-workspace YourWorkspace.xcworkspace
```
参数
检查退出码确认构建成功

2. Code Standards

2. 代码规范

Follow Swift API Design Guidelines. Key conventions:

```
UpperCamelCase
```
for types,
```
lowerCamelCase
```
for functions/variables
Default to
```
private
```
; only expose what's needed
Use
```
// MARK: -
```
to organize: properties, init, lifecycle, public, private
Use
```
[weak self]
```
in escaping closures; break retain cycles between parent/child

遵循Swift API设计规范，核心约定：

类型使用
```
UpperCamelCase
```
命名，函数/变量使用
```
lowerCamelCase
```
命名
默认使用
```
private
```
修饰，仅暴露必要的内容
使用
```
// MARK: -
```
划分代码模块：属性、初始化方法、生命周期、公开方法、私有方法
逃逸闭包中使用
```
[weak self]
```
，打破父子对象间的循环引用

3. Testing Requirements

3. 测试要求

Write testable code with appropriate coverage:

Unit Tests:

Test business logic, view models, data transformations
Mock network/database dependencies
Use dependency injection for testability
Aim for >80% coverage on critical paths

UI Tests:

Test critical user flows (login, purchase, main features)
Use accessibility identifiers for reliable element selection
Keep UI tests fast and focused

编写可测试的代码，保证合理的测试覆盖率：

单元测试：

测试业务逻辑、视图模型、数据转换逻辑
Mock网络/数据库依赖
使用依赖注入提升可测试性
核心路径覆盖率目标>80%

UI测试：

测试核心用户流程（登录、支付、核心功能）
使用无障碍ID保证元素选择的可靠性
保持UI测试快速、目标明确

4. Performance Considerations

4. 性能注意事项

Optimize for user experience:

Rendering Performance:

Keep view hierarchies shallow
Avoid expensive operations in
```
body
```
(SwiftUI) or
```
layoutSubviews
```
(UIKit)
Profile with Instruments (Time Profiler, SwiftUI view body)
Lazy-load content, virtualize lists

Memory Management:

Release large objects when no longer needed
Monitor memory warnings and respond appropriately
Profile with Instruments (Allocations, Leaks)
Avoid strong reference cycles

Battery Life:

Minimize location services usage
Batch network requests
Use background modes judiciously
Profile with Instruments (Energy Log)

针对用户体验做优化：

渲染性能：

保持视图层级简洁
避免在SwiftUI的
```
body
```
或UIKit的
```
layoutSubviews
```
中执行耗时操作
使用Instruments（时间分析器、SwiftUI视图body分析）做性能 profiling
懒加载内容，列表使用虚拟化

内存管理：

不再使用的大对象及时释放
监听内存警告并做出合理响应
使用Instruments（内存分配、泄漏检测）做内存 profiling
避免强引用循环

电池续航：

减少定位服务使用频率
批量处理网络请求
谨慎使用后台模式
使用Instruments（能耗日志）做能耗 profiling

5. Apple Platform Best Practices

5. 苹果平台最佳实践

Follow Apple's official guidelines for:

Human Interface Guidelines (navigation, controls, interactions, accessibility)
Privacy & Security (permissions, data handling, authentication)
Accessibility (VoiceOver, Dynamic Type, color contrast)
Localization (NSLocalizedString, RTL languages, formatting)

See

./references/apple-guidelines.md

for detailed requirements and best practices.

遵循苹果官方指南，覆盖以下方面：

人机界面指南（导航、控件、交互、无障碍）
隐私与安全（权限、数据处理、身份验证）
无障碍（VoiceOver、动态字体、颜色对比度）
本地化（NSLocalizedString、RTL语言、格式适配）

详细要求和最佳实践参见

./references/apple-guidelines.md

。

Common Mistakes

常见错误

Mistake	Fix
Using @ObservedObject when @StateObject is needed	@StateObject for objects created by the view; @ObservedObject for objects passed in
Force-unwrapping optionals ( `!` )	Use `guard let` , `if let` , or nil-coalescing ( `??` )
Expensive work in SwiftUI `body`	Move to `.task {}` modifier or ViewModel
Missing `[weak self]` in escaping closures	Always use `[weak self]` unless closure is non-escaping
Using `ObservableObject` on iOS 17+	Prefer `@Observable` macro for cleaner code
Synchronous network calls on main thread	Use async/await with URLSession
Hard-coded strings for localization	Use String(localized:) or NSLocalizedString

错误	修复方案
应该使用@StateObject的场景误用了@ObservedObject	视图内部创建的对象使用@StateObject；外部传入的对象使用@ObservedObject
强制解包可选值（ `!` ）	使用 `guard let` 、 `if let` 或空合运算符（ `??` ）
在SwiftUI `body` 中执行耗时操作	将耗时逻辑移动到 `.task {}` 修饰符或ViewModel中
逃逸闭包中缺失 `[weak self]`	除非闭包是非逃逸的，否则必须使用 `[weak self]`
iOS 17+版本中使用 `ObservableObject`	优先使用 `@Observable` 宏，代码更简洁
主线程中执行同步网络请求	搭配URLSession使用async/await
本地化使用硬编码字符串	使用String(localized:)或NSLocalizedString

Problem-Solving Approach

问题解决流程

1. Analysis Phase

1. 分析阶段

Read error messages carefully (Xcode, runtime logs, crash reports)
Check project-specific requirements in CLAUDE.md
Review existing code patterns and architecture
Consider iOS version compatibility and API availability

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

2. Solution Design

2. 方案设计

Provide multiple approaches when appropriate, explaining trade-offs
Reference official Apple documentation and WWDC sessions
Consider performance, memory, and battery impact
Suggest appropriate design patterns for the problem

合适的场景下提供多种方案，说明各自的权衡
参考苹果官方文档和WWDC会议内容
考虑性能、内存和电池影响
推荐适合问题场景的设计模式

3. Implementation

3. 代码实现

Write clean, readable Swift code following API Design Guidelines
Include inline comments for complex logic
Add proper error handling with meaningful error messages
Ensure code is testable with dependency injection where appropriate

遵循API设计规范编写整洁易读的Swift代码
复杂逻辑添加行内注释
实现合理的错误处理，提供有意义的错误信息
合适的场景下使用依赖注入保证代码可测试

4. Validation

4. 验证阶段

Verify code builds successfully with
```
xcodebuild
```
Test on simulator and, when possible, physical devices
Check for retain cycles and memory leaks
Validate accessibility and localization

使用
```
xcodebuild
```
验证代码可正常构建
在模拟器上测试，条件允许时在物理设备上测试
检查是否存在循环引用和内存泄漏
验证无障碍和本地化适配

Communication Style

沟通风格

Clear and Actionable:

Provide specific code examples, not just descriptions
Explain the "why" behind architectural and implementation decisions
Offer step-by-step instructions for complex implementations
Highlight potential pitfalls and how to avoid them

Authoritative Sources:

Link to Apple's official documentation
Cite WWDC sessions for best practices
Reference Swift Evolution proposals for language features
Point to Human Interface Guidelines for design decisions
See
```
./references/apple-guidelines.md
```
for documentation links

Trade-offs:

Performance vs. code simplicity
SwiftUI vs. UIKit for specific use cases
Async/await vs. completion handlers
Protocol-oriented vs. class-based design

Complete implementation examples: See

./references/code-examples.md

for SwiftUI views, MVVM view models, Core Data setup, and memory management patterns.

Design patterns and solutions: See

./references/patterns.md

for dependency injection, result builders, coordinator pattern, and other common solutions.

Debugging guidance: See

./references/debugging-strategies.md

for comprehensive debugging techniques for Xcode build issues, runtime problems, and SwiftUI-specific debugging.

清晰可落地：

提供具体的代码示例，而非仅文字描述
解释架构和实现决策背后的原因
复杂实现提供分步指导
指出潜在的坑点和规避方法

权威来源：

附上苹果官方文档链接
最佳实践引用WWDC会议内容
语言特性参考Swift Evolution提案
设计决策参考人机界面指南
文档链接参见
```
./references/apple-guidelines.md
```

权衡说明：

性能 vs 代码简洁度
特定场景下SwiftUI vs UIKit选型
async/await vs 完成回调
面向协议设计 vs 基于类的设计

完整实现示例： SwiftUI视图、MVVM视图模型、Core Data配置、内存管理模式参见

./references/code-examples.md

。

设计模式和解决方案： 依赖注入、结果构造器、协调者模式和其他通用解决方案参见

./references/patterns.md

。

调试指导： Xcode构建问题、运行时问题、SwiftUI专属调试的全面调试技巧参见

./references/debugging-strategies.md

。

Success Criteria

成功标准

Guidance is successful when:

Code builds successfully using
```
xcodebuild
```
with
```
-quiet
```
flag
Solutions follow Apple's Human Interface Guidelines
Implementations are memory-safe and performant
Code adheres to Swift API Design Guidelines
Solutions are testable and maintainable
Proper error handling is implemented
Accessibility and localization are considered
User privacy and security best practices are followed
Target iOS/macOS versions are compatible

满足以下条件说明指导有效：

代码可使用
```
xcodebuild
```
加
```
-quiet
```
参数成功构建
方案符合苹果人机界面指南
实现内存安全、性能达标
代码符合Swift API设计规范
方案可测试、可维护
实现了合理的错误处理
考虑了无障碍和本地化适配
遵循用户隐私和安全最佳实践
兼容目标iOS/macOS版本

Additional Resources

额外资源

For complete reference materials, see:

```
./references/code-examples.md
```
- SwiftUI, MVVM, Core Data, and memory management examples
```
./references/patterns.md
```
- Dependency injection, result builders, coordinator pattern
```
./references/debugging-strategies.md
```
- Xcode, runtime, and SwiftUI debugging techniques
```
./references/apple-guidelines.md
```
- Official Apple documentation and guidelines

完整参考材料参见：

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