配置、环境变量与密钥边界

配置、环境变量与密钥边界

JS/TS 常从 process.env 读取配置。Python 和 C++ 也可以读取环境变量，但环境变量本身永远是字符串，缺失、拼写错误和非法数值都要到启动边界处理。真正可靠的做法是启动时集中解析、校验并生成不可变配置，业务模块只接受 Config，不在每个函数里重新读取环境。

配置还要区分普通参数和秘密。服务地址、端口、超时、模型名可以记录来源；API key、数据库密码和设备凭据应该由 secret store 或部署环境注入，不能进入源码、日志、异常文本和构建产物。机器人系统还常有频率、坐标系、设备路径和安全阈值，单位必须和数值一起验证。

学习目标

• 能在启动边界把字符串配置解析成有明确类型和范围的值。
• 能写出默认值、文件、环境变量和命令行之间的优先级，并返回安全摘要。
• 能区分缺配置、非法配置与秘密缺失，避免把值泄漏进日志或测试。

配置要能被验证，而不是到运行时才崩

下面这段代码只保留同一个意图，重点观察输入边界、数据流和失败语义，而不是逐字符翻译。

const port = Number(process.env.PORT ?? 8080);
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("API_KEY is required");

# Python
port = int(os.getenv("PORT", "8080"))
api_key = os.environ["API_KEY"]

// C++
const char* raw_port = std::getenv("PORT");
const char* api_key = std::getenv("API_KEY");

从字符串到不可变配置

环境变量只是一种输入，不是类型安全的配置对象。解析函数应完成 trim、类型转换、范围检查和相互约束，例如 timeout_ms > 0、HTTPS 地址必须有主机、控制频率不能超过硬件允许值。成功后返回只读配置；失败时指出字段名和原因，但不回显秘密。默认值也要写在契约里，避免本地和生产默默使用不同设置。

from dataclasses import dataclass
import os

@dataclass(frozen=True)
class Config:
    endpoint: str
    timeout_s: float

def load_config() -> Config:
    endpoint = os.environ.get("MODEL_ENDPOINT")
    if not endpoint:
        raise RuntimeError("MODEL_ENDPOINT is required")
    timeout_s = float(os.environ.get("MODEL_TIMEOUT_S", "5"))
    if timeout_s <= 0:
        raise RuntimeError("MODEL_TIMEOUT_S must be positive")
    return Config(endpoint=endpoint, timeout_s=timeout_s)

来源优先级与环境隔离

先定义“默认值 < 配置文件 < 环境变量 < CLI”的优先级，再在启动日志中打印字段名和来源。测试不应依赖开发机的环境变量，可以传入一个显式映射；C++ 可在 main 中读取 std::getenv 后立即转换，Node 则将 process.env 变成经过 schema 校验的对象。配置对象一旦创建，传入模型服务、文件适配器和机器人节点。

常见错误与排错思路

常见错误是把 PORT 当数字比较，或者在模块导入时读取秘密，导致测试顺序和运行环境影响结果。排错时先输出非敏感字段的来源、解析后的类型与有效范围，检查是否加载了错误的 .env/配置文件；若生产缺配置，确认部署注入名与代码读取名完全一致。发现密钥被打印或提交后，应立即停止扩散并轮换凭据。

从原始字符串生成有效配置

解析最好是一个接受普通对象的纯函数，这样测试不必改写当前终端的环境变量。先集中转换所有值，任何一项不合法就整体拒绝；不要让部分模块悄悄退回不同默认值。

function loadConfig(env) {
  const port = Number(env.PORT ?? "8080");
  const timeoutMs = Number(env.TIMEOUT_MS ?? "5000");
  if (!Number.isInteger(port) || port < 1 || port > 65535) return { ok: false, code: "invalid_port" };
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return { ok: false, code: "invalid_timeout" };
  return { ok: true, config: { port, timeoutMs, hasToken: Boolean(env.API_TOKEN) } };
}
console.log(loadConfig({ PORT: "9000", API_TOKEN: "not-printed" }));

输出只含端口、超时和秘密是否存在，不包含秘密值。验证时逐一传入：默认环境、合法覆盖、端口 0、文字端口、负超时、空 token。每种输入都应得到可预测结果；合法配置应该在启动时一次生成，后续只读传入业务函数。

优先级与故障定位

明确覆盖关系，例如默认值 < 配置文件 < 环境变量 < 命令行。每个解析值同时保留来源标签，启动摘要记录 port_source=env 而不是整个环境对象。若本地能启动、CI 失败，比较变量名、当前工作目录和加载文件路径；若错误只在导入时出现，把读取环境的动作从模块顶层移到明确的 loadConfig 调用。

解析器应能解释“为什么这个值生效”：每个字段都能报告最终类型和来源，但不能回显秘密。多个配置来源冲突时，先确定覆盖顺序，再测试同一字段在默认、文件、环境和命令行分别出现的结果；若一个来源只覆盖部分字段，其余字段仍应从较低优先级来源补齐。

验证配置组合与启动失败

除了逐个测字段，还要测组合约束，例如超时时间必须为正、服务 URL 必须包含受支持的协议、机器人控制频率不能高于设备上限。缺少必填配置时应在启动阶段给出字段名和修复提示并以非零状态退出，不应等到第一条请求才崩。测试传入独立环境映射，结束后检查 logger 没有包含 token、密码或完整连接串。

如果配置源来自文件，确认读取路径基于明确的应用根目录，且生产环境权限足够但不过宽。若不同模块各自读取同一个环境变量，统一收敛到单一配置对象，否则很难解释最终值究竟从哪里来。

生产秘密缺失时应快速失败，并只记录秘密名称或 secret_missing 状态。若秘密曾被打印或提交，单纯删除日志并不能撤销暴露，应按凭据管理流程轮换。

优先级表应对应真实启动场景

高优先级来源没有提供字段时，继续保留低优先级来源值；提供了空字符串时，则按照字段契约决定它是合法空值、显式清空还是非法配置。不同配置源之间相互矛盾时，例如 TLS 关闭但地址要求 HTTPS，要在构造 Config 时拒绝并指出冲突字段，不能留给首个网络请求暴露。

配置快照与重新加载

进程启动时生成只读配置快照，便于记录版本与复现问题。需要动态重载时，先解析并完整验证新快照，再原子切换；不能边读取文件边修改多个全局变量，否则请求可能看到半旧半新的组合。秘密轮换也要定义新旧凭据过渡期，日志只记录版本或是否存在，不记录值。

运行验证：启动边界与覆盖来源

每次测试传入独立 source map，确认四层优先级、部分字段回退、非法空值、冲突约束和秘密缺失均有固定结果。对失败启动断言模型/设备依赖尚未创建；对成功启动断言配置摘要包含字段来源且没有敏感内容。这样能把本地“刚好有环境变量”的问题提前暴露在 CI。

迁移练习

配置来源优先级的逐项推演

拿同一个 PORT 分别在默认值、配置文件、环境变量和 CLI 中赋不同值，按既定优先级逐层合并；每一步都应能说明当前值和来源。另一个字段只出现在低优先级文件中时，不应因为高优先级来源缺少它就被擦除。可以将解析产物拆成 value 与 source，最后再提取不可变业务配置。

运行验证：非法值不得进入业务层

创建独立测试环境映射，测试非法端口、负超时、URL 协议不支持、必需秘密缺失和相互矛盾配置。每种情况检查错误字段、退出状态和非敏感来源摘要，并断言模型/设备依赖还没有被创建。合法配置则检查最终类型，而非只比较字符串；这样 Python、JS/TS 和 C++ 不会在一个语言里容忍空字符串、在另一个语言里误解析为零。

请完成：定义一个包含端口、服务地址和超时的配置对象，并为缺失字段、非法端口、负超时和秘密缺失写出启动错误与安全日志行为。

先读取所有变量，转换成明确类型并验证端口 1..65535、超时大于 0、地址有合法 scheme；缺少秘密只记录 secret_missing 和字段名，不记录值。成功返回不可变 Config，失败在启动阶段以非零退出码结束。

小结

配置在启动边界解析、校验并冻结，业务代码只消费有效配置；来源应可解释，秘密只检查而不展示。接下来处理 CLI 时，可把命令行参数作为最高优先级输入并注入同一配置流程。