Quando o monólito começa a custar caro no dia a dia
Todo aplicativo iOS começa simples: um target principal no Xcode, algumas pastas organizadas por assunto e builds incrementais que terminam em menos de dez segundos. O problema aparece quando o produto cresce, entram cinco ou seis squads mexendo na mesma base de código e o aplicativo passa a acumular fluxos de conta, cartões, transferências, atendimento e notificações no mesmo módulo.
Em um projeto corporativo com mais de trinta engenheiros iOS onde trabalhei, chegamos a um ponto em que uma alteração de duas linhas em uma tela de pagamento exigia quase quatro minutos de compilação local. Além do tempo perdido, os conflitos no arquivo project.pbxproj viraram rotina toda tarde e o autocomplete do Xcode travava com frequência. Pior ainda: como tudo enxergava tudo, a tela de extrato importava direto o controlador de fatura, que por sua vez chamava o fluxo de contestação de compra. Bastava mudar um inicializador para quebrar três áreas diferentes do aplicativo.
Dividir o aplicativo em pacotes menores usando Swift Package Manager (SPM) resolve a compilação e separa os domínios, mas cria uma pergunta imediata: como o módulo de Extrato abre uma tela do módulo de Cartões sem declarar dependência direta entre os dois? Se os módulos voltarem a se importar mutuamente, o grafo de compilação perde o paralelismo e o monólito reaparece disfarçado de múltiplos pacotes.
Regra de fronteira entre módulos: módulos de funcionalidade devem depender apenas de pacotes leves de contrato (interfaces e modelos compartilhados) e de um barramento de roteamento. Nenhum módulo de feature deve importar outro módulo de feature.
Separando contrato de navegação e composição do aplicativo
O erro mais comum de quem tenta modularizar um app iOS pela primeira vez é criar um módulo AppNavigation que importa todas as features para montar os fluxos. Na prática, esse módulo vira um funil gigante: qualquer mudança em qualquer squad invalida o cache de compilação do coordenador central.
A saída que funciona melhor em produção inverte essa dependência. Você cria um pacote pequeno, chamado por exemplo RoutingInterface, contendo somente os protocolos de rota, o modelo de destino e o contrato do roteador. Todos os módulos de feature importam apenas RoutingInterface. Já o registro das implementações concretas acontece exclusivamente no target principal do app (o Composition Root), no momento em que o aplicativo inicializa.
Com esse desenho, o grafo de compilação fica achatado e largo. Se a squad de Cartões altera vinte arquivos internos, o Xcode recompila apenas FeatureCartoes e religa o executável final. Os módulos de Conta e Pagamentos continuam aproveitando o cache intacto, algo que também traz ganho direto quando combinado com as práticas de cache que detalho no artigo sobre otimização de pipelines de CI/CD para aplicativos iOS.
Implementando um roteador com middlewares e segurança de thread
Roteadores simples demais costumam falhar no primeiro mês em produção porque ignoram três exigências reais: validação de sessão antes de abrir telas autenticadas, checagem de feature flags para contingência e garantia de que toda transição de interface aconteça na main thread.
Abaixo está uma estrutura enxuta em Swift que uso como base. Repare que o roteador recebe middlewares ordenados antes de entregar a rota ao handler responsável, e toda a execução de navegação fica marcada com @MainActor para evitar bugs intermitentes de UIKit quando um deeplink chega vindo de um callback de rede ou de uma notificação push:
import Foundation
import UIKit
public struct RouteRequest: Sendable {
public let url: URL
public let pathComponents: [String]
public let queryItems: [String: String]
public init?(url: URL) {
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
return nil
}
self.url = url
self.pathComponents = url.pathComponents.filter { $0 != "/" }
var mapped: [String: String] = [:]
components.queryItems?.forEach { item in
if let value = item.value {
mapped[item.name] = value
}
}
self.queryItems = mapped
}
}
public enum RouteDecision: Sendable {
case proceed(RouteRequest)
case redirect(URL)
case block(reason: String)
}
@MainActor
public protocol RouteMiddleware {
func evaluate(_ request: RouteRequest) -> RouteDecision
}
@MainActor
public protocol RouteHandler {
var hostIdentifier: String { get }
func canHandle(_ request: RouteRequest) -> Bool
func handle(_ request: RouteRequest, from presenter: UIViewController) -> Bool
}
@MainActor
public final class AppRouter {
private var handlers: [String: [RouteHandler]] = [:]
private var middlewares: [RouteMiddleware] = []
private let fallbackHandler: ((URL, UIViewController) -> Void)?
public init(fallbackHandler: ((URL, UIViewController) -> Void)? = nil) {
self.fallbackHandler = fallbackHandler
}
public func register(handler: RouteHandler) {
handlers[handler.hostIdentifier, default: []].append(handler)
}
public func add(middleware: RouteMiddleware) {
middlewares.append(middleware)
}
@discardableResult
public func navigate(to url: URL, from presenter: UIViewController) -> Bool {
guard var request = RouteRequest(url: url) else { return false }
for middleware in middlewares {
switch middleware.evaluate(request) {
case .proceed(let updated):
request = updated
case .redirect(let newURL):
return navigate(to: newURL, from: presenter)
case .block:
return false
}
}
let host = request.url.host ?? ""
let candidates = handlers[host] ?? []
if let match = candidates.first(where: { $0.canHandle(request) }) {
return match.handle(request, from: presenter)
}
fallbackHandler?(request.url, presenter)
return false
}
} Indexar os handlers por hostIdentifier em vez de percorrer um array linear evita colisões silenciosas quando o aplicativo passa de cinquenta rotas registradas. Além disso, o fallbackHandler permite registrar telemetria de rotas órfãs e direcionar o usuário para a tela inicial ou para uma webview controlada quando uma campanha de marketing dispara um link antigo.
Plugando feature flags e contingência antes da tela abrir
Colocar o controle de toggle dentro de um middleware ou na porta de entrada do handler muda completamente a resposta a incidentes. Se uma experiência nova de cartões começa a gerar crashes logo após a liberação na App Store, você desliga a flag remotamente e o roteador desvia o fluxo para a versão legada ou para uma tela de aviso, sem precisar esperar revisão emergencial da loja. Se quiser aprofundar essa camada de rollout progressivo, escrevi em detalhe sobre isso em feature flags e lançamento progressivo em aplicativos críticos.
public protocol FeatureFlagChecking: Sendable {
func isEnabled(_ key: String) -> Bool
}
@MainActor
public final class CardsRouteHandler: RouteHandler {
public let hostIdentifier = "cards"
private let flags: FeatureFlagChecking
private let makeModernFlow: (String) -> UIViewController
private let makeLegacyFlow: (String) -> UIViewController
public init(
flags: FeatureFlagChecking,
makeModernFlow: @escaping (String) -> UIViewController,
makeLegacyFlow: @escaping (String) -> UIViewController
) {
self.flags = flags
self.makeModernFlow = makeModernFlow
self.makeLegacyFlow = makeLegacyFlow
}
public func canHandle(_ request: RouteRequest) -> Bool {
request.pathComponents.first == "detail" && request.queryItems["id"] != nil
}
public func handle(_ request: RouteRequest, from presenter: UIViewController) -> Bool {
guard let cardId = request.queryItems["id"], !cardId.isEmpty else {
return false
}
let destination = flags.isEnabled("cards_v2_detail")
? makeModernFlow(cardId)
: makeLegacyFlow(cardId)
if let navigation = presenter.navigationController {
navigation.pushViewController(destination, animated: true)
} else {
presenter.present(destination, animated: true)
}
return true
}
} Repare que o CardsRouteHandler recebe fábricas injetadas para construir os controladores. Isso permite testar o roteamento em milissegundos usando um UIViewController() vazio e um mock de FeatureFlagChecking, sem instanciar rede, banco local ou dependências de UI complexas.
Armadilhas de runtime e build que aparecem em produção
Roteamento por URL parece limpo no papel, mas quatro problemas recorrentes costumam derrubar times quando o sistema vai para a rua:
O primeiro é o cold start com Universal Link pendente. O usuário toca em um link recebido por mensagem com o app totalmente fechado. O sistema operacional entrega a URL no scene(_:willConnectTo:options:) antes de o usuário autenticar com biometria ou antes de o container de dependências terminar de carregar as flags remotas. Se o roteador tentar navegar imediatamente, o fluxo falha em silêncio ou abre uma tela protegida sem token válido. A solução prática consiste em guardar uma pendingRouteURL na memória e drenar essa fila somente depois que a sessão autenticada estiver pronta e a navegação raiz montada.
O segundo problema é silencioso e traiçoeiro: duplicação de singletons por static linking. Se RoutingInterface for declarado como biblioteca estática no SPM e importado simultaneamente pelo app principal e por um framework dinâmico interno, o linker pode duplicar o símbolo AppRouter.shared em dois binários diferentes. O app registra todos os handlers em uma instância, enquanto a feature chama navigate em outra instância vazia. Por isso, evite singletons globais no roteador; injete a instância única via inicializador ou garanta linking dinâmico explícito para o módulo de contratos.
O terceiro ponto envolve validação de parâmetros externos. Qualquer URL que entra por Universal Link ou custom scheme deve ser tratada como entrada não confiável. Nunca passe strings recebidas na query direto para chamadas de API sem sanitização, e nunca confie em redirecionamentos abertos do tipo app://webview?url=... sem validar o domínio em uma lista estrita de hosts permitidos.
Por fim, cuidado com ciclos infinitos de redirect nos middlewares. Se o middleware de autenticação redireciona para app://auth/login e esse mesmo middleware não isenta o host auth, a função navigate entra em recursão até estourar a pilha. Coloque um contador máximo de saltos (por exemplo, limite de 3 redirecionamentos) e falhe de forma controlada com log.
Comparativo entre estratégias de navegação modular
Nem toda equipe precisa começar por URLs. A tabela abaixo resume os trade-offs práticos entre as três abordagens mais comuns em projetos Swift corporativos:
| Critério | Coordinators com injeção direta | Roteador por enum / descritor tipado | Roteador baseado em URL / Deeplink |
|---|---|---|---|
| Acoplamento de compilação | Alto se os coordinators importarem features entre si | Baixo, desde que os descritores vivam em um módulo de contrato | Muito baixo; features conhecem apenas o contrato de URL |
| Segurança em tempo de compilação | Máxima; tipos checados pelo compilador | Alta; parâmetros obrigatórios ficam explícitos na struct | Baixa na string; exige testes de contrato e validadores |
| Integração com Push e Universal Links | Exige camada extra de tradução | Exige parser de URL para descritor tipado | Nativa; o mesmo caminho atende navegação interna e externa |
| Manutenção com 30+ desenvolvedores | Tende a virar gargalo de merge e build | Boa, mas o pacote de descritores cresce rápido e exige revisão constante | Excelente para autonomia de squads, desde que haja catálogo versionado |
Em vários apps grandes, o meio-termo mais saudável é usar descritores tipados dentro do módulo (por exemplo, um método construtor CardsRoute.detail(cardId: "42").asURL() no pacote de interface) que convertem para URL padronizada. Assim você mantém checagem de tipos no código Swift sem perder a compatibilidade direta com notificações push e campanhas web.
Quando adotar e checklist de revisão de PR
Se o seu aplicativo tem até cinco engenheiros iOS e menos de vinte telas, montar um barramento de rotas por URL provavelmente vai gerar mais indireção do que benefício. Um conjunto simples de Coordinators ou NavigationStack tipado em SwiftUI resolve o problema com menos código. O roteador desacoplado passa a se pagar quando há múltiplas squads liberando fluxos em paralelo, quando o tempo de build incremental ultrapassa um minuto ou quando o produto depende fortemente de campanhas via Universal Links e notificações push.
Antes de aprovar um pull request que cria ou altera uma rota modular, vale checar estes itens na revisão:
- O módulo de origem importa apenas o pacote de contratos de navegação e não referencia nenhuma classe concreta do módulo de destino.
- Todos os parâmetros obrigatórios da URL são validados com guarda explícita e a rota falha de forma segura caso venham vazios ou malformados.
- O handler roda isolado na main thread e respeita o estado de autenticação exigido pelo fluxo.
- Existe teste unitário garantindo o casamento da URL, o comportamento com feature flag desligada e o redirecionamento quando faltam parâmetros.
- Rotas novas ou alteradas foram registradas no catálogo de deeplinks do time para não quebrar campanhas antigas nem notificações agendadas.
