命令行与文本处理 / 系统课时

分离配置与运行环境

分离配置与运行环境

把路径、端点和功能开关写死在脚本中,会导致开发、测试和生产环境只能靠改代码切换。本课将建立配置加载与覆盖规则,让脚本从 JSON 文件读取非敏感配置,从环境变量读取部署差异和凭据,并在启动时完成校验。

学习目标

  • 区分可提交配置、环境差异与敏感凭据
  • 实现“配置文件加环境变量”的参数注入
  • 建立明确的覆盖优先级和启动校验

划分配置边界

配置文件适合保存端点默认值、相对路径、超时和功能开关,并可随代码进行版本管理。环境变量适合注入容器、计划任务或 CI/CD 环境中的差异值。令牌和密码不应写入配置文件,配置中只保存其环境变量名称。

推荐采用以下优先级:命令行参数高于环境变量,环境变量高于配置文件,配置文件高于代码默认值。优先级必须固定并写入文档,否则同一个参数在不同机器上可能得到不同解释。

PowerShell 配置注入与覆盖优先级图

准备环境配置文件

以下 settings.json 只保存可公开的运行参数。tokenEnvironmentVariable 是凭据引用,不是令牌本身。

json
{
  "endpoint": "https://api.example.internal",
  "outputPath": "./out",
  "timeoutSeconds": 20,
  "features": {
    "enableArchive": false
  },
  "credentials": {
    "tokenEnvironmentVariable": "APP_API_TOKEN"
  }
}

该文件生效后,脚本仍允许使用 APP_ENDPOINT、APP_OUTPUT_PATH 和 APP_ENABLE_ARCHIVE 覆盖对应值。真实令牌由 APP_API_TOKEN 提供,不进入仓库。

实现加载、覆盖与校验

将下面脚本保存为 run.ps1,并与 settings.json 放在同一目录。脚本先读取 JSON,再应用环境变量覆盖,最后校验端点、超时和凭据是否有效。

powershell
[CmdletBinding()]
param(
    [string]$ConfigPath = (Join-Path $PSScriptRoot 'settings.json')
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

function ConvertTo-Boolean {
    param(
        [Parameter(Mandatory)]
        [string]$Value,

        [Parameter(Mandatory)]
        [string]$Name
    )

    $parsed = $false
    if (-not [bool]::TryParse($Value, [ref]$parsed)) {
        throw "环境变量 $Name 必须是 true 或 false。"
    }

    return $parsed
}

if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) {
    throw "找不到配置文件:$ConfigPath"
}

$configDirectory = Split-Path -Parent (Resolve-Path -LiteralPath $ConfigPath)
$config = Get-Content -LiteralPath $ConfigPath -Raw |
    ConvertFrom-Json

# 环境变量只覆盖已定义的部署差异,不改变配置结构。
$endpoint = if ($env:APP_ENDPOINT) {
    $env:APP_ENDPOINT
}
else {
    $config.endpoint
}

$outputPathValue = if ($env:APP_OUTPUT_PATH) {
    $env:APP_OUTPUT_PATH
}
else {
    $config.outputPath
}

$enableArchive = if ($env:APP_ENABLE_ARCHIVE) {
    ConvertTo-Boolean -Value $env:APP_ENABLE_ARCHIVE `
        -Name 'APP_ENABLE_ARCHIVE'
}
else {
    [bool]$config.features.enableArchive
}

$tokenVariableName = [string]$config.credentials.tokenEnvironmentVariable
$token = [Environment]::GetEnvironmentVariable($tokenVariableName)

$endpointUri = $null
if (-not [Uri]::TryCreate($endpoint, [UriKind]::Absolute, [ref]$endpointUri) -or
    $endpointUri.Scheme -notin @('http', 'https')) {
    throw 'endpoint 必须是绝对 HTTP 或 HTTPS 地址。'
}

if ([int]$config.timeoutSeconds -le 0) {
    throw 'timeoutSeconds 必须大于 0。'
}

if ([string]::IsNullOrWhiteSpace($token)) {
    throw "未设置凭据环境变量:$tokenVariableName"
}

$outputPath = if ([IO.Path]::IsPathRooted($outputPathValue)) {
    [IO.Path]::GetFullPath($outputPathValue)
}
else {
    [IO.Path]::GetFullPath(
        (Join-Path $configDirectory $outputPathValue)
    )
}

# 只输出脱敏后的统一配置对象,业务代码无需知道参数来源。
[pscustomobject]@{
    Endpoint       = $endpointUri.AbsoluteUri
    OutputPath     = $outputPath
    TimeoutSeconds = [int]$config.timeoutSeconds
    EnableArchive  = $enableArchive
    TokenLoaded    = $true
}

预期结果。配置有效时,脚本输出一个脱敏后的统一配置对象;配置文件缺失、端点非法、超时非正数或凭据未注入时,脚本会立即抛出终止错误。脚本不会输出令牌值,业务函数也无需知道参数来自文件还是环境变量。

运行并验证覆盖规则

在 PowerShell 7 中执行以下命令。示例覆盖端点和功能开关,同时注入测试令牌。

powershell
$env:APP_ENDPOINT = 'https://test-api.example.internal'
$env:APP_ENABLE_ARCHIVE = 'true'
$env:APP_API_TOKEN = 'test-token-value'

./run.ps1 | Format-List

预期输出

text
Endpoint       : https://test-api.example.internal/
OutputPath     : <PATH>
TimeoutSeconds : 20
EnableArchive  : True
TokenLoaded    : True

<PATH> 是根据 settings.json 所在目录解析得到的绝对路径,实际值会因保存位置不同而变化。输出中的端点和开关来自环境变量,超时和输出路径来自配置文件,说明覆盖顺序已经生效。

管理多环境与失败边界

可以为不同环境准备 settings.dev.json、settings.test.json 和 settings.prod.json,部署时只通过 -ConfigPath 选择文件,不修改脚本。环境文件应保持相同字段结构,避免业务代码出现环境分支。

启动阶段应采用“快速失败”:配置文件缺失、布尔值非法、端点格式错误或凭据未注入时立即终止。不要静默回退到危险默认值,也不要在错误消息中打印令牌、密码或完整连接字符串。

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

目录与阅读设置

阅读设置

17

记录一个想法

分离配置与运行环境

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

登录哪都通