Declarativo vs. Scripted: Escolhendo a Sintaxe do Seu Pipeline Jenkins

O Jenkins Pipeline oferece duas maneiras de escrever um Jenkinsfile: Declarativo e Scripted. Ambos podem construir, testar e implantar sua aplicação, mas eles levam a diferentes trade-offs em legibilidade, validação e flexibilidade do Groovy.

Se sua equipe está escolhendo uma sintaxe para um novo pipeline, comece com o fluxo de trabalho que você precisará manter daqui a seis meses. O Declarativo geralmente é mais fácil de ler e revisar. O Scripted oferece mais controle direto do Groovy quando o pipeline realmente precisa de comportamento dinâmico.

Entendendo os Pipelines Jenkins

Antes de mergulhar nas sintaxes, vamos relembrar brevemente o que é um Pipeline Jenkins. Um Pipeline é um conjunto de plugins que suporta a implementação e integração de pipelines de entrega contínua no Jenkins. É essencialmente uma sequência de etapas automatizadas que definem todo o processo de entrega de software, desde o commit do código até a implantação. Essas etapas são definidas em um Jenkinsfile, tipicamente escrito em Groovy, e oferecem uma maneira poderosa de gerenciar cenários complexos de construção, teste e implantação.

O Jenkins Pipeline as Code oferece várias vantagens principais:

Controle de Versão: O Jenkinsfile é armazenado no controle de origem, assim como o código da aplicação, permitindo versionamento, auditoria e colaboração.
Repetibilidade: Garante a execução consistente do processo de entrega em diferentes ambientes e execuções.
Visibilidade: Fornece uma visão clara e compreensível de todo o processo de entrega.
Durabilidade: Pipelines podem sobreviver a reinicializações do mestre Jenkins.
Extensibilidade: Através de bibliotecas compartilhadas, lógicas complexas podem ser abstraídas e reutilizadas.

Pipelines Declarativos

O Pipeline Declarativo é a sintaxe mais nova e opinativa, projetada para tornar a escrita e compreensão de pipelines mais fáceis. Ele fornece uma abordagem estruturada com blocos predefinidos, o que ajuda as equipes a manterem os Jenkinsfiles consistentes.

Características e Sintaxe

Os Pipelines Declarativos impõem uma estrutura específica definida por blocos de nível superior como pipeline, agent, stages, steps, post, environment, parameters, options, triggers, tools, input e when. Essa estrutura simplifica a definição do pipeline, fornecendo limites claros para diferentes partes do fluxo de trabalho.

Aqui está uma estrutura básica de um Pipeline Declarativo:

pipeline {
    agent any // Ou 'label', 'docker', etc.

    stages {
        stage('Build') {
            steps {
                echo 'Construindo a aplicação...'
                sh 'mvn clean install'
            }
        }
        stage('Test') {
            steps {
                echo 'Executando testes...'
                sh 'mvn test'
            }
        }
        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                echo 'Implantando em produção...'
                script {
                    // Lógica estilo Scripted pode ser colocada aqui se absolutamente necessário
                    // Por exemplo, chamar uma função de biblioteca compartilhada
                    // mySharedLibrary.deployApplication()
                }
            }
        }
    }

    post {
        always {
            echo 'Pipeline finalizado.'
        }
        success {
            echo 'Pipeline bem-sucedido!'
        }
        failure {
            echo 'Pipeline falhou.'
        }
    }
}

Vantagens dos Pipelines Declarativos

Simplicidade e Legibilidade: A estrutura predefinida torna os pipelines fáceis de ler e entender, mesmo para não especialistas. Parece mais um arquivo de configuração.
Abordagem Estruturada: Impõe boas práticas e consistência entre os pipelines, reduzindo a curva de aprendizado e potenciais erros.
Recursos Integrados: Oferece um conjunto rico de recursos integrados para padrões comuns de CI/CD, como execução condicional (when), ações pós-construção (post), execução paralela de estágios e várias opções para gerenciar o fluxo do pipeline.
Mais Fácil de Aprender: Desenvolvedores sem conhecimento extenso de Groovy podem começar rapidamente devido à sua sintaxe opinativa.
Validação: O Jenkins pode validar mais da estrutura antes da execução porque o Declarativo tem regras mais rígidas.

Limitações dos Pipelines Declarativos

Menos Flexível: A estrutura rígida pode ser restritiva para fluxos de trabalho altamente complexos ou dinâmicos que exigem lógica Groovy personalizada fora dos blocos predefinidos.
Acesso Direto Limitado ao Groovy: Embora um bloco script possa ser usado para injetar sintaxe de Pipeline Scripted, o uso excessivo pode prejudicar os benefícios da sintaxe Declarativa e tornar o pipeline mais difícil de ler.

Quando Usar Pipelines Declarativos

Os Pipelines Declarativos são a escolha recomendada para a maioria dos cenários comuns de CI/CD. Eles são ideais para:

Equipes novas no Jenkins ou Pipeline as Code.
Projetos com processos de construção, teste e implantação diretos ou moderadamente complexos.
Garantir consistência e manutenibilidade em muitos pipelines.
Aproveitar os recursos integrados do Jenkins para padrões comuns, como execução paralela, estágios condicionais e notificações.

Pipelines Scripted

O Pipeline Scripted, construído diretamente sobre a linguagem de programação Groovy, foi a sintaxe original para o Jenkins Pipeline as Code. Ele oferece máxima flexibilidade e poder, permitindo que os desenvolvedores implementem fluxos de automação altamente personalizados e dinâmicos.

Características e Sintaxe

Os Pipelines Scripted são executados sequencialmente de cima para baixo, como um script Groovy tradicional. Eles usam a sintaxe completa do Groovy e aproveitam o DSL (Domain Specific Language) do Jenkins Pipeline através de métodos como node, stage, checkout, sh, git, etc. Isso fornece acesso direto à API do Jenkins e todo o poder da linguagem Groovy.

Aqui está uma estrutura básica de um Pipeline Scripted:

node('my-agent-label') {
    stage('Prepare') {
        echo 'Preparando o workspace...'
        checkout scm
    }

    stage('Build') {
        echo 'Construindo a aplicação...'
        try {
            sh 'mvn clean install'
        } catch (err) {
            echo "Falha na construção: ${err}"
            // Tratamento de erro personalizado
            currentBuild.result = 'FAILURE'
            throw err
        }
    }

    stage('Test') {
        echo 'Executando testes...'
        // Determinar dinamicamente as suítes de teste
        def testSuites = sh(script: 'find tests -name "*.test"', returnStdout: true).trim().split('\n')
        if (testSuites.isEmpty()) {
            echo 'Nenhum teste encontrado.'
        } else {
            for (suite in testSuites) {
                echo "Executando suíte de teste: ${suite}"
                sh "./run-test.sh ${suite}"
            }
        }
    }

    stage('Deploy') {
        // Lógica condicional complexa
        if (env.BRANCH_NAME == 'main' && currentBuild.currentResult == 'SUCCESS') {
            echo 'Implantando em produção...'
            sh './deploy-prod.sh'
        } else if (env.BRANCH_NAME == 'develop') {
            echo 'Implantando em staging...'
            sh './deploy-staging.sh'
        } else {
            echo 'Nenhuma implantação para este branch.'
        }
    }

    // Ações pós-construção podem ser implementadas com blocos try-finally ou lógica personalizada
    // Por exemplo, enviar notificações
    if (currentBuild.result == 'SUCCESS') {
        echo 'Pipeline concluído com sucesso!'
        // notifySuccess()
    } else {
        echo 'Pipeline falhou.'
        // notifyFailure()
    }
}

Vantagens dos Pipelines Scripted

Máxima Flexibilidade: Oferece todo o poder do Groovy, permitindo lógica altamente complexa e dinâmica, loops personalizados, tratamento de erros e manipulação de dados.
Acesso Direto à API do Jenkins: Fornece mais espaço para uso das APIs do Jenkins e Groovy, embora algumas operações ainda dependam de plugins, permissões e do sandbox de Segurança de Script.
Comportamento Dinâmico: Ideal para fluxos de trabalho que exigem alocação dinâmica de agentes, execução paralela baseada em condições de tempo de execução ou gerenciamento avançado de recursos.
Extensibilidade: Excelente para criar Bibliotecas Compartilhadas sofisticadas que encapsulam lógica complexa e reutilizável para Pipelines Declarativos.

Limitações dos Pipelines Scripted

Curva de Aprendizado Mais Íngreme: Requer um sólido entendimento de Groovy, o que pode ser uma barreira para equipes não familiarizadas com a linguagem.
Menos Opinativo: Sem uma estrutura estrita, os pipelines podem se tornar inconsistentes e mais difíceis de ler ou manter em diferentes projetos ou desenvolvedores.
Propenso a Erros: A flexibilidade do Groovy significa mais oportunidades para erros de codificação e menos validação integrada em comparação com o Declarativo.
Desafios de Legibilidade: Pipelines Scripted complexos podem rapidamente se tornar difíceis de analisar e entender, dificultando a colaboração e a solução de problemas.
Menos Sintaxe Específica de Pipeline: Muitos padrões comuns de CI/CD (como ações post ou condições when) precisam ser implementados manualmente usando construções Groovy (por exemplo, try-catch-finally, declarações if).

Declarativo vs. Scripted: Uma Comparação Lado a Lado

Para ajudar a resumir as diferenças, aqui está uma tabela comparativa:

Característica	Pipeline Declarativo	Pipeline Scripted
Estrutura da Sintaxe	Opinativa, blocos de nível superior predefinidos.	Flexível, baseada em Groovy, execução sequencial.
Curva de Aprendizado	Mais fácil para iniciantes, menos conhecimento de Groovy necessário.	Mais íngreme, requer expertise em Groovy.
Legibilidade	Alta devido a blocos estruturados e sintaxe clara.	Pode ser baixa para scripts complexos, depende do estilo do desenvolvedor.
Flexibilidade	Limitada a estruturas predefinidas; blocos `script` para Groovy.	Ilimitada, todo o poder do Groovy.
Recursos Integrados	Conjunto rico para padrões comuns de CI/CD (`post`, `when`, `parallel`).	Requer implementação manual usando construções Groovy.
Tratamento de Erros	Blocos `post` para ações globais ou específicas de estágio.	Blocos manuais `try-catch-finally`.
Extensibilidade	Aproveita Bibliotecas Compartilhadas para lógica Groovy complexa.	Escreve lógica Groovy complexa diretamente. Frequentemente cria Bibliotecas Compartilhadas.
Controle de Agente	`agent` global ou `agent` no nível do estágio.	Blocos `node`, pode definir agentes em qualquer lugar.
Casos de Uso	Fluxos de trabalho CI/CD padrão, complexidade simples a moderada.	Fluxos de trabalho altamente dinâmicos, complexos e personalizados; desenvolvimento de Bibliotecas Compartilhadas.
Sensação JSON/YAML	Mais semelhante a linguagens de configuração.	Linguagem de programação pura.

Escolhendo a Sintaxe Correta

Ao decidir entre Pipelines Declarativos e Scripted, considere os seguintes fatores:

Expertise em Groovy da Equipe: Se sua equipe não tem fortes habilidades em Groovy, o Declarativo terá uma curva de aprendizado muito mais suave e promoverá uma adoção mais rápida.
Complexidade do Fluxo de Trabalho: Para a maioria dos fluxos de trabalho CI/CD padrão (construir, testar, implantar), o Declarativo é perfeitamente adequado e muitas vezes superior devido à sua legibilidade e recursos integrados. Para tarefas altamente dinâmicas, condicionais ou intensivas em recursos personalizados, o Scripted pode ser necessário.
Manutenibilidade e Legibilidade: Pipelines Declarativos são geralmente mais fáceis de ler e manter, especialmente para grandes organizações com muitos pipelines e desenvolvedores. Essa consistência reduz a carga cognitiva.
Ecossistema de Pipeline Existente: Se você tem Pipelines Scripted existentes ou um conjunto robusto de Bibliotecas Compartilhadas construídas com sintaxe Scripted, pode optar por mantê-lo para consistência, ou migrar progressivamente para o Declarativo quando apropriado.
Crescimento Futuro: Pipelines Declarativos são geralmente suficientes e podem ser estendidos com lógica personalizada através de Bibliotecas Compartilhadas, que por si só são tipicamente escritas em Groovy Scripted. Esta é frequentemente a melhor abordagem híbrida.

Melhores Práticas para Tomada de Decisão

Comece com Declarativo: Para novos pipelines, opte pelo Declarativo por padrão. Ele cobre a grande maioria dos casos de uso de CI/CD e promove consistência e legibilidade.
Aproveite Bibliotecas Compartilhadas: Quando encontrar lógica repetitiva ou complexa em seus Pipelines Declarativos, abstraia essa lógica em uma Biblioteca Compartilhada. Bibliotecas Compartilhadas são escritas principalmente em Groovy Scripted, permitindo combinar o melhor dos dois mundos: a estrutura do Declarativo e a flexibilidade do Scripted.
Evite Excesso de Script no Declarativo: Embora o Declarativo permita blocos script, tente mantê-los mínimos. Se um bloco script se tornar muito grande ou complexo, é um forte indicador de que a lógica deve ser movida para uma função de Biblioteca Compartilhada.
Considere a Migração: Se você tem Pipelines Scripted legados que estão se tornando difíceis de manter, considere refatorá-los para a sintaxe Declarativa, movendo partes complexas para Bibliotecas Compartilhadas.

Conclusão

Para novos Jenkinsfiles, escolha o Declarativo a menos que você tenha um motivo concreto para não fazê-lo. Mova Groovy repetido ou complexo para Bibliotecas Compartilhadas e reserve pipelines totalmente Scripted para fluxos de trabalho que não se encaixam claramente em estágios, condições e etapas Declarativas.