Python dataclass 配置管理实战：默认值、环境变量覆盖和启动校验

小项目里配置经常从多个地方来：代码默认值、环境变量、容器注入、部署平台变量。刚开始可以直接 `os.getenv`，但随着配置项变多，类型转换、默认值和错误提示会散落在业务代码里。更稳妥的做法，是把配置集中到一个 `dataclass`，启动时一次性加载并校验。

适合人群：正在写 Python Web 服务、脚本任务、数据处理任务的同学。本文只使用标准库，适合想先把配置管理整理清楚，再考虑 pydantic、dynaconf 等更完整方案的场景。

目录

• 为什么配置不能到处读取
• 配置加载链路：默认值到环境变量
• 用 dataclass 写 AppConfig
• 启动校验：错误要早暴露
• 常见坑和上线检查

一、为什么配置不能到处读取

如果业务代码里到处都有 `os.getenv("DB_HOST")`，短期看省事，长期会有几个问题：

• 默认值分散：同一个超时参数可能在不同文件里有不同默认值。
• 类型不明确：环境变量都是字符串，端口、开关、超时需要统一转换。
• 错误发现太晚：服务跑到某个分支才发现配置缺失，排查成本更高。
• 测试不方便：单元测试需要反复改环境变量，难以构造稳定输入。

配置对象的目标很简单：启动时把外部输入收拢成一个结构清楚的对象，业务代码只依赖这个对象，不直接接触环境变量。

二、配置加载链路：默认值到环境变量

一个轻量但实用的加载顺序可以设计成：先定义代码默认值，再读取环境变量覆盖，随后做类型转换和校验，最后交给业务模块使用。这样每个配置项的来源、类型和错误都能被统一管理。

注意，环境变量适合覆盖部署差异，比如端口、数据库地址、日志级别；不建议在代码里写死生产密钥，也不要把一整段复杂 JSON 藏在一个变量里，后续维护会很难。

三、用 dataclass 写 AppConfig

下面是一份可直接运行的配置加载代码。它把端口、数据库地址、调试开关和请求超时整理到 `AppConfig`，并在 `from_env` 方法里统一处理字符串到目标类型的转换。

from __future__ import annotations

from dataclasses import dataclass
import os


def read_bool(name: str, default: bool) -> bool:
    raw = os.getenv(name)
    if raw is None:
        return default
    return raw.strip().lower() in {"1", "true", "yes", "on"}


def read_int(name: str, default: int) -> int:
    raw = os.getenv(name)
    if raw is None or raw.strip() == "":
        return default
    try:
        return int(raw)
    except ValueError as err:
        raise ValueError(f"{name} must be an integer") from err


@dataclass(frozen=True)
class AppConfig:
    app_name: str = "demo-service"
    host: str = "127.0.0.1"
    port: int = 8000
    db_host: str = "127.0.0.1"
    db_port: int = 3306
    request_timeout_ms: int = 3000
    debug: bool = False

    @classmethod
    def from_env(cls) -> "AppConfig":
        return cls(
            app_name=os.getenv("APP_NAME", cls.app_name),
            host=os.getenv("APP_HOST", cls.host),
            port=read_int("APP_PORT", cls.port),
            db_host=os.getenv("DB_HOST", cls.db_host),
            db_port=read_int("DB_PORT", cls.db_port),
            request_timeout_ms=read_int("REQUEST_TIMEOUT_MS", cls.request_timeout_ms),
            debug=read_bool("APP_DEBUG", cls.debug),
        )

`frozen=True` 不是必须的，但它能避免运行中被随手修改配置。服务启动后，配置通常应该保持稳定；如果确实需要动态配置，建议走独立的配置中心和刷新机制，而不是到处改对象属性。

四、启动校验：错误要早暴露

配置加载完成后，马上做业务校验。类型转换只能保证格式大体正确，不能保证值合理。例如端口不能越界、超时时间不能为 0、数据库地址不能是空字符串。

class ConfigError(RuntimeError):
    pass


def check_config(config: AppConfig) -> None:
    errors: list[str] = []

    if not 1  AppConfig:
    config = AppConfig.from_env()
    check_config(config)
    return config


if __name__ == "__main__":
    settings = load_config()
    print(settings)

这类错误最好在启动阶段直接暴露出来。容器平台看到进程启动失败，会按重启策略处理；如果让服务带着错误配置继续运行，用户请求进来后才失败，影响面会更大。

五、常见坑和上线检查

1. 不要在业务函数里直接读环境变量

业务函数应该接收 `AppConfig` 或者接收由配置创建好的客户端对象。这样单元测试可以直接传入配置对象，不需要在测试里反复修改全局环境。

2. 不要把布尔值只按 Python 真值判断

环境变量里的 `"false"` 是非空字符串，如果直接 `bool("false")` 会得到 `True`。布尔配置要单独解析，明确哪些值代表开启。

3. 默认值要适合本地开发，不要假装是生产配置

默认端口、本地数据库地址、较短超时适合开发环境；生产环境的数据库地址、密钥、外部服务地址应该由部署平台注入。

4. 上线前快速自测

APP_PORT=8080 DB_HOST=127.0.0.1 python app_config.py
APP_PORT=abc python app_config.py
REQUEST_TIMEOUT_MS=1 python app_config.py

第一条应该正常打印配置；第二条应该在类型转换阶段失败；第三条应该在业务校验阶段失败。把这三类结果分清楚，线上排查会轻松很多。

总结

用 `dataclass` 管理 Python 配置的核心思路是：集中定义字段，统一读取环境变量，显式做类型转换，启动时一次性校验。它不复杂，却能让配置来源更清楚、错误更早暴露，也能让业务代码少接触全局环境。