Arquitetura SwiftUI
Quando Usar Este Skill
Use este skill quando:
- Você tem lógica em seus arquivos de view SwiftUI e deseja extraí-la
- Escolhendo entre MVVM, TCA, padrões SwiftUI puros ou Coordinator
- Refatorando views para separar responsabilidades
- Tornando código SwiftUI testável
- Perguntando "onde este código deve ir?"
- Decidindo qual property wrapper usar (@State, @Environment, @Bindable)
- Organizando uma base de código SwiftUI para desenvolvimento em equipe
Exemplos de Prompts
| O Que Você Pode Perguntar | Por Que Este Skill Ajuda |
|---|---|
| "Tem bastante código nos meus arquivos de view sobre lógica. Como extraio isso?" | Fornece fluxo de refatoração com árvores de decisão sobre onde a lógica pertence |
| "Devo usar MVVM, TCA ou os padrões da Apple?" | Critérios de decisão baseados em complexidade do app, tamanho da equipe, necessidades de testabilidade |
| "Como tornar meu código SwiftUI testável?" | Mostra padrões de separação que permitem teste sem imports do SwiftUI |
| "Onde devem ir os formatadores e cálculos?" | Seção de anti-padrões previne lógica no corpo das views |
| "Qual property wrapper usar?" | Árvore de decisão para @State, @Environment, @Bindable ou propriedades simples |
Árvore de Decisão Rápida de Arquitetura
O que está guiando sua escolha de arquitetura?
│
├─ Começando do zero, app pequeno/médio, quer padrões da Apple?
│ └─ Use Padrões Nativos da Apple (Parte 1)
│ - Modelos @Observable para lógica de negócios
│ - State-as-Bridge para limites assíncronos
│ - Árvore de decisão de property wrapper
│
├─ Familiar com MVVM do UIKit?
│ └─ Use Padrão MVVM (Parte 2)
│ - ViewModels como adaptadores de apresentação
│ - Separação clara View/ViewModel/Model
│ - Funciona bem com @Observable
│
├─ App complexo, precisa de testabilidade rigorosa, consistência de equipe?
│ └─ Considere TCA (Parte 3)
│ - Arquitetura State/Action/Reducer/Store
│ - Excelente história de teste
│ - Curva de aprendizado + trade-off de boilerplate
│
└─ Navegação complexa, deep linking, múltiplos pontos de entrada?
└─ Adicione Padrão Coordinator (Parte 4)
- Pode combinar com qualquer um acima
- Extrai lógica de navegação das views
- NavigationPath + objetos Coordinator
Parte 1: Padrões Nativos da Apple (iOS 26+)
Princípio Central
"Um modelo de dados fornece separação entre os dados e as views que interagem com os dados. Essa separação promove modularidade, melhora a testabilidade e ajuda a tornar mais fácil raciocinar sobre como o app funciona." — Documentação do Desenvolvedor Apple
Os padrões SwiftUI modernos da Apple (WWDC 2023-2025) centram-se em:
- @Observable para modelos de dados (substitui ObservableObject)
- State-as-Bridge para limites assíncronos (WWDC 2025)
- Três property wrappers: @State, @Environment, @Bindable
- Atualizações de UI síncronas para animações
O Padrão State-as-Bridge
Problema
Funções assíncronas criam pontos de suspensão que podem quebrar animações:
// ❌ Problemático: Animação pode perder o prazo do frame
struct ColorExtractorView: View {
@State private var isLoading = false
var body: some View {
Button("Extrair Cores") {
Task {
isLoading = true // Síncrono ✅
await extractColors() // ⚠️ Ponto de suspensão!
isLoading = false // ❌ Pode acontecer tarde demais
}
}
.scaleEffect(isLoading ? 1.5 : 1.0) // ⚠️ Tempo da animação incerto
}
}
Solução: Use State como uma Ponte
"Encontre os limites entre o código de UI que requer mudanças sensíveis ao tempo e a lógica assíncrona de longa duração."
// ✅ Correto: State ponteia UI e código assíncrono
@Observable
class ColorExtractor {
var isLoading = false
var colors: [Color] = []
func extract(from image: UIImage) async {
// Este método é assíncrono e pode viver no modelo
let extracted = await heavyComputation(image)
// Mutação síncrona para atualização da UI
self.colors = extracted
}
}
struct ColorExtractorView: View {
let extractor: ColorExtractor
var body: some View {
Button("Extrair Cores") {
// Mudança de estado síncrona para animação
withAnimation {
extractor.isLoading = true
}
// Inicia trabalho assíncrono
Task {
await extractor.extract(from: currentImage)
// Mudança de estado síncrona para animação
withAnimation {
extractor.isLoading = false
}
}
}
.scaleEffect(extractor.isLoading ? 1.5 : 1.0)
}
}
Benefícios:
- Lógica de UI permanece síncrona (animações funcionam corretamente)
- Código assíncrono vive no modelo (testável sem SwiftUI)
- Limite claro entre UI sensível ao tempo e trabalho de longa duração
Árvore de Decisão de Property Wrapper
Existem apenas 3 perguntas a responder:
Qual property wrapper devo usar?
│
├─ Este modelo precisa ser ESTADO DA PRÓPRIA VIEW?
│ └─ SIM → Use @State
│ Exemplos: Entradas de formulário, toggles locais, apresentações de sheet
│ Tempo de vida: Gerenciado pelo tempo de vida da view
│
├─ Este modelo precisa fazer parte do AMBIENTE GLOBAL?
│ └─ SIM → Use @Environment
│ Exemplos: Conta de usuário, configurações do app, injeção de dependência
│ Tempo de vida: Vive no nível do app/cena
│
├─ Este modelo PRECISA APENAS DE BINDINGS?
│ └─ SIM → Use @Bindable
│ Exemplos: Editando um modelo passado do pai
│ Leve: Apenas habilita a sintaxe $ para bindings
│
└─ NENHUMA DAS ACIMA?
└─ Use como propriedade simples
Exemplos: Dados imutáveis, modelos de propriedade do pai
Nenhum wrapper necessário: @Observable lida com a observação
Exemplos
// ✅ @State — View possui o modelo
struct DonutEditor: View {
@State private var donutToAdd = Donut() // Estado próprio da view
var body: some View {
TextField("Nome", text: $donutToAdd.name)
}
}
// ✅ @Environment — Modelo em todo o app
struct MenuView: View {
@Environment(Account.self) private var account // Global
var body: some View {
Text("Bem-vindo, \(account.userName)")
}
}
// ✅ @Bindable — Precisa de bindings para modelo do pai
struct DonutRow: View {
@Bindable var donut: Donut // Pai o possui
var body: some View {
TextField("Nome", text: $donut.name) // Precisa de binding
}
}
// ✅ Propriedade simples — Apenas leitura
struct DonutRow: View {
let donut: Donut // Pai possui, sem binding necessário
var body: some View {
Text(donut.name) // Apenas leitura
}
}
Padrão de Modelo @Observable
Use @Observable para lógica de negócios que precisa acionar atualizações de UI:
// ✅ Modelo de domínio com lógica de negócios
@Observable
class FoodTruckModel {
var orders: [Order] = []
var donuts = Donut.all
var orderCount: Int {
orders.count // Propriedades computadas funcionam automaticamente
}
func addDonut() {
donuts.append(Donut())
}
}
// ✅ View rastreia automaticamente propriedades acessadas
struct DonutMenu: View {
let model: FoodTruckModel // Nenhum wrapper necessário!
var body: some View {
List {
Section("Donuts") {
ForEach(model.donuts) { donut in
Text(donut.name) // Rastreia model.donuts
}
Button("Adicionar") {
model.addDonut()
}
}
Section("Pedidos") {
Text("Contagem: \(model.orderCount)") // Rastreia model.orders
}
}
}
}
Como funciona (WWDC 2023/10149):
- SwiftUI rastreia quais propriedades são acessadas durante a execução de
body - Apenas essas propriedades acionam atualizações de view quando alteradas
- Rastreamento granular de dependências = melhor desempenho
Padrão ViewModel Adapter
Use ViewModels como adaptadores de apresentação quando você precisar de filtragem, ordenação ou lógica específica de view:
// ✅ ViewModel como adaptador de apresentação
@Observable
class PetStoreViewModel {
let petStore: PetStore // Modelo de domínio
var searchText: String = ""
// Propriedade computada específica da view
var filteredPets: [Pet] {
guard !searchText.isEmpty else { return petStore.myPets }
return petStore.myPets.filter { $0.name.contains(searchText) }
}
}
struct PetListView: View {
@Bindable var viewModel: PetStoreViewModel
var body: some View {
List {
ForEach(viewModel.filteredPets) { pet in
PetRowView(pet: pet)
}
}
.searchable(text: $viewModel.searchText)
}
}
Quando usar um ViewModel adapter:
- Filtragem, ordenação, agrupamento para exibição
- Formatação para apresentação (mas NÃO computação pesada)
- Estado específico da view que não pertence ao modelo de domínio
- Ponte entre modelo de domínio e convenções SwiftUI
Quando NÃO usar um ViewModel:
- Views simples que apenas exibem dados do modelo
- Lógica que pertence ao modelo de domínio
- Extração excessiva apenas por "pureza de padrão"
Parte 2: Padrão MVVM
Quando Usar MVVM
MVVM (Model-View-ViewModel) é apropriado quando:
✅ Você está familiarizado com ele do UIKit — Integração mais fácil para a equipe ✅ Você quer separação explícita View/ViewModel — Contratos claros ✅ Você tem lógica de apresentação complexa — Múltiplas operações de filtragem/ordenação ✅ Você está migrando do UIKit — Modelo mental familiar
❌ Evite MVVM quando:
- Views são simples (apenas exibindo dados)
- Você está começando do zero com SwiftUI (padrões da Apple são mais simples)
- Você está criando camadas de abstração desnecessárias
Estrutura MVVM para SwiftUI
// Model — Dados de domínio e lógica de negócios
struct Pet: Identifiable {
let id: UUID
var name: String
var kind: Kind
var trick: String
var hasAward: Bool = false
mutating func giveAward() {
hasAward = true
}
}
// ViewModel — Lógica de apresentação
@Observable
class PetListViewModel {
private let petStore: PetStore
var pets: [Pet] { petStore.myPets }
var searchText: String = ""
var selectedSort: SortOption = .name
var filteredSortedPets: [Pet] {
let filtered = pets.filter { pet in
searchText.isEmpty || pet.name.contains(searchText)
}
return filtered.sorted { lhs, rhs in
switch selectedSort {
case .name: lhs.name < rhs.name
case .kind: lhs.kind.rawValue < rhs.kind.rawValue
}
}
}
init(petStore: PetStore) {
self.petStore = petStore
}
func awardPet(_ pet: Pet) {
petStore.awardPet(pet.id)
}
}
// View — Apenas UI
struct PetListView: View {
@Bindable var viewModel: PetListViewModel
var body: some View {
List {
ForEach(viewModel.filteredSortedPets) { pet in
PetRow(pet: pet) {
viewModel.awardPet(pet)
}
}
}
.searchable(text: $viewModel.searchText)
}
}
Erros Comuns de MVVM em SwiftUI
❌ Erro 1: Duplicando @Observable na View e ViewModel
// ❌ @State + @Observable é redundante — @State cria seu próprio armazenamento
struct MyView: View {
@State private var viewModel = MyViewModel() // ❌ Wrapper redundante
}
// ✅ Passe @Observable diretamente — use @State apenas se a view POSSUIR o ciclo de vida
struct MyView: View {
let viewModel: MyViewModel // ✅ Ou @State se a view o criar
}
❌ Erro 2: ViewModel Deus
// ❌ Não faça isso
@Observable
class AppViewModel {
// Configurações
var isDarkMode = false
var notificationsEnabled = true
// Usuário
var userName = ""
var userEmail = ""
// Conteúdo
var posts: [Post] = []
var comments: [Comment] = []
// ... mais 50 propriedades
}
// ✅ Correto: Separe responsabilidades
@Observable
class SettingsViewModel {
var isDarkMode = false
var notificationsEnabled = true
}
@Observable
class UserProfileViewModel {
var user: User
}
@Observable
class FeedViewModel {
var posts: [Post] = []
}
❌ Erro 3: Lógica de Negócios no ViewModel
// ❌ Regras de negócios pertencem ao Model, não ao ViewModel
@Observable class OrderViewModel {
func calculateDiscount(for order: Order) -> Double { /* ... */ } // ❌ Lógica de negócios
}
// ✅ Model possui lógica de negócios; ViewModel apenas formata para exibição
struct Order {
func calculateDiscount() -> Double { /* regras de negócio */ }
}
@Observable class OrderViewModel {
let order: Order
var displayDiscount: String {
"$\(order.calculateDiscount(), specifier: \"%.2f\")" // ✅ Apenas formatação
}
}
Parte 3: TCA (Arquitetura Componível)
Quando Considerar TCA
TCA é uma arquitetura de terceiros da Point-Free. Considere-a quando:
✅ Testabilidade rigorosa é crítica — TestStore torna o teste determinístico ✅ Equipe grande precisa de consistência — Padrões estritos reduzem variação ✅ Gerenciamento de estado complexo — Efeitos colaterais, dependências, composição ✅ Você valoriza padrões tipo Redux — Fluxo de dados unidirecional
❌ Evite TCA quando:
- App pequeno ou protótipo (muita sobrecarga)
- Equipe não familiarizada com programação funcional
- Você precisa de iteração rápida (boilerplate atrasa desenvolvimento)
- Você quer dependências mínimas
Conceitos Centrais do TCA
TCA tem 4 blocos de construção — State (dados), Action (eventos), Reducer (evolução do estado) e Store (motor de execução). Aqui estão eles em uma única feature:
// STATE — Dados que sua feature precisa
@ObservableState
struct CounterFeature {
var count = 0
var fact: String?
var isLoading = false
}
// ACTION — Todos os eventos possíveis
enum Action {
case incrementButtonTapped
case decrementButtonTapped
case factButtonTapped
case factResponse(String)
}
// REDUCER — Como o estado evolui em resposta a ações
struct CounterFeature: Reducer {
var body: some ReducerOf<Self> {
Reduce { state, action in
switch action {
case .incrementButtonTapped:
state.count += 1
return .none
case .decrementButtonTapped:
state.count -= 1
return .none
case .factButtonTapped:
state.isLoading = true
// Efeito colateral: busca fato
return .run { send in
let fact = await getFact(state.count)
await send(.factResponse(fact))
}
case .factResponse(let fact):
state.isLoading = false
state.fact = fact
return .none
}
}
}
}
Benefícios do TCA:
- Testabilidade: TestStore permite testar reducers de forma isolada e determinística
- Composabilidade: Features podem ser compostas em hierarquias
- Gerenciamento de efeitos: Efeitos colaterais são explicitamente modelados
- Histórico de ações: Fácil depuração com logs de ações
Considerações:
- Curva de aprendizado: Conceitos como Reducer, Store e efeitos colaterais
- Boilerplate: Mais código para features simples
- Dependência externa: Mantida pela Point-Free, mas ainda de terceiros
Parte 4: Padrão Coordinator
Quando Usar Coordinators
Use Coordinators quando:
✅ Navegação complexa — Fluxos com múltiplos caminhos ✅ Deep linking — URLs ou notificações que abrem telas específicas ✅ Múltiplos pontos de entrada — Widgets, ações rápidas, atalhos ✅ Reutilização de fluxos — Mesma sequência de telas em diferentes contextos
❌ Evite Coordinators quando:
- App de uma única tela ou navegação simples
- Você está feliz com NavigationStack e NavigationLink
- Você quer manter o mínimo possível de abstração
Estrutura do Coordinator
// Coordinator gerencia navegação e fluxos
@Observable
class AppCoordinator {
var path = NavigationPath()
var presentedSheet: Sheet?
enum Sheet: Identifiable {
case settings
case profile(User)
var id: String {
switch self {
case .settings: "settings"
case .profile(let user): user.id.uuidString
}
}
}
func showSettings() {
presentedSheet = .settings
}
func showProfile(_ user: User) {
presentedSheet = .profile(user)
}
func navigateToDonut(_ donut: Donut) {
path.append(DonutRoute.detail(donut))
}
func popToRoot() {
path.removeLast(path.count)
}
}
// View usa o Coordinator
struct AppView: View {
@State private var coordinator = AppCoordinator()
var body: some View {
NavigationStack(path: $coordinator.path) {
HomeView(coordinator: coordinator)
.navigationDestination(for: DonutRoute.self) { route in
switch route {
case .detail(let donut):
DonutDetailView(donut: donut, coordinator: coordinator)
case .list:
DonutListView(coordinator: coordinator)
}
}
}
.sheet(item: $coordinator.presentedSheet) { sheet in
switch sheet {
case .settings:
SettingsView()
case .profile(let user):
ProfileView(user: user)
}
}
}
}
Por que Coordinators funcionam bem com SwiftUI:
- NavigationPath fornece gerenciamento de pilha tipo UIKit
- Coordinators podem ser @Observable, integrando-se perfeitamente
- Separa responsabilidades de navegação da lógica de view
- Facilita teste de fluxos de navegação
Guia de Refatoração
Quando Refatorar
Refatore quando você perceber:
- View gorda: View com muitas responsabilidades (lógica, formatação, estado)
- Dificuldade de teste: Lógica de negócios amarrada a SwiftUI
- Duplicação: Mesmo padrão de código aparecendo em várias views
- Baixa coesão: Propriedades não relacionadas na mesma view/modelo
Processo de Refatoração
1. Identifique o que extrair
O que está causando o problema?
│
├─ Lógica de apresentação (formatação, filtragem)?
│ └→ Crie um ViewModel ou adaptador de apresentação
│
├─ Lógica de negócios (cálculos, regras)?
│ └→ Mova para o Model de domínio
│
├─ Lógica de navegação (fluxos, deep links)?
│ └→ Crie um Coordinator
│
└─ Código assíncrono (chamadas de rede, banco de dados)?
└→ Use o padrão State-as-Bridge
2. Extraia passo a passo
- Extraia tipo: Crie uma struct/class separada para a lógica
- Mova propriedades: Transfira propriedades relacionadas para o novo tipo
- Mova métodos: Transfira métodos que operam nessas propriedades
- Atualize view: Modifique a view para usar o novo tipo
- Teste: Verifique se a view ainda funciona como antes
3. Exemplo de Refatoração
Antes — Tudo na view:
struct OrderListView: View {
@State private var orders: [Order] = []
@State private var searchText = ""
@State private var isLoading = false
var filteredOrders: [Order] {
guard !searchText.isEmpty else { return orders }
return orders.filter { $0.name.contains(searchText) }
}
var body: some View {
List(filteredOrders) { order in
Text(order.name)
}
.searchable(text: $searchText)
.task {
isLoading = true
orders = await APIClient.fetchOrders()
isLoading = false
}
}
}
Depois — Lógica extraída para ViewModel:
@Observable
class OrderListViewModel {
private(set) var orders: [Order] = []
var searchText = ""
var filteredOrders: [Order] {
guard !searchText.isEmpty else { return orders }
return orders.filter { $0.name.contains(searchText) }
}
func loadOrders() async {
orders = await APIClient.fetchOrders()
}
}
struct OrderListView: View {
@State private var viewModel = OrderListViewModel()
var body: some View {
List(viewModel.filteredOrders) { order in
Text(order.name)
}
.searchable(text: $viewModel.searchText)
.task {
await viewModel.loadOrders()
}
}
}
Anti-Padrões
1. Lógica no Corpo da View
// ❌ Evite: Formatação e cálculo no corpo da view
var body: some View {
Text("Total: \(items.reduce(0) { $0 + $1.price }, specifier: \"%.2f\")") // ❌
}
2. ViewModels Inchados
// ❌ ViewModel que faz tudo
@Observable class GiantViewModel {
// 30 propriedades de domínios diferentes
// 20 métodos de vários contextos
}
3. Ignorar Padrões da Apple
// ❌ Usar ObservableObject quando @Observable está disponível
class OldViewModel: ObservableObject { // ❌ Desnecessário em iOS 26+
@Published var value = 0
}
4. Extração Prematura
// ❌ Extrair ViewModel para view que só exibe dados
struct SimpleLabel: View {
let text: String // ✅ Suficiente
}