Back to Details

solid-swift

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SOLID Swift - Apple Best Practices 2026

SOLID Swift - Apple 2026最佳实践

Agent Workflow (MANDATORY)

Agent工作流（强制要求）

Before ANY implementation, use 
TeamCreate
to spawn 3 agents:
  1. fuse-ai-pilot:explore-codebase - Analyze existing architecture
  2. fuse-ai-pilot:research-expert - Verify Swift/Apple docs via Apple Docs MCP + Context7
  3. XcodeBuildMCP - Build validation after code changes. Then run fuse-ai-pilot:sniper.
在进行任何实现之前，使用
TeamCreate
生成3个Agent：
  1. fuse-ai-pilot:explore-codebase - 分析现有架构
  2. fuse-ai-pilot:research-expert - 通过Apple Docs MCP + Context7验证Swift/Apple文档
  3. XcodeBuildMCP - 代码变更后进行构建验证。然后运行fuse-ai-pilot:sniper。

DRY - Reuse Before Creating (MANDATORY)

DRY原则 - 优先复用而非创建（强制要求）

Before writing ANY new code:
  1. Grep the codebase for similar protocols, services, or logic
  2. Check shared locations: 
    Core/Extensions/
    , 
    Core/Utilities/
    , 
    Core/Protocols/
  3. If similar code exists -> extend/reuse instead of duplicate
  4. If code will be used by 2+ features -> create it in 
    Core/
    directly
在编写任何新代码之前：
  1. 在代码库中搜索类似的协议、服务或逻辑
  2. 检查共享目录：
    Core/Extensions/
    、
    Core/Utilities/
    、
    Core/Protocols/
  3. 如果存在类似代码 -> 扩展/复用而非重复编写
  4. 如果代码将被2个及以上功能使用 -> 直接在
    Core/
    中创建

Architecture (Features Modular MANDATORY)

架构设计（功能模块化是强制要求）

LayerLocationMax Lines
Views
Features/[Feature]/Views/
80
ViewModels
Features/[Feature]/ViewModels/
100
Services
Features/[Feature]/Services/
100
Protocols
Features/[Feature]/Protocols/
30
Shared
Core/{Models,Protocols,Services,Extensions,Utilities}/
-
NEVER use flat 
Sources/
structure - always 
Features/[Feature]/
层级位置最大行数
视图
Features/[Feature]/Views/
80
视图模型
Features/[Feature]/ViewModels/
100
服务
Features/[Feature]/Services/
100
协议
Features/[Feature]/Protocols/
30
共享代码
Core/{Models,Protocols,Services,Extensions,Utilities}/
-
禁止使用扁平的
Sources/
结构 - 必须使用
Features/[Feature]/
结构

Critical Rules (MANDATORY)

关键规则（强制要求）

RuleValue
File limit150 lines (split at 120)
ViewModels
@MainActor @Observable
Protocols
Features/[Feature]/Protocols/
or 
Core/Protocols/
ONLY
Models
Sendable
structs
Documentation
///
on all public APIs
PreviewsEvery View MUST have 
#Preview
规则要求
文件行数限制150行（120行时就需要拆分）
视图模型使用
@MainActor @Observable
协议只能放在
Features/[Feature]/Protocols/
或
Core/Protocols/
目录下
模型采用
Sendable
结构体
文档所有公开API都需要添加
///
注释
预览每个视图必须包含
#Preview

Reference Guide

参考指南

Concepts

核心概念

TopicReferenceWhen to consult
SOLID Overviewsolid-principles.mdQuick reference all principles
SRPsingle-responsibility.mdFat views/VMs, splitting files
OCPopen-closed.mdAdding providers, extensibility
LSPliskov-substitution.mdProtocol contracts, testing
ISPinterface-segregation.mdFat protocols, splitting
DIPdependency-inversion.mdInjection, testing, mocking
Concurrencyconcurrency-patterns.mdActors, @MainActor, Sendable
Anti-Patternsanti-patterns.mdCode smells detection
主题参考文档适用场景
SOLID总览solid-principles.md快速查阅所有原则
单一职责原则（SRP）single-responsibility.md视图/视图模型过于臃肿、拆分文件时
开闭原则（OCP）open-closed.md添加服务提供者、实现扩展性时
里氏替换原则（LSP）liskov-substitution.md协议契约、测试时
接口隔离原则（ISP）interface-segregation.md协议过于臃肿、拆分协议时
依赖倒置原则（DIP）dependency-inversion.md依赖注入、测试、模拟对象时
并发处理concurrency-patterns.md使用Actors、@MainActor、Sendable时
反模式anti-patterns.md检测代码异味时

Templates

模板

TemplateWhen to use
view.mdSwiftUI View with subviews and #Preview
viewmodel.md@Observable ViewModel with @MainActor
service.mdAPI Service, Mock, Cache actor
protocol.mdService protocol, CQRS, Auth
model.mdModel, DTO, Error, Enum
模板适用场景
view.md包含子视图和#Preview的SwiftUI视图
viewmodel.md带有@MainActor的@Observable视图模型
service.mdAPI服务、模拟对象、缓存Actor
protocol.md服务协议、CQRS、认证相关
model.md模型、DTO、错误类型、枚举

Forbidden

禁止事项

Anti-PatternFix
Files > 150 linesSplit at 120
Protocols in impl filesMove to 
Protocols/
directory
ObservableObject
Use 
@Observable
Completion handlersUse 
async/await
Missing 
#Preview
Add preview for every View
Non-Sendable in asyncUse 
struct
with 
let
Flat 
Sources/
structure		Use 
Features/[Feature]/
反模式修复方案
文件行数>150行在120行时拆分文件
协议放在实现文件中移动到
Protocols/
目录
使用
ObservableObject
改用
@Observable
使用完成回调改用
async/await
缺少
#Preview
为每个视图添加预览
异步代码中使用非Sendable类型使用带
let
的
struct
扁平的
Sources/
结构		改用
Features/[Feature]/
结构