Uma ferramenta de depuração puramente baseada em SwiftUI, inspirada na FLEX, que monitora o tráfego da rede, inspeciona os estados dos objetos ao vivo e gerencia UserDefaults em tempo real.

O Problema: A “ritualística Xcode & Cable”

Assim como a maioria dos desenvolvedores iOS, odeio ter que conectar meu telefone ao Xcode apenas para verificar se uma chave UserDefaults foi atualizada ou para validar um payload de solicitação API bruto. As coisas ficam ainda piores quando você está testando em um dispositivo do QA ou verificando uma versão TestFlight no mundo real, e precisa configurar certificados SSL do Charles Proxy ou do Proxyman apenas para rastrear uma simples falha na rede.

A depuração no dispositivo não deve exigir cabos de desktop, perfis proxy ou declarações de console do Xcode cheias de informações.

Para resolver essa fricção, eu queria uma dashboard de depuração leve e inspirada na FLEX que vive diretamente dentro da hierarquia de visualização do aplicativo, escrita completamente em SwiftUI.

É por isso que eu construí o KDInspector.

Por Que Construir Isso?

Aqui está o que torna uma sobreposição de depuração em aplicativo um jogo-changer para fluxos de trabalho de desenvolvimento:

• Diga adeus aos cabos USB: Navegue por arquivos locais, logs e molduras de layout em dispositivos físicos em qualquer lugar - sem conexão do depurador.
• Configurações de proxy zero: Intercepte e visualize o tráfego da rede do backend sem lidar com perfis de confiança SSL ou configurações de IP do proxy.
• Amigável para QA e equipe de produtos: Permita que seus testadores de qualidade e designers inspecionem bandeiras de onboarding e configurações ao vivo durante as execuções TestFlight.
• Modificadores de estado imediatos: Modifique estados de cache local e bandeiras persistentes em linha para testar condições de limite imediatamente.

Recursos do KDInspector

O KDInspector divide as diagnósticas internas do seu aplicativo em cinco abas modulares:

1. Interceptor de Logs da Rede: Captura automaticamente todos os logs de entrada e saída URLSession.
2. Refletor de Objetos: Usa Swift Mirroring (Mirror) para imprimir e navegar pelos estados das propriedades em tempo de execução de structs ou classes.
3. Editor Live UserDefaults: Lista todos os estados chave-valor nos seus conjuntos e suporta edição em linha de strings.
4. Explorador do Sistema de Arquivos Sandbox: Navega por diretórios locais (Documentos, Caches) para verificar arquivos baixados e tamanhos.
5. Hierarquia de Visualização: Lista todos os nós ativos da hierarquia de visualizações, dimensões do frame e bandeiras de visibilidade.

A Pilha Técnica

• Swift 5.9+ / Testes Swift: Utiliza macros modernos do Swift para testes unitários modulares.
• SwiftUI: Componentes de interface dinâmicos com animações micro-spring e efeitos glassmorphic.
• Foundation URLProtocol: Um interceptador personalizado que se registra para rastrear chamadas de rede.

Detalhes Chave da Implementação

1. Iniciando o Interceptador de Rede

No ponto de entrada do seu aplicativo, registre o interceptador. Isso se conecta ao sistema de carregamento de URLs para capturar cabeçalhos HTTP e payloads:

import SwiftUI
import NetworkInspector

@main
struct InterceptorTestApp: App {
    init() {
        // Comece a monitorar todos os tráfegos de rede imediatamenta
        NetworkMonitor.shared.startMonitoring()
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

2. Adicionando o Overlay Arrastável

Para tornar o painel acessível em qualquer tela, aplique a modificadora de visualização .kdInspectorOverlay(). Isso renderiza um botão de sobreposição que persiste sua posição via UserDefaults:

import SwiftUI
import KDInspector

@main
struct InterceptorTestApp: App {
    init() {
        NetworkMonitor.shared.startMonitoring()
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
                .kdInspectorOverlay() // Botão de gatilho FLEX estilo arrastável
        }
    }
}

3. Construindo um Menu de Depuração Expansível Personalizado

Se você deseja criar uma página de gatilhos de depuração personalizada em vez do botão global, pode implementar um Floating Action Button (FAB) expansível usando animações de mola:

import SwiftUI
import KDInspector
import NetworkInspector
import ObjectInspector
import DefaultsInspector

struct FloatingActionDemoView: View {
    @State private var isExpanded = false
    @State private var showInspector = false
    @State private var showObjectInspector = false
    @State private var apiCallCount = 0
    @State private var lastActionDescription = "Toque no botão de ação flutuante abaixo para começar."
    @State private var mockState = DemoState()
    struct DemoState {
        var username: String = "kavindu_dissanayake"
        var email: String = "kavindu@example.com"
        var buildVersion: String = "1.0.0-beta.3"
        var deviceModel: String = "iPhone Simulator"
        var themeColor: String = "Indigo"
    }
    var body: some View {
        ZStack {
            Color(.systemGroupedBackground).ignoresSafeArea()
            ScrollView {
                VStack(spacing: 20) {
                    // Cartão de Logs
                    VStack(alignment: .leading, spacing: 8) {
                        Text("ÚLTIMA AÇÃO DE TRACE").font(.caption.bold()).foregroundColor(.indigo)
                        Text(lastActionDescription).font(.subheadline.monospaced()).foregroundColor(.primary)
                    }
                    .padding().background(Color(.secondarySystemGroupedBackground)).cornerRadius(12)
                }
                .padding()
            }
            // Menu Expansível
            floatingMenuOverlay
        }
        .sheet(isPresented: $showInspector) { KDInspectorView() }
        .sheet(isPresented: $showObjectInspector) {
            let props = ObjectReflector().reflect(mockState)
            ObjectInspectorView(properties: props, title: "DemoState Reflection")
        }
    }
    private var floatingMenuOverlay: some View {
        VStack {
            Spacer()
            HStack {
                Spacer()
                ZStack(alignment: .bottomTrailing) {
                    if isExpanded {
                        VStack(spacing: 12) {
                            MenuActionButton(icon: "magnifyingglass", color: .purple, tooltip: "Dashboard") {
                                withAnimation(.spring()) { isExpanded = false }
                                showInspector = true
                            }
                            MenuActionButton(icon: "sparkles", color: .blue, tooltip: "Inspeccionar Estado") {
                                withAnimation(.spring()) { isExpanded = false }
                                showObjectInspector = true
                            }
                        }
                        .padding(.bottom, 72)
                    }
                    Button {
                        withAnimation(.spring(response: 0.4, dampingFraction: 0.75)) { isExpanded.toggle() }
                    } label: {
                        Image(systemName: isExpanded ? "xmark" : "plus")
                            .font(.title2.bold()).foregroundColor(.
Pressione Enter ou clique para ver a imagem em tamanho completo
Adicionando Diagnósticos do Tipo Apple Intelligence: O Investigador AI no Dispositivo
Embora navegar manualmente por solicitações de rede e padrões seja poderoso, eu queria construir uma experiência moderna para desenvolvedores alinhada com os princípios da Apple Intelligence: local, contextual e completamente gratuita.
E se o próprio aplicativo pudesse atuar como um investigador privado no dispositivo, diagnosticando automaticamente rastros de falhas, falhas na rede ou anomalias de layout, e mostrando exatamente as alterações necessárias no código Swift para corrigi-los?
Integrando diretamente o quadro FoundationModels da Apple em nosso painel, construímos um Investigador AI no Dispositivo que roda completamente modelos locais de linguagem (LLMs) nos dispositivos compatíveis (iOS 19.0+ / macOS 16.0+).
Aqui está como o sistema aproveita a inteligência local:
Zero Configuração & Segurança Off-Grid: Não são necessárias chaves de API, credenciais ou tokens de rede. Todos os diagnósticos rodam localmente na hardware do dispositivo, garantindo que logs e payloads sensíveis nunca deixem o sandbox.
Agregação Contextual de Logs: O assistente de diagnóstico extrai dados ativos do depurador (incluindo especificações do dispositivo, bandeiras UserDefaults e uma fatia dos últimos cinco payloads da rede) e os empacota em uma string JSON.
Investigando Falhas de Aplicativo: Usando nosso menu FAB personalizado, adicionamos um gatilho para Simular Falha de Aplicativo. Clicar nele escreve um rastreamento de falha mock opcional-unwrap no UserDefaults (embaixo de "kd_inspector_last_crash") e automaticamente eleva o painel.
Instruções Passo a Passo para Resolução: O AI empacota este contexto, passa-o por um ativo LanguageModelSession no dispositivo e gera um relatório personalizado. Ele identifica que o rastreamento está vindo da ferramenta KD Interceptor, explica a causa raiz da falha, e fornece patches Swift diretos com as etapas exatas que o desenvolvedor deve realizar.
Aqui está a implementação do nosso serviço de diagnóstico:
import Foundation
import NetworkInspector
#if canImport(FoundationModels)
import FoundationModels
#endif

struct FloatingActionDemoView: View {
    @State private var isExpanded = false
    @State private var showInspector = false
    @State private var showObjectInspector = false
    @State private var apiCallCount = 0
    @State private var lastActionDescription = "Tocar no botão de ação flutuante abaixo para começar."
    @State private var mockState = DemoState()
    struct DemoState {
        var username: String = "kavindu_dissanayake"
        var email: String = "kavindu@example.com"
        var buildVersion: String = "1.0.0-beta.3"
        var deviceModel: String = "iPhone Simulator"
        var themeColor: String = "Indigo"
    }
    var body: some View {
        ZStack {
            Color(.systemGroupedBackground).ignoresSafeArea()
            ScrollView {
                VStack(spacing: 20) {
                    // Cartão de Logs
                    VStack(alignment: .leading, spacing: 8) {
                        Text("ÚLTIMA AÇÃO DE TRACE").font(.caption.bold()).foregroundColor(.indigo)
                        Text(lastActionDescription).font(.subheadline.monospaced()).foregroundColor(.primary)
                    }
                    .padding().background(Color(.secondarySystemGroupedBackground)).cornerRadius(12)
                }
                .padding()
            }
            // Menu Expansível
            floatingMenuOverlay
        }
        .sheet(isPresented: $showInspector) { KDInspectorView() }
        .sheet(isPresented: $showObjectInspector) {
            let props = ObjectReflector().reflect(mockState)
            ObjectInspectorView(properties: props, title: "DemoState Reflection")
        }
    }
    private var floatingMenuOverlay: some View {
        VStack {
            Spacer()
            HStack {
                Spacer()
                ZStack(alignment: .bottomTrailing) {
                    if isExpanded {
                        VStack(spacing: 12) {
                            MenuActionButton(icon: "magnifyingglass", color: .purple, tooltip: "Dashboard") {
                                withAnimation(.spring()) { isExpanded = false }
                                showInspector = true
                            }
                            MenuActionButton(icon: "sparkles", color: .blue, tooltip: "Inspeccionar Estado") {
                                withAnimation(.spring()) { isExpanded = false }
                                showObjectInspector = true
                            }
                        }
                        .padding(.bottom, 72)
                    }
                    Button {
                        withAnimation(.spring(response: 0.4, dampingFraction: 0.75)) { isExpanded.toggle() }
                    } label: {
                        Image(systemName: isExpanded ? "xmark" : "plus")
                            .font(.title2.bold()).foregroundColor(.white).frame(width: 56, height: 56)
                            .background(Circle().fill(Color.indigo))
                    }
                }
                .padding(.trailing, 20).padding(.bottom, 20)
            }
        }
    }
}
Pressione Enter ou clique para ver a imagem em tamanho completo
Testando o Kit de Ferramentas de Depuração
Um kit de ferramentas diagnóstico deve ser totalmente confiável. Escrevemos testes usando o novo framework Swift Testing para verificar matemática de layout e reflexão do modelo:
Organização Limpa da Estrutura do Projeto
Para manter a estrutura do projeto de desenvolvimento, dividimos o diretório plano em quatro grupos limpos:
App/: Lógica de inicialização, ativos e configurações do aplicativo.
Demos/: Objetivos de teste dinâmicos, incluindo o menu FAB personalizado.
Components/: Modelos de layout da interface do usuário.
Guides/: Configurações de documentos de caminhos guiados no aplicativo.
Conclusão
Integrar um overlay de depuração no aplicativo remove gargalos na desenvolvimento. Ajuda as equipes de QA a reportar problemas com payloads da rede, ajuda gerentes de produto a verificar preferências locais e permite que você se concentre em codificação ao invés de gerenciar configurações de proxy.
Experimente em seu projeto! O código-fonte do framework está disponível no repositório GitHub KDInspector, e você pode encontrar a implementação completa do demo no repositório GitHub InterceptorTest.