【通用常识】YAML 中的高阶语法

说明：YAML 中用于锚点（Anchor）、合并（Merge）和引用（Reference）的特殊语法。主要用来做配置参数服用和组装

在java中可以直接映射过来用

java 复制代码

@Configuration
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    private String version;
    // getters and setters
}

应用代码

yaml 复制代码

# 定义锚点
base_config: &defaults
  environment: production
  timeout: 30s
  retries: 3

# 第一次引用 defaults
service_a:
  <<: *defaults
  host: service-a.example.com

# 第二次引用 defaults
service_b:
  <<: *defaults
  host: service-b.example.com
  timeout: 60s  # 覆盖默认值

# 第三次引用 defaults（完全独立的位置）
monitoring:
  <<: *defaults
  purpose: health-check
  interval: 10s

解析结果

yaml 复制代码

service_a:
  environment: production
  timeout: 30s
  retries: 3
  host: service-a.example.com

service_b:
  environment: production
  timeout: 60s
  retries: 3
  host: service-b.example.com

monitoring:
  environment: production
  timeout: 30s
  retries: 3
  purpose: health-check
  interval: 10s

共享通用配置（环境变量、网络、卷等） docker-compose.yaml

yaml 复制代码

version: '3.8'

x-common-env: &common-env
  environment:
    NODE_ENV: production
    TZ: Asia/Shanghai
    LOG_LEVEL: info

x-common-config: &common-config
  restart: unless-stopped
  networks:
    - app-network
  volumes:
    - ./logs:/app/logs
  logging:
    driver: "json-file"
    options:
      max-size: "10m"
      max-file: "3"

services:
  web:
    image: nginx:alpine
    <<: *common-config
    environment:
      <<: *common-env
      PORT: 80
    ports:
      - "80:80"

  api:
    image: my-api:latest
    <<: *common-config
    environment:
      <<: *common-env
      DATABASE_URL: postgres://db:5432/myapp
    ports:
      - "3000:3000"

  worker:
    image: my-worker:latest
    <<: *common-config
    environment:
      <<: *common-env
      QUEUE_NAME: tasks
    depends_on:
      - redis

networks:
  app-network:
    driver: bridge

共享环境变量（支持合并）

yaml 复制代码

x-env-base: &env-base
  DATABASE_HOST: db
  REDIS_URL: redis://redis:6379

x-env-prod: &env-prod
  <<: *env-base
  NODE_ENV: production
  API_KEY: ${PROD_API_KEY}

x-env-dev: &env-dev
  <<: *env-base
  NODE_ENV: development
  DEBUG: true

services:
  api-prod:
    image: myapp:latest
    environment: *env-prod

  api-dev:
    image: myapp:latest
    environment: *env-dev

共享卷挂载或部署配置（Swarm 模式）

yaml 复制代码

x-volumes: &app-volumes
  volumes:
    - static-data:/var/www/html
    - logs:/var/log/app

x-deploy: &common-deploy
  deploy:
    replicas: 3
    update_config:
      parallelism: 2
      delay: 10s
    restart_policy:
      condition: on-failure

services:
  frontend:
    image: nginx
    <<: *app-volumes
    <<: *common-deploy
    ports:
      - "80:80"

  backend:
    image: app:latest
    <<: *app-volumes
    <<: *common-deploy
    environment:
      - ENV=prod

使用 x- 前缀定义自定义锚点（官方推荐）

Docker Compose 支持以 x- 开头的自定义字段，这些字段不会被解析为服务，仅用于组织配置。

yaml 复制代码

x-defaults: &defaults
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"

x-monitoring: &monitoring
  environment:
    MONITORING: "true"
    AGENT_HOST: host.docker.internal

services:
  web:
    image: nginx
    <<: *defaults
    <<: *monitoring
    ports:
      - "80:80"

使用误区

❌ 错误：在列表中使用 <<

yaml 复制代码

# 错误！ports 是列表，不能用 <<
ports:
  <<: *some-map   # ❌ 无效
  - "80:80"

❌ 错误：引用未定义的锚点

yaml 复制代码

# 错误！ports 是列表，不能用 <<
ports:
  <<: *some-map   # ❌ 无效
  - "80:80"

❌ 错误：先引用后定义

yaml 复制代码

service:
  environment: *env
  # ... 其他内容
env: &env    # 锚点定义在后面 ❌ 某些解析器不支持
  KEY: value

理想结构

yaml 复制代码

# docker-compose.yml
x-env: &env
  environment:
    TZ: Asia/Shanghai

x-base: &base
  restart: unless-stopped
  networks:
    - app

x-app: &app
  <<: *base
  <<: *env
  volumes:
    - logs:/var/log

services:
  web: <<: *app
  api: <<: *app
  worker: <<: *app

networks:
  app: driver: bridge
volumes:
  logs: