让 Python 服务启动前检查配置：把运行期故障提前发现

服务启动后才发现端口写成了文字、必需的数据库地址为空，排查时常会把注意力放到网络、依赖或代码上。很多这类故障其实来自配置没有在入口处校验。把配置读取集中到启动阶段，尽早失败并给出明确提示，能让部署问题更容易定位，也能避免服务带着不完整设置运行。

一、先划清配置边界

代码里放稳定的默认值和规则，环境变量提供随环境变化的值。开发、测试、生产可以使用不同的端口和连接地址，但应用读取配置的入口应保持一致。不要在业务函数里到处调用 os.getenv；否则同一项设置可能被读取多次，测试时也难以知道最终生效的值。

二、集中读取并校验

下面用 Python 标准库演示端口、调试开关和数据库地址的检查：

from dataclasses import dataclass
import os

@dataclass(frozen=True)
class Settings:
    port: int
    debug: bool
    database_url: str

def load_settings() -> Settings:
    raw_port = os.getenv("APP_PORT", "8000").strip()
    try:
        port = int(raw_port)
    except ValueError as exc:
        raise ValueError("APP_PORT 必须是整数") from exc
    if not 1 <= port <= 65535:
        raise ValueError("APP_PORT 必须在 1 到 65535 之间")

    raw_debug = os.getenv("APP_DEBUG", "false").strip().lower()
    if raw_debug not in {"true", "false"}:
        raise ValueError("APP_DEBUG 只接受 true 或 false")

    database_url = os.getenv("DATABASE_URL", "").strip()
    if not database_url:
        raise ValueError("必须设置 DATABASE_URL")

    return Settings(port, raw_debug == "true", database_url)

settings = load_settings()

这里的重点不是检查得越复杂越好，而是把容易出错的类型、范围和必填项显式化。示例只检查连接地址非空；如果项目还要求特定协议或主机格式，应依据实际数据库类型增加规则。校验失败时抛出带变量名的错误，部署日志就能直接指出缺少什么，而不是等第一次请求才出现难懂的异常。

三、让环境差异可见

可以在部署配置中明确写出 APP_PORT、APP_DEBUG 等非敏感变量，并在启动文档里列出默认值、允许范围和是否必填。开发环境可以使用本地专用的配置文件，但应确保文件不会被提交到公共仓库；生产环境中的密码、令牌等秘密应从受控的秘密配置渠道注入，不能写进代码、镜像或普通日志。日志只记录校验成功和配置来源，不要打印完整连接串，因为其中可能包含用户名或密码。

四、把校验当作可测试逻辑

为 load_settings 编写几类小测试：不设置端口时使用默认值；端口不是整数或超出范围时失败；调试开关出现未知拼写时失败；必填地址为空时失败。测试可以通过临时设置和清理环境变量完成，确保每个用例互不影响。这样，修改默认值或新增必填项时，错误会在持续集成阶段暴露，而不是留到部署之后。

五、启动顺序也很重要

先加载并校验配置，再创建依赖配置的客户端和应用对象。这样启动错误能在入口处中止，并保留清晰的原因。不要为了“尽量启动”而悄悄用空字符串或危险默认值替代缺失的生产配置；宁可明确失败，也不要让服务在错误参数下接收流量。

配置校验不能替代权限、连通性和服务健康检查，但它能把一类常见问题从运行中提前到启动时。把读取集中起来、把规则写清楚、把错误信息控制在不泄露秘密的范围内，是一项投入很小、容易持续维护的可靠性改进。