容器与云原生 / 系统课时
变量没配置时怎样提供默认值
变量没配置时怎样提供默认值
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 可以直接验证两类行为:
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 没有默认值,因为缺失令牌时继续启动通常只会把问题推迟到应用运行阶段。
给必填变量一个值并启动:
APP_ENV= WORKER_COUNT= API_TOKEN=demo-token docker compose run --rm app预期输出:
APP_ENV=development
WORKER_COUNT=2
TOKEN_SET=yes命令显式把 APP_ENV 与 WORKER_COUNT 设为空字符串;因为这里使用 :-,两者都会回退到默认值,因此输出可以稳定复现。
让错误发生在容器启动之前
必填表达式的价值在于 Compose 解析配置时就能拒绝缺失值,而不是先创建容器再等待应用报错。直接执行配置解析即可检查:
API_TOKEN= docker compose config预期结果:
命令退出非 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])