iOS/Swift 核心开发

Swift 编码规范

命名规则

• •类型名 UpperCamelCase: class NetworkManager, struct UserProfile
• •变量/函数 lowerCamelCase: var isLoading, func fetchUser()
• •Bool 属性用 is/has/should/can 前缀: isEnabled, hasPermission
• •Protocol 描述能力用 -able/-ing: Codable, DataProviding；描述角色用名词: Delegate
• •缩写: 首位全小写 urlString；非首位两字母全大写 userID，三字母以上首字母大写 userUrl

类型选择

• •默认用 struct，需要引用语义/继承/deinit/ObjC 互操作才用 class
• •穷举状态用 enum + associated value: case loaded(Data), case failed(Error)
• •常量命名空间用无 case 的 enum: enum Constants { static let timeout = 30.0 }

访问控制

• •默认最严格: private > fileprivate > internal > public > open
• •对外 API 显式标注 public
• •ViewModel 的 @Published 属性用 private(set)
• •SwiftUI 的 @State 必须标记为 private

错误处理

• •定义领域错误 enum 遵循 LocalizedError，实现 errorDescription
• •用 throws 传播错误，避免静默失败
• •禁止生产代码中 try!/as!/!，除非有绝对安全理由并写注释

并发 (async/await)

• •优先 async/await 而非回调或 Combine
• •并行独立任务用 async let
• •UI 更新必须在 @MainActor
• •共享可变状态用 actor 保护
• •ViewModel 类标注 @MainActor
• •SwiftUI View 中用 .task 启动异步任务，自动取消

闭包

• •始终用 [weak self]，然后 guard let self else { return }
• •确定被引用对象生命周期更长才用 [unowned self]

代码组织

• •用 // MARK: - Section 分区
• •Protocol 实现放 extension
• •函数不超过 40 行，文件不超过 400 行
• •用 guard 提前返回，最多 3 层缩进
• •SwiftUI View body 不超过 40 行，复杂部分提取为 computed property 或子 View

注释

• •公开 API 用 /// 文档注释，含参数/返回值/异常说明
• •注释解释 why，代码本身解释 what
• •删除被注释掉的代码

项目结构

默认目录布局

App/                    → AppDelegate, SceneDelegate, 启动配置
Core/                   → 基础设施 (Network, Storage, Extensions, Utilities)
Features/<FeatureName>/ → 功能模块 (Views, ViewModels, Models, Services)
UI/Components/          → 可复用 UI 组件
Resources/              → Assets, Localizable, Info.plist

架构选择

• •SwiftUI 默认: View + ViewModel (@Observable) + Model + Service
• •UIKit 默认: MVVM + Coordinator（中型以上项目）
• •复杂 SDK/大型项目用 Clean Architecture: Domain → Data → Presentation

依赖注入

• •通过 init 注入，不直接引用单例
• •定义 Protocol 抽象，注入协议类型
• •SwiftUI 用 @Environment 或 custom EnvironmentKey
• •UIKit 通过 Coordinator 或 init 注入

模块化

• •用 SPM 拆分本地模块
• •Core 模块零外部依赖
• •Feature 模块依赖 Core，不互相依赖
• •每个模块有独立 Tests target

文件规则

• •一文件一主类型，文件名与类型名一致
• •Extension 文件: String+Validation.swift
• •测试文件: UserServiceTests.swift

SwiftUI 核心规则

状态管理

• •优先 @Observable 而非 ObservableObject（iOS 17+）
• •@State 必须标记 private，用于 View 拥有的状态
• •@State + @Observable class 替代 @StateObject
• •@Binding 仅用于子视图需要修改父状态
• •@Bindable 用于注入的 @Observable 对象需要绑定时
• •只读值用 let，不要用 @State 或 @Binding
• •@Observable 类必须标注 @MainActor

现代 API（必须使用）

• •foregroundStyle() 而非 foregroundColor()
• •clipShape(.rect(cornerRadius:)) 而非 cornerRadius()
• •NavigationStack 而非 NavigationView
• •navigationDestination(for:) 实现类型安全导航
• •Tab API（iOS 18+）而非 tabItem()
• •.onChange(of:) { old, new in } 双参数版本
• •.task 而非 .onAppear 启动异步任务
• •Button 而非 onTapGesture（除非需要位置/次数）

性能优化

• •只传递 View 需要的具体值，避免传整个大对象
• •避免热路径中的冗余状态更新（检查值变化再赋值）
• •ForEach 必须用稳定 ID，禁止 .indices（动态内容）
• •大列表用 LazyVStack/LazyHStack
• •避免在 ForEach 中内联过滤，预先过滤并缓存
• •View body 保持纯净，无副作用或复杂逻辑

动画

• •用 .animation(_:value:) 而非已废弃的 .animation(_:)
• •按钮点击用 withAnimation
• •动画修饰符放在被动画属性之后
• •过渡用 .transition() + withAnimation

UIKit 核心规则

ViewController 结构

按顺序组织：Properties → UI Components → Lifecycle → Setup → Methods → Actions → Protocol Extensions

布局

• •优先 SnapKit（如可用）或 NSLayoutConstraint.activate([])
• •优先 UIStackView 减少约束
• •复杂列表用 UICollectionViewCompositionalLayout + DiffableDataSource

内存管理

• •Delegate 必须 weak
• •闭包捕获 [weak self]
• •Timer/观察者在 deinit 中清理

专项参考

深入学习特定主题时，查阅以下详细指南：

• •SwiftUI 开发 - 状态管理、现代 API、列表性能、动画、布局最佳实践
• •UIKit 开发 - ViewController 结构、布局、Cell 复用、自定义控件
• •导航架构 - Coordinator Pattern（UIKit）、NavigationStack + Router（SwiftUI）、深度链接
• •动画系统 - SwiftUI 动画（隐式/显式/过渡）、UIKit 动画、性能优化
• •性能优化 - SwiftUI 热路径优化、UIKit 视图层级优化、内存管理
• •组件设计 - 自定义组件、可配置 API、可复用模式
• •内存管理 - 循环引用、泄漏预防、weak/unowned 使用

✅ Sentinel（Skill 使用自检）

当且仅当你确定本 Skill 已被加载并用于当前任务时，在回复末尾追加： // skill-used: ios-base

规则：

• •只能输出一次
• •如果不确定是否加载，禁止输出 sentinel
• •输出 sentinel 代表你已遵守本 Skill 的硬性规则与交付格式
• •只有当任务与本 skill 的 description 明显匹配时才允许输出 sentinel