Back to Details

swift-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Swift Architecture

Swift架构

Select and implement the right architecture pattern for Apple platform apps built with Swift 6.3 and SwiftUI or UIKit.
为使用Swift 6.3、SwiftUI或UIKit构建的Apple平台应用选择并实现合适的架构模式。

Contents

目录

Architecture Selection

架构选择

Choose based on feature complexity, team size, and testing requirements.
PatternBest ForComplexityTestability
MVSmall-to-medium SwiftUI apps, rapid iterationLowModerate
MVVMMedium apps, teams familiar with reactive patternsMediumHigh
MVIComplex state machines, predictable state flowMedium-HighHigh
TCALarge apps needing composable features, strong testingHighVery High
Clean ArchitectureEnterprise apps, strict separation of concernsHighVery High
CoordinatorApps with complex navigation flows (UIKit or hybrid)MediumHigh
Default recommendation for new SwiftUI apps: Start with MV (Model-View with 
@Observable
). Escalate to MVVM or TCA only when the feature's complexity demands it.
根据功能复杂度、团队规模和测试需求进行选择。
模式适用场景复杂度可测试性
MV中小型SwiftUI应用、快速迭代低中等
MVVM中型应用、熟悉响应式模式的团队中等高
MVI复杂状态机、可预测的状态流中高高
TCA需要可组合功能的大型应用、强测试需求高极高
Clean Architecture企业级应用、严格关注点分离高极高
Coordinator包含复杂导航流程的应用（UIKit或混合架构）中等高
**新SwiftUI应用默认推荐：**从MV（搭配
@Observable
的Model-View）开始。仅当功能复杂度要求时，再升级到MVVM或TCA。

Decision Framework

决策框架

  1. Is the feature a simple CRUD screen? → MV pattern
  2. Does the screen have complex business logic separate from the view? → MVVM
  3. Do you need deterministic state transitions and side-effect management? → MVI or TCA
  4. Is the app large with many independent feature modules? → TCA or Clean Architecture
  5. Is navigation complex with deep linking and conditional flows? → Add Coordinator pattern
  1. 该功能是简单的CRUD界面吗？ → MV模式
  2. 界面是否包含与视图分离的复杂业务逻辑？ → MVVM
  3. 是否需要确定性状态转换和副作用管理？ → MVI或TCA
  4. 应用是否为大型应用，包含多个独立功能模块？ → TCA或Clean Architecture
  5. 导航是否包含复杂的深度链接和条件流程？ → 添加Coordinator模式

MV Pattern

MV模式

The simplest SwiftUI architecture. The view observes 
@Observable
models directly. No intermediate view model layer.
Docs: @Observable
swift
import Observation
import SwiftUI

@Observable
class TripStore {
    var trips: [Trip] = []
    var isLoading = false
    var error: Error?

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        do {
            trips = try await service.fetchTrips()
        } catch {
            self.error = error
        }
    }

    func deleteTrip(_ trip: Trip) async throws {
        try await service.delete(trip)
        trips.removeAll { $0.id == trip.id }
    }
}

struct TripsView: View {
    @State private var store = TripStore(service: .live)

    var body: some View {
        List(store.trips) { trip in
            TripRow(trip: trip)
        }
        .task { await store.loadTrips() }
    }
}
When MV is enough: Single-screen features, prototype/MVP, small teams, straightforward data flow.
When to upgrade: Business logic grows complex, unit testing the view's behavior becomes difficult, multiple views need to share and transform the same state differently.
最简单的SwiftUI架构。视图直接观察
@Observable
模型，无需中间的视图模型层。
文档：@Observable
swift
import Observation
import SwiftUI

@Observable
class TripStore {
    var trips: [Trip] = []
    var isLoading = false
    var error: Error?

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        do {
            trips = try await service.fetchTrips()
        } catch {
            self.error = error
        }
    }

    func deleteTrip(_ trip: Trip) async throws {
        try await service.delete(trip)
        trips.removeAll { $0.id == trip.id }
    }
}

struct TripsView: View {
    @State private var store = TripStore(service: .live)

    var body: some View {
        List(store.trips) { trip in
            TripRow(trip: trip)
        }
        .task { await store.loadTrips() }
    }
}
**MV模式足够的场景：**单屏功能、原型/MVP、小型团队、简单数据流。
**何时升级：**业务逻辑变得复杂、难以对视图行为进行单元测试、多个视图需要以不同方式共享和转换同一状态。

MVVM

MVVM

Separates view logic into a 
ViewModel
that the view observes. The view model transforms model data for display and handles user actions.
swift
@Observable
class TripListViewModel {
    private(set) var trips: [TripRowItem] = []
    private(set) var isLoading = false
    var searchText = ""

    var filteredTrips: [TripRowItem] {
        guard !searchText.isEmpty else { return trips }
        return trips.filter { $0.name.localizedStandardContains(searchText) }
    }

    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        let models = (try? await repository.fetchAll()) ?? []
        trips = models.map { TripRowItem(from: $0) }
    }

    func delete(at offsets: IndexSet) async {
        let toDelete = offsets.map { filteredTrips[$0] }
        for item in toDelete {
            try? await repository.delete(id: item.id)
        }
        await loadTrips()
    }
}

struct TripRowItem: Identifiable {
    let id: UUID
    let name: String
    let dateRange: String

    init(from trip: Trip) {
        self.id = trip.id
        self.name = trip.name
        self.dateRange = trip.startDate.formatted(.dateTime.month().day())
            + " – " + trip.endDate.formatted(.dateTime.month().day())
    }
}

struct TripListView: View {
    @State private var viewModel: TripListViewModel

    init(repository: TripRepository) {
        _viewModel = State(initialValue: TripListViewModel(repository: repository))
    }

    var body: some View {
        List {
            ForEach(viewModel.filteredTrips) { item in
                Text(item.name)
            }
            .onDelete { offsets in
                Task { await viewModel.delete(at: offsets) }
            }
        }
        .searchable(text: $viewModel.searchText)
        .task { await viewModel.loadTrips() }
    }
}
Testing a ViewModel:
swift
@Test func filteredTripsMatchesSearch() async {
    let repo = MockTripRepository(trips: [
        Trip(name: "Paris"), Trip(name: "Tokyo"), Trip(name: "Paris TX")
    ])
    let vm = TripListViewModel(repository: repo)
    await vm.loadTrips()
    vm.searchText = "Paris"
    #expect(vm.filteredTrips.count == 2)
}
将视图逻辑分离到视图模型（
ViewModel
）中，视图观察该模型。视图模型将模型数据转换为适合展示的格式，并处理用户操作。
swift
@Observable
class TripListViewModel {
    private(set) var trips: [TripRowItem] = []
    private(set) var isLoading = false
    var searchText = ""

    var filteredTrips: [TripRowItem] {
        guard !searchText.isEmpty else { return trips }
        return trips.filter { $0.name.localizedStandardContains(searchText) }
    }

    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        let models = (try? await repository.fetchAll()) ?? []
        trips = models.map { TripRowItem(from: $0) }
    }

    func delete(at offsets: IndexSet) async {
        let toDelete = offsets.map { filteredTrips[$0] }
        for item in toDelete {
            try? await repository.delete(id: item.id)
        }
        await loadTrips()
    }
}

struct TripRowItem: Identifiable {
    let id: UUID
    let name: String
    let dateRange: String

    init(from trip: Trip) {
        self.id = trip.id
        self.name = trip.name
        self.dateRange = trip.startDate.formatted(.dateTime.month().day())
            + " – " + trip.endDate.formatted(.dateTime.month().day())
    }
}

struct TripListView: View {
    @State private var viewModel: TripListViewModel

    init(repository: TripRepository) {
        _viewModel = State(initialValue: TripListViewModel(repository: repository))
    }

    var body: some View {
        List {
            ForEach(viewModel.filteredTrips) { item in
                Text(item.name)
            }
            .onDelete { offsets in
                Task { await viewModel.delete(at: offsets) }
            }
        }
        .searchable(text: $viewModel.searchText)
        .task { await viewModel.loadTrips() }
    }
}
测试ViewModel：
swift
@Test func filteredTripsMatchesSearch() async {
    let repo = MockTripRepository(trips: [
        Trip(name: "Paris"), Trip(name: "Tokyo"), Trip(name: "Paris TX")
    ])
    let vm = TripListViewModel(repository: repo)
    await vm.loadTrips()
    vm.searchText = "Paris"
    #expect(vm.filteredTrips.count == 2)
}

MVI

MVI

Unidirectional data flow: views dispatch intents, a reducer produces new state, and side effects are handled explicitly.
swift
@Observable
class TripListStore {
    private(set) var state = State()

    struct State {
        var trips: [Trip] = []
        var isLoading = false
        var error: String?
    }

    enum Intent {
        case loadTrips
        case deleteTrip(Trip)
        case clearError
    }

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func send(_ intent: Intent) {
        Task { await handle(intent) }
    }

    @MainActor
    private func handle(_ intent: Intent) async {
        switch intent {
        case .loadTrips:
            state.isLoading = true
            do {
                state.trips = try await service.fetchTrips()
            } catch {
                state.error = error.localizedDescription
            }
            state.isLoading = false

        case .deleteTrip(let trip):
            try? await service.delete(trip)
            state.trips.removeAll { $0.id == trip.id }

        case .clearError:
            state.error = nil
        }
    }
}
Advantages: Predictable state transitions, easy to log/replay intents, clear separation of "what happened" from "what changed."
单向数据流：视图分发意图（intents），归约器（reducer）生成新的状态（state），**副作用（side effects）**被显式处理。
swift
@Observable
class TripListStore {
    private(set) var state = State()

    struct State {
        var trips: [Trip] = []
        var isLoading = false
        var error: String?
    }

    enum Intent {
        case loadTrips
        case deleteTrip(Trip)
        case clearError
    }

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func send(_ intent: Intent) {
        Task { await handle(intent) }
    }

    @MainActor
    private func handle(_ intent: Intent) async {
        switch intent {
        case .loadTrips:
            state.isLoading = true
            do {
                state.trips = try await service.fetchTrips()
            } catch {
                state.error = error.localizedDescription
            }
            state.isLoading = false

        case .deleteTrip(let trip):
            try? await service.delete(trip)
            state.trips.removeAll { $0.id == trip.id }

        case .clearError:
            state.error = nil
        }
    }
}
**优势：**可预测的状态转换、易于记录/重放意图、清晰分离“发生了什么”与“什么被改变”。

TCA

TCA

The Composable Architecture (Point-Free) provides composable reducers, dependency injection, exhaustive testing, and structured side effects.
Docs: TCA
swift
import ComposableArchitecture

@Reducer
struct TripList {
    @ObservableState
    struct State: Equatable {
        var trips: IdentifiedArrayOf<Trip> = []
        var isLoading = false
    }

    enum Action {
        case onAppear
        case tripsLoaded([Trip])
        case deleteTrip(Trip.ID)
    }

    @Dependency(\.tripClient) var tripClient

    var body: some ReducerOf<Self> {
        Reduce { state, action in
            switch action {
            case .onAppear:
                state.isLoading = true
                return .run { send in
                    let trips = try await tripClient.fetchAll()
                    await send(.tripsLoaded(trips))
                }
            case .tripsLoaded(let trips):
                state.trips = IdentifiedArray(uniqueElements: trips)
                state.isLoading = false
                return .none
            case .deleteTrip(let id):
                state.trips.remove(id: id)
                return .run { _ in try await tripClient.delete(id) }
            }
        }
    }
}
Use TCA when: Large team needs consistent patterns, exhaustive test coverage is a priority, features compose from smaller features, you need structured dependency injection across the app.
The Composable Architecture（Point-Free）提供可组合的归约器、依赖注入、全面的测试支持以及结构化的副作用处理。
文档：TCA
swift
import ComposableArchitecture

@Reducer
struct TripList {
    @ObservableState
    struct State: Equatable {
        var trips: IdentifiedArrayOf<Trip> = []
        var isLoading = false
    }

    enum Action {
        case onAppear
        case tripsLoaded([Trip])
        case deleteTrip(Trip.ID)
    }

    @Dependency(\.tripClient) var tripClient

    var body: some ReducerOf<Self> {
        Reduce { state, action in
            switch action {
            case .onAppear:
                state.isLoading = true
                return .run { send in
                    let trips = try await tripClient.fetchAll()
                    await send(.tripsLoaded(trips))
                }
            case .tripsLoaded(let trips):
                state.trips = IdentifiedArray(uniqueElements: trips)
                state.isLoading = false
                return .none
            case .deleteTrip(let id):
                state.trips.remove(id: id)
                return .run { _ in try await tripClient.delete(id) }
            }
        }
    }
}
**何时使用TCA：**大型团队需要统一模式、优先考虑全面测试覆盖、功能由更小的功能组合而成、需要在整个应用中进行结构化依赖注入。

Clean Architecture

Clean Architecture

Layers: Domain (entities, use cases, repository protocols) → Data (repository implementations, network, persistence) → Presentation (views, view models). Dependencies point inward.
swift
// Domain layer
protocol TripRepository: Sendable {
    func fetchAll() async throws -> [Trip]
    func save(_ trip: Trip) async throws
    func delete(id: UUID) async throws
}

struct FetchUpcomingTripsUseCase: Sendable {
    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func execute() async throws -> [Trip] {
        try await repository.fetchAll()
            .filter { $0.startDate > .now }
            .sorted { $0.startDate < $1.startDate }
    }
}

// Data layer
struct RemoteTripRepository: TripRepository {
    private let client: APIClient

    func fetchAll() async throws -> [Trip] {
        try await client.request(.get, "/trips")
    }
    // ...
}

// Presentation layer
@Observable
class UpcomingTripsViewModel {
    private(set) var trips: [Trip] = []
    private let useCase: FetchUpcomingTripsUseCase

    init(useCase: FetchUpcomingTripsUseCase) {
        self.useCase = useCase
    }

    func load() async {
        trips = (try? await useCase.execute()) ?? []
    }
}
Use Clean Architecture when: Strict separation is required (enterprise, regulated domains), the domain layer must be testable without any framework dependencies, or multiple presentation targets share the same business logic.
分层结构：领域层（实体、用例、仓库协议）→ 数据层（仓库实现、网络、持久化）→ 表示层（视图、视图模型）。依赖关系向内指向。
swift
// Domain layer
protocol TripRepository: Sendable {
    func fetchAll() async throws -> [Trip]
    func save(_ trip: Trip) async throws
    func delete(id: UUID) async throws
}

struct FetchUpcomingTripsUseCase: Sendable {
    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func execute() async throws -> [Trip] {
        try await repository.fetchAll()
            .filter { $0.startDate > .now }
            .sorted { $0.startDate < $1.startDate }
    }
}

// Data layer
struct RemoteTripRepository: TripRepository {
    private let client: APIClient

    func fetchAll() async throws -> [Trip] {
        try await client.request(.get, "/trips")
    }
    // ...
}

// Presentation layer
@Observable
class UpcomingTripsViewModel {
    private(set) var trips: [Trip] = []
    private let useCase: FetchUpcomingTripsUseCase

    init(useCase: FetchUpcomingTripsUseCase) {
        self.useCase = useCase
    }

    func load() async {
        trips = (try? await useCase.execute()) ?? []
    }
}
**何时使用Clean Architecture：**需要严格分离（企业级、受监管领域）、领域层必须在无框架依赖的情况下可测试、多个表示目标共享相同业务逻辑。

Coordinator Pattern

Coordinator模式

Separates navigation logic from views. Especially useful in UIKit or hybrid apps with complex navigation flows.
swift
@MainActor
protocol Coordinator: AnyObject {
    var navigationController: UINavigationController { get }
    func start()
}

@MainActor
final class TripCoordinator: Coordinator {
    let navigationController: UINavigationController
    private let repository: TripRepository

    init(navigationController: UINavigationController, repository: TripRepository) {
        self.navigationController = navigationController
        self.repository = repository
    }

    func start() {
        let vm = TripListViewModel(repository: repository)
        vm.onSelectTrip = { [weak self] trip in
            self?.showDetail(for: trip)
        }
        let vc = TripListViewController(viewModel: vm)
        navigationController.pushViewController(vc, animated: false)
    }

    private func showDetail(for trip: Trip) {
        let vm = TripDetailViewModel(trip: trip, repository: repository)
        vm.onEdit = { [weak self] trip in self?.showEditor(for: trip) }
        let vc = TripDetailViewController(viewModel: vm)
        navigationController.pushViewController(vc, animated: true)
    }

    private func showEditor(for trip: Trip) {
        // ...
    }
}
In pure SwiftUI apps, 
NavigationStack
with path-based routing often replaces the Coordinator pattern. Use Coordinators when you need UIKit integration or shared navigation logic across platforms.
将导航逻辑与视图分离。在UIKit或包含复杂导航流程的混合应用中尤其有用。
swift
@MainActor
protocol Coordinator: AnyObject {
    var navigationController: UINavigationController { get }
    func start()
}

@MainActor
final class TripCoordinator: Coordinator {
    let navigationController: UINavigationController
    private let repository: TripRepository

    init(navigationController: UINavigationController, repository: TripRepository) {
        self.navigationController = navigationController
        self.repository = repository
    }

    func start() {
        let vm = TripListViewModel(repository: repository)
        vm.onSelectTrip = { [weak self] trip in
            self?.showDetail(for: trip)
        }
        let vc = TripListViewController(viewModel: vm)
        navigationController.pushViewController(vc, animated: false)
    }

    private func showDetail(for trip: Trip) {
        let vm = TripDetailViewModel(trip: trip, repository: repository)
        vm.onEdit = { [weak self] trip in self?.showEditor(for: trip) }
        let vc = TripDetailViewController(viewModel: vm)
        navigationController.pushViewController(vc, animated: true)
    }

    private func showEditor(for trip: Trip) {
        // ...
    }
}
在纯SwiftUI应用中，带有基于路径路由的
NavigationStack
通常会替代Coordinator模式。当需要UIKit集成或跨平台共享导航逻辑时，再使用Coordinator。

Migration Between Patterns

模式间迁移

ObservableObject → @Observable

ObservableObject → @Observable

swift
// Before (iOS 16)
class TripStore: ObservableObject {
    @Published var trips: [Trip] = []
}
// View uses @ObservedObject or @StateObject

// After (iOS 17+)
@Observable
class TripStore {
    var trips: [Trip] = []
}
// View uses @State for owned, plain property for injected
swift
// Before (iOS 16)
class TripStore: ObservableObject {
    @Published var trips: [Trip] = []
}
// View uses @ObservedObject or @StateObject

// After (iOS 17+)
@Observable
class TripStore {
    var trips: [Trip] = []
}
// View uses @State for owned, plain property for injected

MVVM → MV (simplifying)

MVVM → MV（简化）

If a view model only passes through model data without transforming it, remove the view model and let the view observe the model directly.
如果视图模型仅传递模型数据而不进行转换，则移除视图模型，让视图直接观察模型。

MV → MVVM (scaling up)

MV → MVVM（扩展）

Extract business logic and data transformation into a view model when:
  • The view's 
    body
    contains conditional logic for data formatting
  • Multiple views need different projections of the same model
  • You need to test logic without instantiating views
当出现以下情况时，将业务逻辑和数据转换提取到视图模型中：
  • 视图的
    body
    包含用于数据格式化的条件逻辑
  • 多个视图需要同一模型的不同投影
  • 需要在不实例化视图的情况下测试逻辑

Any → TCA

任意模式 → TCA

TCA adoption is typically incremental: wrap one feature's state and actions in a 
Reducer
, migrate its dependencies to 
@Dependency
, and test.
TCA的采用通常是增量式的：将一个功能的状态和操作包装在
Reducer
中，将其依赖项迁移到
@Dependency
，然后进行测试。

Common Mistakes

常见错误

MistakeFix
Using 
ObservableObject
in new iOS 17+ code		Use 
@Observable
instead
View model that only forwards model propertiesRemove the view model; use MV pattern
Massive view model with navigation, networking, and formattingSplit into focused collaborators (coordinator, service, formatter)
Choosing TCA for a two-screen appStart with MV; adopt TCA when composition and testing demands justify it
Protocol-heavy Clean Architecture for a simple featureMatch architecture complexity to feature complexity
Coordinator pattern in pure SwiftUI without UIKit needsUse 
NavigationStack
path-based routing instead
Mixing architecture patterns inconsistently within a moduleOne pattern per feature module; different modules can use different patterns
错误修复方案
在iOS 17+新项目中使用
ObservableObject
改用
@Observable
仅转发模型属性的视图模型移除视图模型；使用MV模式
包含导航、网络和格式化逻辑的巨型视图模型拆分为专注的协作组件（Coordinator、服务、格式化器）
为双屏应用选择TCA从MV开始；当组合和测试需求证明其合理性时再采用TCA
为简单功能使用过度依赖协议的Clean Architecture使架构复杂度与功能复杂度匹配
在无UIKit需求的纯SwiftUI应用中使用Coordinator模式改用基于路径路由的
NavigationStack
在模块内不一致地混合架构模式每个功能模块使用一种模式；不同模块可以使用不同模式

Review Checklist

审查清单

  • Architecture choice is justified by feature complexity and team needs
  • @Observable
    used instead of 
    ObservableObject
    for iOS 17+ targets
  • Dependencies are injected, not created internally (testability)
  • Navigation logic is separated from business logic
  • State mutations happen in a clear, auditable location
  • View models (if present) are testable without views
  • No god objects — responsibilities are distributed appropriately
  • Pattern is consistent within each feature module
  • 架构选择符合功能复杂度和团队需求
  • iOS 17+目标中使用
    @Observable
    而非
    ObservableObject
  • 依赖项通过注入而非内部创建（可测试性）
  • 导航逻辑与业务逻辑分离
  • 状态变更发生在清晰、可审计的位置
  • 视图模型（如果存在）无需视图即可测试
  • 不存在上帝对象——职责被合理分配
  • 每个功能模块内的模式保持一致

References

参考资料