Python configparser ExtendedInterpolation 组织分层配置

用 configparser.ExtendedInterpolation 组织分层配置，最实用的做法是把“原始值”“环境覆盖”“派生值”分开：基础文件保存完整默认项，环境文件只覆盖变化的键，其他路径和地址通过 ${section:option} 引用。读取多个文件时后读文件优先，而插值会在取值时展开，因此只改一个主机名或根目录，所有引用它的配置都会得到新结果。

Python 官方文档：https://docs.python.org/3/library/configparser.html

这套方案适合中小型 Python 服务、脚本和内部工具。它不需要第三方库，但必须显式启用 ExtendedInterpolation()；默认的 ConfigParser 使用的是另一套 %(name)s 基础插值语法。

先用最小写法启用 ExtendedInterpolation

最小初始化只有一处关键参数：

import configparser

# 显式启用扩展插值，才能使用 ${section:option} 语法。
config = configparser.ConfigParser(
    interpolation=configparser.ExtendedInterpolation()
)

# 按顺序读取配置；后面的文件覆盖前面的同名键。
loaded_files = config.read(
    ["base.ini", "prod.ini"],
    encoding="utf-8",
)

${section:option} 用于跨节引用；同一节内可省略节名，写成 ${option}。如果值中需要字面量美元符号，要写成 $$。例如价格模板 cost = $$80 取出后得到 $80。

把公共值、路径和服务地址拆成三层

下面的基础文件把全局共享值放进 DEFAULT，路径放进 paths，业务地址放进 service。这样每个原始值只有一个维护位置。

[DEFAULT]
# 所有普通节都可以读取这些默认项。
scheme = https
host = api.example.com
port = 443

[paths]
# 同节引用可省略节名。
root = /srv/myapp
logs = ${root}/logs
cache = ${root}/cache

[service]
# DEFAULT 中的值可按当前节可见项直接引用。
base_url = ${scheme}://${host}:${port}
health_url = ${base_url}/health
# 跨节引用必须写明 paths 节。
log_dir = ${paths:logs}

这里没有字符串复制：health_url 依赖 base_url，log_dir 依赖 paths.logs，而 paths.logs 又依赖 paths.root。ExtendedInterpolation 允许多层引用，配置项在文件中的先后顺序不是解析依赖的依据。

让环境文件只覆盖真正变化的键

生产环境通常只需要替换域名和根目录，不必复制整份文件：

[DEFAULT]
# 生产环境只覆盖与基础环境不同的主机名。
host = api.prod.example.com

[paths]
# 派生的 logs 和 cache 会使用新的根目录。
root = /data/myapp

当程序依次读取 base.ini 和 prod.ini 时，后读文件中的同名键优先，未冲突的键仍保留。于是 service.base_url 会使用生产域名，paths.logs 会使用 /data/myapp，而生产文件无需重复 health_url 或 log_dir。

读取后的使用方式仍然很简单：

# 取值时才展开引用，得到的是最终合并后的结果。
base_url = config.get("service", "base_url")
health_url = config["service"]["health_url"]
log_dir = config.get("service", "log_dir")

# 数字仍以字符串保存，应使用类型转换 getter。
port = config.getint("service", "port")

一次配置故障暴露了延迟插值

分层改造后最容易出现的症状，不是 read() 立刻报错，而是应用第一次读取某个派生项时才失败。原因是插值按需发生：文件能被读入，只代表 INI 结构可解析，不代表每条引用链已经成功展开。

一个典型故障过程是这样的：基础文件中把 host 改名为 api_host，环境覆盖文件仍然保留旧键；service.base_url 继续引用 ${host}。启动阶段只检查了 read() 返回值，因此没有发现问题；直到请求代码调用 get("service", "base_url")，才触发 InterpolationMissingOptionError。

[DEFAULT]
# 新名称已经写入，但旧引用没有同步修改。
api_host = api.prod.example.com

[service]
# 这里仍引用不存在的 host，取值时才会失败。
base_url = ${scheme}://${host}:${port}

根因并不是多文件覆盖失效，而是把“文件读取成功”误当成了“所有派生值可解析”。同理，引用链形成循环或层级过深时，会在展开过程中触发 InterpolationDepthError；插值语法本身不合法时，则会触发 InterpolationSyntaxError。

增加启动检查和原始值诊断

修复动作分两部分：先检查必需文件确实加载，再在应用启动时主动读取所有关键派生项。这样错误会在接收流量前暴露，而不是留到某条业务路径首次访问配置时。

from pathlib import Path
import configparser


def load_config(base_file: str, override_file: str) -> configparser.ConfigParser:
    # 基础文件是必需项，使用 read_file 让打开失败直接暴露。
    parser = configparser.ConfigParser(
        interpolation=configparser.ExtendedInterpolation()
    )
    base_path = Path(base_file)
    with base_path.open("r", encoding="utf-8") as stream:
        parser.read_file(stream, source=str(base_path))

    # 覆盖文件可选；read 返回成功读取的文件列表。
    parser.read([override_file], encoding="utf-8")

    # 主动展开关键项，把延迟插值错误前移到启动阶段。
    required = [
        ("service", "base_url"),
        ("service", "health_url"),
        ("service", "log_dir"),
    ]
    for section, option in required:
        try:
            value = parser.get(section, option)
        except configparser.Error as exc:
            raise RuntimeError(
                f"配置项无法解析: {section}.{option}"
            ) from exc
        if not value.strip():
            raise RuntimeError(f"配置项不能为空: {section}.{option}")

    return parser

排查时，raw=True 很有用：它跳过插值，直接返回 INI 中保存的原始模板。把原始值和展开值并排打印，就能判断问题发生在文件覆盖还是引用展开。

# raw=True 保留 ${...}，适合确认实际写入的引用模板。
template = config.get("service", "health_url", raw=True)

# 默认 raw=False，会展开完整引用链。
resolved = config.get("service", "health_url")

# 日志中可记录键名和结果，敏感值应按业务要求脱敏。
print({"template": template, "resolved": resolved})

四个容易混淆的边界

DEFAULT 和 fallback 不是同一层

DEFAULT 中的值会被普通节继承，而且它的优先级高于调用 get() 时传入的 fallback。只要默认节已经有该键，fallback 就不会覆盖它。

# DEFAULT 中已有 port 时，fallback=8080 不会替换它。
port = config.getint("service", "port", fallback=8080)

键名默认不区分大小写

ConfigParser 默认通过 optionxform() 把键名转换为小写，插值引用中的选项名也会经过同样转换。因此 ${HOST} 和 ${host} 默认等价。节名则默认区分大小写。如果项目确实需要保留键名大小写，可以覆盖 optionxform，但整套配置必须统一策略。

# 保留键名原样；该函数必须保持幂等。
case_sensitive = configparser.ConfigParser(
    interpolation=configparser.ExtendedInterpolation()
)
case_sensitive.optionxform = str

ExtendedInterpolation 不会自动读取环境变量

${HOME} 不会天然去操作系统环境中查找。若要引入环境变量，应在创建解析器时显式注入经过筛选的 defaults，避免把整个环境无差别暴露给配置。

import os
import configparser

# 只注入允许使用的环境变量，并提供清晰默认值。
runtime_defaults = {
    "deploy_root": os.environ.get("APP_DEPLOY_ROOT", "/srv/myapp"),
}
parser = configparser.ConfigParser(
    defaults=runtime_defaults,
    interpolation=configparser.ExtendedInterpolation(),
)

配置值始终先按字符串保存

插值完成后仍然是字符串。端口、超时、布尔开关应使用 getint()、getfloat()、getboolean()，或注册自定义 converter。不要用 bool("false") 判断布尔配置，因为非空字符串会得到 True。

分层配置速查表

常见问题

为什么 read() 成功，get() 仍然报插值错误？

因为插值按需执行。read() 主要负责读取和解析文件结构，具体引用链通常在取值时展开。启动时主动读取关键项即可提前发现问题。

多个 INI 文件应该按什么顺序读取？

从通用到具体：基础配置、站点配置、环境配置、本机覆盖。越靠后的文件优先级越高。必需文件建议用 read_file() 明确打开，可选文件可以用 read() 并检查返回列表。

能否让一个环境文件删除基础文件中的键？

多文件读取擅长覆盖和补充，不提供“用后一个文件声明删除前一个键”的通用语义。需要删除时，应在加载后显式调用 remove_option()，或重新设计为清晰的启用开关。

什么时候不该继续使用 INI 插值？

当配置已经包含复杂嵌套对象、列表、模式校验、条件表达式或大量密钥管理需求时，INI 的扁平节和字符串模型会变得勉强。此时应考虑 TOML、专门的配置模型或密钥服务，而不是继续增加更深的插值链。

总结

ExtendedInterpolation 的价值不在于少写几个字符串，而在于明确配置依赖：原始值集中维护，环境文件只覆盖差异，派生项通过引用自动跟随。真正需要防范的是延迟插值带来的启动盲区。只要固定加载顺序、显式启用扩展插值、在启动阶段读取关键项，并保留 raw=True 诊断入口，Python 项目的多环境 INI 配置就能保持简洁且可定位。