# 配置加载器：默认值、文件与环境覆盖

学习目标：完成读取、解析、分层覆盖、严格校验和配置展示，明确“没有设置”和“设置了无效值”的区别。

前置知识：字符串、字典或对象、异常、文件读取。选择 Python 与 JavaScript：前者用上下文和映射，后者用 Node.js 文件 API 和环境对象；两者均使用标准库，比较的是输入边界而不是配置框架。配置很小且只在启动时加载，因此这里有意使用同步读取，不为了异步而引入并发结构。

# 问题与边界

这是一个显式指定文件的启动配置检查器，不搜索 home、工作目录或系统配置。命令行读取文件和真实进程环境，成功打印生效配置，失败报告错误且不输出部分配置。无参数模式在临时目录演示所有层级，不修改真实环境变量。

优先级是 默认值 < 文件 < 环境变量。端口允许前导零；不接受符号、空白、小数、指数或全角数字。空环境变量是显式的无效设置，不能回退到文件。无关环境变量忽略。

文件格式是本工具定义的两键 key=value 格式，不是 TOML、INI 或 dotenv 的兼容实现：UTF-8、无 BOM；LF、CRLF、CR 均可；空行可忽略，其他空白不修剪；不支持注释、插值、引号或转义。未知键、重复键、缺少等号、非法值都失败。空文件使用默认值，显式路径不存在则失败，不能当作空文件。

特别约定：先校验文件全部内容，再应用并校验环境覆盖。因此 port=broken 即使被 APP_PORT=9000 覆盖，仍报错。这能暴露配置漂移；“只校验最终生效值”也是可能的产品政策，但不是本例的语义。

# 关键差异

不能用 bool("false") 或 Boolean("false") 解析布尔文本；非空字符串是真值，但这不是配置协议。也不能用 env.APP_PORT || default，因为空字符串应该报错而不是被默认值掩盖。Python 环境映射见 os.environ，Node.js 环境值是文本，见 process.env。

# 各语言实现

# Python

执行 python main.py 运行隔离演示；执行 python main.py "配置路径" 读取真实配置及当前进程环境。成功返回 0，输入错误返回 1，参数错误返回 2。

Pythonimport os
import re
import sys
from pathlib import Path
from tempfile import TemporaryDirectory

def parse_value(key, text):
    if key == "port":
        if re.fullmatch(r"[0-9]{1,5}", text) and 1 <= int(text) <= 65535:
            return int(text)
        raise ValueError("invalid port")
    if text not in ("true", "false"):
        raise ValueError("invalid debug")
    return text == "true"

def load_config(path, env):
    try:
        with open(path, encoding="utf-8", newline=None) as source:
            text = source.read()
    except (OSError, UnicodeError) as error:
        raise ValueError("config read failed") from error
    config = {"port": 8080, "debug": False}
    seen = set()
    for number, line in enumerate(text.split("\n"), 1):
        if line == "":
            continue
        key, separator, value = line.partition("=")
        if not separator or key not in config or key in seen:
            raise ValueError(f"line {number}: invalid key")
        seen.add(key)
        config[key] = parse_value(key, value)
    for key, name in [("port", "APP_PORT"), ("debug", "APP_DEBUG")]:
        if name in env:
            config[key] = parse_value(key, env[name])
    return config

def render(config):
    return f"port={config['port']} debug={str(config['debug']).lower()}"

def demo():
    with TemporaryDirectory(prefix="config-demo-") as directory:
        path = Path(directory) / "app.conf"
        path.write_bytes(b"")
        config = load_config(path, {})
        assert config == {"port": 8080, "debug": False}
        print("defaults: " + render(config))
        path.write_bytes(b"port=00080\r\ndebug=true\r")
        config = load_config(path, {})
        assert config == {"port": 80, "debug": True}
        print("file: " + render(config))
        env = {"APP_PORT": "9000", "APP_DEBUG": "false", "OTHER": "ignored"}
        config = load_config(path, env)
        assert config == {"port": 9000, "debug": False}
        print("env: " + render(config))
        for port in ["1", "65535"]:
            assert load_config(path, {"APP_PORT": port})["port"] == int(port)
        for port in ["", "0", "65536", " 80", "+80", "80x", "1e3", "８０"]:
            try:
                load_config(path, {"APP_PORT": port})
            except ValueError as error:
                assert str(error) == "invalid port"
            else:
                raise AssertionError("invalid environment accepted")
        cases = [
            ("port=0", {"APP_PORT": "9000"}, "invalid port"),
            ("port=80\nport=81", {}, "line 2: invalid key"),
            ("unknown=x", {}, "line 1: invalid key"),
            ("port", {}, "line 1: invalid key"),
            ("debug=TRUE", {}, "invalid debug"),
            ("debug=true", {"APP_DEBUG": ""}, "invalid debug"),
        ]
        for text, overrides, message in cases:
            path.write_text(text, encoding="utf-8")
            try:
                load_config(path, overrides)
            except ValueError as error:
                assert str(error) == message
                print("error: " + str(error))
            else:
                raise AssertionError("invalid config accepted")
        try:
            load_config(Path(directory) / "missing.conf", {})
        except ValueError as error:
            assert str(error) == "config read failed"
            print("error: " + str(error))
        else:
            raise AssertionError("missing file accepted")

def main():
    if len(sys.argv) == 1:
        demo()
        return 0
    if len(sys.argv) != 2:
        print("usage: python main.py [FILE]", file=sys.stderr)
        return 2
    try:
        config = load_config(sys.argv[1], os.environ)
    except ValueError as error:
        print(f"error: {error}", file=sys.stderr)
        return 1
    print(render(config))
    return 0

if __name__ == "__main__":
    sys.exit(main())

env 是显式参数，CLI 才传入 os.environ；演示传普通映射，既覆盖相同路径，又不污染后续程序的环境。load_config 构造局部对象，只在全部步骤成功后返回，不把半校验状态存到全局。Python open 的通用换行处理把三种换行归一为 \n。

# JavaScript

使用独立 CommonJS 目录。执行 node main.js；读取真实配置为 node main.js "配置路径"，退出状态同上。

JavaScriptconst assert = require('node:assert/strict');
const { readFileSync, writeFileSync, mkdtempSync, rmSync } = require('node:fs');
const { tmpdir } = require('node:os');
const { join } = require('node:path');
const { TextDecoder } = require('node:util');

function parseValue(key, text) {
  if (key === 'port') {
    if (/^[0-9]{1,5}$/.test(text) && !text.includes('\n') &&
        Number(text) >= 1 && Number(text) <= 65535) return Number(text);
    throw new Error('invalid port');
  }
  if (text !== 'true' && text !== 'false') throw new Error('invalid debug');
  return text === 'true';
}

function loadConfig(path, env) {
  let text;
  try {
    // ignoreBOM=true 保留 BOM，让键名检查拒绝它，而非静默剥离。
    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
      .decode(readFileSync(path));
  } catch (error) {
    throw new Error('config read failed', { cause: error });
  }
  const config = { port: 8080, debug: false };
  const seen = new Set();
  const lines = text.split(/\r\n|\r|\n/);
  for (const [index, line] of lines.entries()) {
    if (line === '') continue;
    const separator = line.indexOf('=');
    const key = line.slice(0, separator);
    if (separator < 0 || !['port', 'debug'].includes(key) || seen.has(key)) {
      throw new Error(`line ${index + 1}: invalid key`);
    }
    seen.add(key);
    config[key] = parseValue(key, line.slice(separator + 1));
  }
  for (const [key, name] of [['port', 'APP_PORT'], ['debug', 'APP_DEBUG']]) {
    if (Object.hasOwn(env, name)) config[key] = parseValue(key, env[name]);
  }
  return config;
}

function render(config) {
  return `port=${config.port} debug=${config.debug}`;
}

function demo() {
  const directory = mkdtempSync(join(tmpdir(), 'config-demo-'));
  const path = join(directory, 'app.conf');
  try {
    writeFileSync(path, '');
    let config = loadConfig(path, {});
    assert.deepEqual(config, { port: 8080, debug: false });
    console.log('defaults: ' + render(config));
    writeFileSync(path, 'port=00080\r\ndebug=true\r');
    config = loadConfig(path, {});
    assert.deepEqual(config, { port: 80, debug: true });
    console.log('file: ' + render(config));
    config = loadConfig(path, { APP_PORT: '9000', APP_DEBUG: 'false', OTHER: 'ignored' });
    assert.deepEqual(config, { port: 9000, debug: false });
    console.log('env: ' + render(config));
    for (const port of ['1', '65535']) {
      assert.equal(loadConfig(path, { APP_PORT: port }).port, Number(port));
    }
    for (const port of ['', '0', '65536', ' 80', '+80', '80x', '1e3', '８０', '80\n']) {
      assert.throws(() => loadConfig(path, { APP_PORT: port }), { message: 'invalid port' });
    }
    const cases = [
      ['port=0', { APP_PORT: '9000' }, 'invalid port'],
      ['port=80\nport=81', {}, 'line 2: invalid key'],
      ['unknown=x', {}, 'line 1: invalid key'],
      ['port', {}, 'line 1: invalid key'],
      ['debug=TRUE', {}, 'invalid debug'],
      ['debug=true', { APP_DEBUG: '' }, 'invalid debug'],
    ];
    for (const [text, env, message] of cases) {
      writeFileSync(path, text, 'utf8');
      try {
        loadConfig(path, env);
        assert.fail('invalid config accepted');
      } catch (error) {
        assert.equal(error.message, message);
        console.log('error: ' + error.message);
      }
    }
    try {
      loadConfig(join(directory, 'missing.conf'), {});
      assert.fail('missing file accepted');
    } catch (error) {
      assert.equal(error.message, 'config read failed');
      console.log('error: ' + error.message);
    }
  } finally {
    rmSync(directory, { recursive: true, force: true });
  }
}

function main() {
  const args = process.argv.slice(2);
  if (args.length === 0) return demo();
  if (args.length !== 1) {
    console.error('usage: node main.js [FILE]');
    process.exitCode = 2;
    return;
  }
  try {
    console.log(render(loadConfig(args[0], process.env)));
  } catch (error) {
    console.error(`error: ${error.message}`);
    process.exitCode = 1;
  }
}
main();

JavaScript 的 $ 可以匹配末尾换行之前的位置，所以这里额外拒绝环境值中的 \n，不能把文件行已分割的前提误用到环境文本。解码的 fatal 和 BOM 选项见 TextDecoder。解析器只接受两个已知键，不把任意键复制到对象；Object.hasOwn 检查的是明确存在的覆盖项，而不是原型链上的属性。

# 迁移误区与适用限制

• 覆盖先于校验：把无效文件用合法环境“救回来”，改变了本例“每个已提供来源必须正确”的契约；若产品需要另一种政策，应明确改变测试和错误报告。
• 缺失等于空字符串：APP_PORT="" 不是未设置。空值失败可以及时发现部署模板漏填。
• 重复键最后一个获胜：本例拒绝重复键，防止读者看见第一项却实际使用最后一项；不能直接用字典推导覆盖掉证据。
• 格式兼容错觉：这不是通用配置格式解析库。若需要引号、数组、嵌套配置，应选择成熟格式解析器，而不是在这里逐项加字符串替换。
• 日志泄露：这里的字段非敏感，所以可打印全部值。增加密码或令牌后，展示层必须改为脱敏，不能照搬 render。
• 配置很小的前提：读取全部文件是有意选择；它不是不可信大文件的资源限制策略。加载后返回普通可变对象，也不提供运行期间自动重载与线程间发布保证。

# 运行与验证

无参数执行会创建并删除临时 app.conf。两种程序预期 stdout 完全相同：

纯文本defaults: port=8080 debug=false
file: port=80 debug=true
env: port=9000 debug=false
error: invalid port
error: line 2: invalid key
error: line 1: invalid key
error: line 1: invalid key
error: invalid debug
error: invalid debug
error: config read failed

边界断言覆盖默认值、两个字段的文件覆盖与环境覆盖、前导零、端口两端点、范围外、空值、大小写布尔、重复键、未知键、无等号、无效但被覆盖的文件值、混合换行和缺失文件。演示中的预期失败被调用方捕获，整次演示应返回 0；CLI 错误打印到 stderr，返回 1，且没有生效配置输出。文件创建与清理错误继续传播，不静默忽略。

如需手工试用 CLI，应先在自己新建的临时目录保存 port=80 和 debug=true 两行，再给当前子进程设置 APP_PORT=9000；预期得到 port=9000 debug=true。不要把样例写到现有应用目录。不同 shell 的环境设置语法不同，自动场景已通过显式映射覆盖同一加载函数，不要求修改当前 shell 环境。

版本见主题首页，实际运行证据见验证记录。本文列的是预期输出，不把阅读核对写成执行成功；权限错误、超大文件以及操作系统环境变量名称的大小写规则不在跨平台演示断言内。

# 相关阅读

• 字符串转端口号：格式约束与数值范围是两层检查。
• 日志统计器：逐行读取与完整结果提交。
• 保证由谁承担：加载成功后，调用方仍须保护配置使用的不变量。