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

Repetir a mesma configuração em múltiplas seções de um arquivo YAML viola o princípio DRY (Don't Repeat Yourself) e cria dores de cabeça na manutenção. Âncoras e aliases YAML resolvem isso permitindo que você defina um valor uma vez e o referencie 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

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

production:
  <<: *default_settings
  retries: 5

A chave de merge << incorpora todos os pares chave-valor da âncora referenciada. Propriedades definidas após o merge sobrescrevem os valores ancorados.

Resultado após resolução:

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

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

Tipos de Âncora

Âncoras Escalares

Reutilize um único valor:

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 Merge (`<<`)

A chave de merge tem um comportamento específico:

Ela copia todos os pares chave-valor do mapeamento referenciado
Chaves definidas explicitamente têm prioridade sobre as chaves mescladas
Múltiplos merges são processados em ordem (o primeiro vence em conflitos)

# Múltiplos merges
base: &base
  a: 1
  b: 2

extra: &extra
  b: 3
  c: 4

combined:
  <<: [*base, *extra]
  # Resultado: a=1, b=2 (base vence), 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 usa a convenção de prefixo x- para campos de extensão que contêm âncoras. Veja 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 Arquivos

Âncoras funcionam apenas dentro de um único arquivo YAML. Você não pode referenciar uma âncora definida em outro arquivo. Para reutilização entre arquivos, use ferramentas de templates como Helm, Jsonnet ou Kustomize.

2. Sem Sobrescritas Parciais em Sequências

Você não pode fazer merge e sobrescrever parcialmente uma lista — você substitui a lista inteira:

base_ports: &ports
  - 80
  - 443

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

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

3. A Ordem Importa

Â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 Merge

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

Valide o uso de âncoras YAML com nosso Validador YAML.

FAQ

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

Não. Quando o YAML é interpretado, âncoras e aliases são resolvidos em seus valores. O JSON resultante terá os valores expandidos inline. Isso significa que converter para JSON e voltar perderá a estrutura DRY. As âncoras existem apenas no formato fonte YAML.

Posso usar âncoras com sobrescritas aninhadas complexas?

A chave de merge (<<) realiza apenas um merge superficial — ela copia as chaves de nível superior do mapeamento ancorado. Objetos aninhados são substituídos inteiramente, sem merge profundo. Para comportamento de merge profundo, você precisa de uma solução específica da ferramenta (função merge do Helm, processadores YAML customizados).

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 para Docker