容器与云原生 / 系统课时

变量没配置时怎样提供默认值

变量没配置时怎样提供默认值

Compose 文件经常需要在“开发环境可省略”和“生产参数必须显式提供”之间取得平衡。本课用默认值与必填校验表达这两种意图,并验证变量为空和完全未设置时的差异。

学习目标

  • 能使用 ${VAR:-default} 与 ${VAR-default} 设置默认值
  • 能使用 ${VAR:?message} 与 ${VAR?message} 对缺失变量做必填校验
  • 能在容器启动前验证插值结果,避免配置缺失后才进入应用排错

默认值与必填校验的四种写法

Docker Compose 使用类似 shell 的变量插值语法。带冒号的形式会把“未设置”和“空字符串”都视为缺失;不带冒号的形式只判断变量是否存在。官方 Compose 插值规范列出了这四种语义。([Docker Documentation][4])

写法 变量未设置 变量为空字符串
${VAR:-default} 使用 default 使用 default
${VAR-default} 使用 default 保留空字符串
${VAR:?message} 报错 报错
${VAR?message} 报错 接受空字符串

大多数应用参数更适合带冒号的写法,因为空字符串通常和缺失一样不可用。例如开发环境可以给 APP_ENV、WORKER_COUNT 默认值,而访问令牌必须提供。

在 Compose 中组合默认值和必填值

下面的 compose.yaml 可以直接验证两类行为:

yaml
services:
  app:
    image: alpine:3.20
    environment:
      APP_ENV: "${APP_ENV:-development}"
      WORKER_COUNT: "${WORKER_COUNT:-2}"
      API_TOKEN: "${API_TOKEN:?API_TOKEN must be set}"
    command:
      - sh
      - -c
      - |
        if [ -n "$$API_TOKEN" ]; then TOKEN_SET=yes; else TOKEN_SET=no; fi
        printf 'APP_ENV=%s\nWORKER_COUNT=%s\nTOKEN_SET=%s\n' "$$APP_ENV" "$$WORKER_COUNT" "$$TOKEN_SET"

APP_ENV 与 WORKER_COUNT 在没有外部配置时使用安全的开发默认值;API_TOKEN 没有默认值,因为缺失令牌时继续启动通常只会把问题推迟到应用运行阶段。

给必填变量一个值并启动:

bash
APP_ENV= WORKER_COUNT= API_TOKEN=demo-token docker compose run --rm app

预期输出:

text
APP_ENV=development
WORKER_COUNT=2
TOKEN_SET=yes

命令显式把 APP_ENV 与 WORKER_COUNT 设为空字符串;因为这里使用 :-,两者都会回退到默认值,因此输出可以稳定复现。

让错误发生在容器启动之前

必填表达式的价值在于 Compose 解析配置时就能拒绝缺失值,而不是先创建容器再等待应用报错。直接执行配置解析即可检查:

bash
API_TOKEN= docker compose config

预期结果:

text
命令退出非 0,错误信息包含:API_TOKEN must be set

不同 Compose 版本的错误前缀可能不同,但自定义消息 API_TOKEN must be set 应出现在报错中。${VAR:?message} 会在变量未设置或为空时失败;若业务允许空字符串,则改用 ${VAR?message}。([Docker Documentation][4])

选择默认值还是强制必填

默认值适合有明确安全退路的参数,例如本地日志级别、开发环境名称或非关键并发数。必填校验适合没有合理默认值且缺失会导致错误连接、数据写错位置或鉴权失败的参数,例如生产数据库地址、外部服务租户标识和必要令牌。

还要注意,普通 ${VAR} 在无法解析且没有默认值时,Compose 会给出警告并用空字符串替代;对关键配置来说,这种行为通常不够严格。需要强约束时,优先写成 ${VAR:?message},让错误尽量靠近配置入口。([Docker Documentation][4])

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

变量没配置时怎样提供默认值

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通