Anchor e Alias YAML: Pattern di Configurazione DRY

Ripetere la stessa configurazione in più sezioni di un file YAML viola il principio DRY (Don't Repeat Yourself) e crea problemi di manutenzione. Gli anchor e alias YAML risolvono questo problema permettendo di definire un valore una volta e referenziarlo più volte.

Sintassi di Base

Anchor (&): Segna un valore per il riutilizzo Alias (*): Referenzia un valore ancorato

# Definisci un anchor
defaults: &default_settings
  timeout: 30
  retries: 3
  log_level: info

# Usa gli alias per referenziarlo
development:
  <<: *default_settings
  log_level: debug

production:
  <<: *default_settings
  retries: 5

La merge key << incorpora tutte le coppie chiave-valore dall'anchor referenziato. Le proprietà definite dopo il merge sovrascrivono i valori ancorati.

Risultato dopo la risoluzione:

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

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

Tipi di Anchor

Anchor Scalari

Riutilizza un singolo valore:

max_connections: &max_conn 100

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

Anchor di Sequenza

Riutilizza intere liste:

common_ports: &ports
  - 80
  - 443

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

Anchor di Mapping

Riutilizza interi oggetti (il pattern più comune):

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

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

La Merge Key (<<)

La merge key ha un comportamento specifico:

1. Copia tutte le coppie chiave-valore dal mapping referenziato
2. Le chiavi impostate esplicitamente hanno priorità sulle chiavi fuse
3. I merge multipli vengono elaborati in ordine (il primo vince per i conflitti)

# Merge multipli
base: &base
  a: 1
  b: 2

extra: &extra
  b: 3
  c: 4

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

Esempi Reali

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

Docker Compose usa la convenzione del prefisso x- per i campi di estensione che contengono anchor. Vedi la nostra guida YAML per Docker Compose per altri pattern.

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  # Stessi limiti di risorse

Limitazioni e Insidie

1. Nessun Riferimento tra File

Gli anchor funzionano solo all'interno di un singolo file YAML. Non puoi referenziare un anchor definito in un altro file. Per il riutilizzo tra file, usa strumenti di templating come Helm, Jsonnet o Kustomize.

2. Nessun Override Parziale nelle Sequenze

Non puoi fondere e sovrascrivere parzialmente una lista — sostituisci l'intera lista:

base_ports: &ports
  - 80
  - 443

service:
  ports: *ports  # Ottieni esattamente [80, 443]
  # Non puoi aggiungere la porta 8080 a questa lista tramite merge

Soluzione alternativa: Definisci la lista estesa separatamente.

3. L'Ordine è Importante

Gli anchor devono essere definiti prima di essere referenziati:

# SBAGLIATO - alias prima dell'anchor
service:
  settings: *defaults

defaults: &defaults
  timeout: 30

# CORRETTO - anchor prima dell'alias
defaults: &defaults
  timeout: 30

service:
  settings: *defaults

4. Non Tutti gli Strumenti Supportano le Merge Key

La merge key << non fa parte della specifica core YAML — è un'estensione specifica per tipo. La maggior parte dei parser YAML popolari la supporta, ma alcuni parser rigorosi potrebbero non farlo.

Valida l'uso dei tuoi anchor YAML con il nostro Validatore YAML.

FAQ

Gli anchor vengono preservati durante la conversione da YAML a JSON?

No. Quando il YAML viene analizzato, anchor e alias vengono risolti nei loro valori. Il JSON risultante avrà i valori espansi inline. Questo significa che convertire in JSON e tornare indietro perderà la struttura DRY. Gli anchor esistono solo nel formato sorgente YAML.

Posso usare gli anchor con override annidati complessi?

La merge key (<<) esegue solo un merge superficiale — copia le chiavi di primo livello dal mapping ancorato. Gli oggetti annidati vengono sostituiti interamente, non fusi in profondità. Per il comportamento di deep merge, serve una soluzione specifica per lo strumento (funzione merge di Helm, processori YAML personalizzati).

Risorse Correlate

• Validatore YAML — Valida YAML con anchor e alias
• Tutorial Sintassi YAML — Fondamenti YAML
• YAML per Docker Compose — Pattern specifici per Docker