Âncoras e Aliases YAML: Padrões de Configuração DRY

Repetir a mesma configuração em múltiplas secções de um ficheiro YAML viola o princípio DRY (Don't Repeat Yourself) e cria dores de cabeça de manutenção. As âncoras e aliases YAML resolvem este problema, permitindo-lhe definir um valor uma vez e referenciá-lo múltiplas vezes.

Sintaxe Básica

Âncora (&): Marca um valor para reutilização Alias (*): Referencia um valor ancorado

# Definir uma âncora
defaults: &default_settings
  timeout: 30
  retries: 3
  log_level: info

# Utilizar aliases para referenciá-la
development:
  <<: *default_settings
  log_level: debug

production:
  <<: *default_settings
  retries: 5

A chave de fusão << incorpora todos os pares chave-valor da âncora referenciada. As propriedades definidas após a fusão sobrepõem os valores ancorados.

Resultado após resolução:

development:
  timeout: 30
  retries: 3
  log_level: debug  # sobreposto

production:
  timeout: 30
  retries: 5        # sobreposto
  log_level: info

Tipos de Âncoras

Âncoras Escalares

Reutilize um valor único:

max_connections: &max_conn 100

database:
  pool_size: *max_conn
cache:
  pool_size: *max_conn

Âncoras de Sequência

Reutilize listas inteiras:

common_ports: &ports
  - 80
  - 443

web_server:
  ports: *ports
load_balancer:
  ports: *ports

Âncoras de Mapeamento

Reutilize objetos inteiros (o padrão mais comum):

logging: &log_config
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  api:
    logging: *log_config
  worker:
    logging: *log_config

A Chave de Fusão (<<)

A chave de fusão tem um comportamento específico:

1. Copia todos os pares chave-valor do mapeamento referenciado
2. As chaves explicitamente definidas têm prioridade sobre as chaves fundidas
3. Múltiplas fusões são processadas por ordem (a primeira ganha em caso de conflito)

# Múltiplas fusões
base: &base
  a: 1
  b: 2

extra: &extra
  b: 3
  c: 4

combined:
  <<: [*base, *extra]
  # Resultado: a=1, b=2 (base ganha), c=4

Exemplos do Mundo Real

Docker Compose

x-common: &common
  restart: unless-stopped
  networks:
    - app-network
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  api:
    <<: *common
    image: myapp/api:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://db:5432/myapp

  worker:
    <<: *common
    image: myapp/worker:latest
    environment:
      QUEUE_URL: redis://cache:6379

  scheduler:
    <<: *common
    image: myapp/scheduler:latest

O Docker Compose utiliza a convenção de prefixo x- para campos de extensão que contêm âncoras. Consulte o nosso guia YAML para Docker Compose para mais padrões.

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    env: &common_env
      NODE_VERSION: '20'
      CI: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: test
    env:
      <<: *common_env
      BUILD_TARGET: production
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

Kubernetes

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          resources: &resources
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
        - name: sidecar
          resources: *resources  # Mesmos limites de recursos

Limitações e Armadilhas

1. Sem Referências Entre Ficheiros

As âncoras funcionam apenas dentro de um único ficheiro YAML. Não é possível referenciar uma âncora definida noutro ficheiro. Para reutilização entre ficheiros, utilize ferramentas de template como Helm, Jsonnet ou Kustomize.

2. Sem Sobreposições Parciais em Sequências

Não é possível fundir e sobrepor parcialmente uma lista — substitui-se a lista inteira:

base_ports: &ports
  - 80
  - 443

service:
  ports: *ports  # Obtém exatamente [80, 443]
  # Não é possível adicionar a porta 8080 a esta lista via fusão

Solução alternativa: Defina a lista estendida separadamente.

3. A Ordem Importa

As âncoras devem ser definidas antes de serem referenciadas:

# ERRADO - alias antes da âncora
service:
  settings: *defaults

defaults: &defaults
  timeout: 30

# CORRETO - âncora antes do alias
defaults: &defaults
  timeout: 30

service:
  settings: *defaults

4. Nem Todas as Ferramentas Suportam Chaves de Fusão

A chave de fusão << não faz parte da especificação central do YAML — é uma extensão específica de tipo. A maioria dos analisadores YAML populares suporta-a, mas alguns analisadores rigorosos podem não a suportar.

Valide a sua utilização de âncoras YAML com o nosso Validador YAML.

FAQ

As âncoras são preservadas ao converter YAML para JSON?

Não. Quando o YAML é analisado, as âncoras e aliases são resolvidos nos seus valores. O JSON resultante terá os valores expandidos em linha. Isto significa que converter para JSON e de volta perderá a estrutura DRY. As âncoras existem apenas no formato de origem YAML.

Posso utilizar âncoras com sobreposições aninhadas complexas?

A chave de fusão (<<) realiza apenas uma fusão superficial — copia as chaves de nível superior do mapeamento ancorado. Os objetos aninhados são substituídos inteiramente, não fundidos em profundidade. Para comportamento de fusão profunda, necessita de uma solução específica da ferramenta (função merge do Helm, processadores YAML personalizados).

Recursos Relacionados

• Validador YAML — Valide YAML com âncoras e aliases
• Tutorial de Sintaxe YAML — Fundamentos de YAML
• YAML para Docker Compose — Padrões específicos do Docker