Boas Práticas de Linting YAML: Detete Erros Antes de Implementar

Um espaço mal colocado num ficheiro YAML pode derrubar uma implementação em produção. Ao contrário do JSON, que falha ruidosamente em erros de sintaxe, o YAML pode silenciosamente analisar indentação incorreta em estruturas de dados inesperadas. O linting deteta estes problemas antes de chegarem a produção.

Porquê Fazer Linting de YAML?

A flexibilidade do YAML é simultaneamente a sua força e fraqueza:

# Isto é YAML válido mas provavelmente está errado
ports:
  - 80
  - 443
  name: webserver  # Esta é uma chave no SEGUNDO item da lista, não no mapeamento!

O exemplo acima cria uma lista onde o segundo item é um mapeamento {443: null, name: webserver}. Um linter detetaria este problema de indentação. Sem linting, este tipo de erro pode levar horas a diagnosticar.

yamllint: O Linter Padrão

O yamllint é o linter de YAML mais amplamente utilizado. Verifica tanto a validade da sintaxe como a consistência de estilo.

Instalação

pip install yamllint

Utilização Básica

# Lint de um único ficheiro
yamllint config.yaml

# Lint de um diretório
yamllint .

# Lint com uma configuração específica
yamllint -c .yamllint.yml .

Configuração

Crie .yamllint.yml na raiz do seu projeto:

extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
    indent-sequences: true
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments:
    require-starting-space: true
    min-spaces-from-content: 2
  document-start: disable
  empty-lines:
    max: 1

Regras Principais Explicadas

Erros Comuns Detetados pelo Linting

1. Caracteres de Tabulação

O YAML proíbe tabs para indentação, mas os editores por vezes inserem-nos:

# ERRO: carácter de tabulação
server:
port: 8080  # Tab em vez de espaços!

2. Indentação Inconsistente

# ERRO: mistura de indentação de 2 e 4 espaços
database:
  host: localhost
    port: 5432  # Errado: 4 espaços em vez de 2

3. Chaves Duplicadas

# ERRO: chave duplicada (a segunda sobrepõe silenciosamente a primeira)
server:
  port: 8080
  host: localhost
  port: 9090  # Duplicada! Qual porta é utilizada?

4. Espaços Finais

Espaços finais invisíveis podem causar comportamento surpreendente, especialmente em strings multilinha. Um linter sinaliza-os imediatamente.

Validação rápida sem instalar nada: cole o seu YAML no nosso Validador YAML.

Integração CI/CD

GitHub Actions

name: YAML Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint YAML files
        run: yamllint .

Hook de Pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.33.0
    hooks:
      - id: yamllint
        args: [-c, .yamllint.yml]

pip install pre-commit
pre-commit install

Agora o YAML é automaticamente verificado pelo linter antes de cada commit.

GitLab CI

yaml-lint:
  image: python:3.12-slim
  script:
    - pip install yamllint
    - yamllint .
  rules:
    - changes:
        - "**/*.yaml"
        - "**/*.yml"

Integração com Editores

A maioria dos editores suporta linting de YAML em tempo real:

• VS Code: Instale a extensão "YAML" da Red Hat (utiliza yamllint)
• Vim/Neovim: Utilize ALE ou coc-yaml
• IDEs JetBrains: Suporte YAML integrado com inspeções configuráveis

Ative a formatação automática ao guardar para ficheiros YAML para corrigir automaticamente problemas de espaços em branco.

Linting Específico por Ferramenta

O linting genérico de YAML deteta erros de sintaxe, mas linters específicos por ferramenta validam a correção semântica:

Kubernetes

# kubeval - validar contra esquemas K8s
kubeval deployment.yaml

# kubeconform - alternativa mais rápida
kubeconform -strict deployment.yaml

Docker Compose

docker compose config --quiet

GitHub Actions

# actionlint - valida a sintaxe de workflows
actionlint .github/workflows/*.yml

Ansible

ansible-lint playbook.yml

Para uma compreensão mais profunda das regras de sintaxe YAML, consulte o nosso tutorial de sintaxe YAML.

Resumo de Boas Práticas

1. Adicione yamllint ao CI — Cada alteração de YAML deve passar pelo linting
2. Utilize hooks de pre-commit — Detete erros antes de chegarem ao repositório
3. Padronize a indentação de 2 espaços — A convenção DevOps
4. Desative a regra truthy ou restrinja-a — O problema dos booleanos yes/no causa erros reais
5. Defina um comprimento de linha razoável — 120 caracteres cobre a maioria dos casos
6. Utilize validadores específicos por ferramenta — Linting genérico mais validação específica para K8s/Docker/Actions
7. Configure o seu editor — Feedback em tempo real é mais rápido do que falhas de CI

FAQ

Devo utilizar YAML ou JSON para ficheiros de configuração?

O YAML é preferido para ficheiros de configuração editados por humanos devido à sua legibilidade, suporte a comentários e sintaxe concisa. O JSON é melhor para dados gerados por máquina e comunicação por API. Para uma comparação detalhada, consulte o nosso guia YAML vs JSON.

Como devo lidar com avisos vs erros do yamllint?

Configure regras críticas (indentação, sintaxe) como erros que bloqueiam o CI. Defina regras de estilo (comprimento de linha, comentários) como avisos que aparecem mas não bloqueiam. Isto equilibra o rigor com a produtividade do programador.

Recursos Relacionados

• Validador YAML — Valide a sintaxe YAML online instantaneamente
• Tutorial de Sintaxe YAML — Aprenda YAML do zero
• YAML para Docker Compose — Padrões YAML específicos do Docker