Sourcery para Swift: Guia Completo de Geração de Código

1. O que é e para que serve?

Sourcery é uma ferramenta poderosa de geração de código para a linguagem Swift, criada por Krzysztof Zabłocki e sua equipe. Ela permite gerar automaticamente código boilerplate com base em anotações e na estrutura dos seus arquivos fonte. Em vez de escrever manualmente implementações repetitivas de protocolos como Equatable, Hashable, Codable, mocks para testes ou código para Auto Layout, você descreve as regras de geração uma única vez, e o Sourcery faz o resto.

Por que usar isso? Em projetos reais em Swift, uma parte significativa do código é mecânica e repetitiva. Isso não só consome tempo do desenvolvedor, mas também é uma fonte de erros: esqueceu de adicionar um novo campo no Equatable? Pronto, surgiu um bug. O Sourcery resolve esse problema assumindo o trabalho braçal. Ele analisa seu código (AST — árvore sintática abstrata) e, com base em templates (Stencil ou baseados em Swift), gera novos arquivos. Isso é especialmente útil em projetos grandes com dezenas ou centenas de modelos, ViewControllers ou serviços.

O Sourcery não é uma biblioteca em tempo de execução — é uma ferramenta de tempo de compilação. Você o executa como parte do processo de build (via Build Phase no Xcode ou via SPM/Tuist), ele gera os arquivos, e então esses arquivos são compilados junto com o resto do código. Essa abordagem garante zero overhead em runtime e total previsibilidade.

2. Instalação

Existem várias formas de instalar o Sourcery. A mais simples e recomendada é via Homebrew:

brew install sourcery

Para projetos que usam Swift Package Manager (SPM), é possível adicionar o Sourcery como um plugin. No entanto, o mais comum é usá-lo como um binário separado, chamado a partir de um script de build. Para instalar via Mint (gerenciador de pacotes para ferramentas Swift):

mint install krzysztofzablocki/Sourcery

Você também pode baixar o binário pronto diretamente do GitHub Releases e colocá-lo na pasta do projeto. Após a instalação, verifique se o comando está disponível:

sourcery --version

3. Início Rápido — Exemplo Mínimo Funcional

Vamos criar um exemplo simples: geração automática da implementação do protocolo Equatable para uma struct.

Passo 1: Crie um arquivo com o código fonte (exemplo: Sources/Models/User.swift):

import Foundation

// sourcery: AutoEquatable
struct User {
    let id: Int
    let name: String
    let email: String
}

Observe o comentário // sourcery: AutoEquatable — esta é uma anotação que instrui o Sourcery a gerar a implementação do Equatable para esta struct.

Passo 2: Crie um template (exemplo: Templates/AutoEquatable.stencil):

// Generated by Sourcery
// swiftlint:disable all

{% for type in types.all where type.annotations.AutoEquatable %}
extension {{ type.name }}: Equatable {
    static func == (lhs: {{ type.name }}, rhs: {{ type.name }}) -> Bool {
        {% for variable in type.storedVariables %}
        {% if not forloop.first %} && {% endif %}lhs.{{ variable.name }} == rhs.{{ variable.name }}
        {% endfor %}
    }
}
{% endfor %}

Passo 3: Execute o Sourcery:

sourcery --sources Sources/Models --templates Templates --output Generated

Passo 4: Resultado — na pasta Generated será criado o arquivo AutoEquatable.generated.swift:

// Generated by Sourcery
// swiftlint:disable all

extension User: Equatable