32 配置

先问：发布以后还会变什么

配置不是把常量搬到 YAML 或 JSON 就结束了。真正值得外置的是那些会随着租户、流量、合规规则或运营策略变化，却不应该要求重新编译的决定。本章把“使用外部配置参数化应用程序”落成一个小合同：应用可以换一项策略，但不能把坏输入带进运行状态。

想象一个限流服务：代码固定了“怎样计算”，而每个环境决定“允许多少请求、何时生效、由谁批准”。先预测一下：如果配置文件缺少默认值，系统应该在读取、校验还是应用策略处停下？打开后面的实验台，只改变一个条件并观察首个变化。

配置合同：把变化留在边界外

一个可复查的配置记录至少包含名称、类型、默认值、版本和来源。<Term def="运行时从文件、环境变量或配置服务取得的策略输入，而不是编译进程序的常量。">外部配置</Term>负责承载变化；它不会自动获得可信身份。解析后的数据还要经过 <Term def="描述字段、类型、范围和必填关系的机器可检查规则。">配置模式</Term>，否则“看起来像数字”的字符串也可能一路传到业务代码。

本章使用一个具体例子：checkout.maxRetries 的默认值是 2，配置版本为 7，应用只接受 0 到 5 的整数。<Term def="字段缺失时采用的明确、可记录的安全值；它不是悄悄吞掉错误的空白。">默认值</Term>必须和版本一起记录，不能由每个调用者各自猜测。加载边界之后，服务再判断 <Term def="配置合同的编号，用来判断当前输入是否能被这段代码理解。">配置版本</Term>是否兼容。

type RetryPolicy = { maxRetries: number; configVersion: 7 };
 
function loadPolicy(raw: unknown): RetryPolicy {
  const parsed = policySchema.parse(raw);
  const maxRetries = parsed.maxRetries ?? 2;
  if (parsed.configVersion !== 7 || maxRetries < 0 || maxRetries > 5) {
    throw new Error("configuration rejected before policy activation");
  }
  return { maxRetries, configVersion: 7 };
}

关键点不是某个库的 API，而是拒绝发生在“激活”之前。调用者只拿到已经通过模式、默认值和版本检查的 RetryPolicy；它不需要知道输入来自文件还是环境变量，也不能在业务处理中临时拼出第二份默认值。

三个最容易被忽略的失败边界

加载、校验与动态变更的因果链

从文件读到对象并不等于配置生效。先把“输入 → 决定 → 结果”写成可观察节点，再讨论热更新。<Term def="记录谁在何时以什么输入、版本和理由做出配置决定的不可变事件。">审计记录</Term>是回退所需的证据，不是操作成功后的装饰日志。

本页的因果链是：读取原始文本，解析成候选对象，用模式拒绝形状错误，补上集中管理的默认值，检查版本，最后生成不可变策略。<Term def="在不重启进程的情况下用新配置候选替换当前策略快照的受控过程。">动态变更</Term>只能发生在完整候选通过后；它不应该让业务线程看到中间状态。

type Audit = {
  source: string;
  version: number;
  decision: "accepted" | "rejected";
  reason: string;
};
 
function activate(candidate: unknown): { policy: RetryPolicy; audit: Audit } {
  const policy = loadPolicy(candidate);
  return {
    policy,
    audit: {
      source: "checkout-policy.json",
      version: policy.configVersion,
      decision: "accepted",
      reason: "schema-and-version-accepted",
    },
  };
}

这段代码把候选构造和审计结果绑在一次决定上。真实系统还需要原子替换、并发读策略的同步方式以及敏感值脱敏；这些是工程实现的下一层，但不能改变“先形成完整候选，再切换”的边界。

用分步实验定位首个偏差

下面每一步都嵌入同一张专属管线图，读者可以把文字预测和图上的高亮节点对齐。注意：故障只撤掉默认值，其他输入、版本和切换动作保持不变。

证据矩阵：正常、边界和单故障

不要用最终的“服务仍然运行”证明配置正确。若旧策略碰巧还能工作，审计仍应显示候选被拒绝、当前快照未变、恢复是否成功。可验证性来自唯一干预和可重建证据，而不是来自一次绿色部署。

动手试：让一项策略安全地热更新

实验台提供三个确定性样本：完整配置、缺少默认值的配置和过期版本。先点击一个非基线样本，观察图中首差与状态说明，再点击“重置”确认它回到完整配置。这个交互验证的是状态合同：改变会可见，恢复会回到同一初始快照。

本章回顾

• 外部配置承载变化，但只有通过模式、默认值和版本检查的候选才可激活。
• 默认值必须集中、命名并写入审计；缺失与显式零值不能被混为一谈。
• 动态变更应构造不可变候选，再一次性切换，避免半份状态进入业务线程。
• 用单变量故障定位首个偏差，并从原始配置重放恢复，而不是修饰最终结果。

可验证练习

function refresh(raw: unknown) {
  currentPolicy.maxRetries = readMaxRetries(raw);
}

前后导航

• 上一页：31 继承税
• 下一页：第6章 并发