别再用 configparser 了:给本地配置加上加密、校验和版本迁移

先说一个我遇到过不止一次的事故

某个 Python 写的桌面工具,用户配置存在 config.json 里,其中有一项是第三方服务的 API key。

用户为了排查问题,把整个配置目录打包发给了客服。key 跟着压缩包一起出去了。

这类事故的根因不是「用户不小心」,而是我们把不该明文落盘的东西,用最方便的方式落盘了 :json.dump 一行代码,问题当场解决,密文一行代码都还没写。

如果你也在写带配置文件的 Python 工具,下面三个缺口大概率同时存在:

  1. 明文 。config.json、settings.ini 打开就能看,改一行就能生效。
  2. 没有类型和校验 。configparser 读出来永远是字符串,"true" 和 True 靠调用方自己猜;数值改成 99999 也照单全收,直到运行时才炸。
  3. 没有版本迁移。老用户机器上留着 v1 的字段,新代码只认 v2,于是「新装没问题、老用户升级就崩」。

python-dotenv、pydantic-settings 解决的是第 2 点的一部分,但对第 1、3 点基本不管;dynaconf 功能很全,代价是引入一套自己的运行时模型。

我想要的是另一种东西:配置结构用类和属性声明出来,读写在类型上收口,加密、校验、迁移都由这个结构自动完成。

这就是 conf_base 想做的事。下面是它解决同样问题时,代码长什么样。

三十秒版本的对比

你现在的做法 痛点 换成声明式之后
json.load + 字典 拼错 key 要到运行时才发现 拼错属性名当场 AttributeError
configparser 读字符串 每次都要 int() / == 'true' 类型由 default 决定,写错类型直接报错
明文文件 密钥、token 裸奔 一行 _cipher,落盘即密文
手改配置文件 越界值、非法枚举照单全收 validator 在写入前拦截
新增字段 老用户的旧文件没人管 _schema_version + _migrate 自动升级

从字典搬到类:五行

下面用到 AES-256-GCM,需要额外装加密依赖:pip install "conf-base[aes]"。 只用明文格式 + 校验的话,pip install conf-base 就够。

python 复制代码
from conf_base import ConfigBase, Section, AesGcmCipher

class ServerConfig(ConfigBase):
    _path = 'server.json.enc'
    _cipher = AesGcmCipher(key_env='APP_SECRET')

    server = Section('Server')
    secret = server.field(default='', read_only=True)
    port = server.field(default=8080, validator=lambda v: 1 <= v <= 65535)
    workers = server.field(default=4, validator=lambda v: 1 <= v <= 64)

类定义完成的那一刻,server.json.enc 就被创建好了,缺失的字段自动补默认值。之后所有读写都走属性:

python 复制代码
ServerConfig.port.value = 9090      # 校验通过 → 立刻落盘
ServerConfig.port.value             # 9090
ServerConfig.port.value = 70000     # ConfigValueError:校验失败

没有 load()、没有 save()、没有「改了忘了写回」这类 bug------赋值即持久化。

加密:磁盘上只有一个信封

_cipher = AesGcmCipher(key_env='APP_SECRET') 之后,文件里不再是 JSON 明文,而是这样一个信封:

json 复制代码
{
  "v": 1,
  "alg": "AES-256-GCM",
  "kid": "v1",
  "nonce": "...",
  "data": "..."
}

明文里只有算法、密钥编号和 nonce,配置值在 data 里,没有密钥读不出来。 密钥可以从环境变量取(示例里的 APP_SECRET),也可以代码里注入;AES-256-GCM 是 AEAD,篡改一个字节解密就会失败,不会悄悄返回错误数据。

如果只是防手改、不要求保密,用 SignedCipher 更轻:文件仍是明文,但末尾会附一行 HMAC-SHA256 签名,被改过就拒绝加载。

校验:把「运行时才炸」提前到「写入时就炸」

python 复制代码
    port = Section('Server').field(
        default=8080,
        validator=lambda v: isinstance(v, int) and 1 <= v <= 65535,
    )

validator 是任意 Callable[[Any], bool]。返回 False 抛 ConfigValueError,抛异常则会被包装成 ConfigValueError 并保留原始异常链。两种失败都会阻止写入,配置文件不会被污染。

类型这一层框架已经替你挡了:值的类型永远与 default 相同,True 不会被当成 1 存进去,"8080" 也不会被悄悄转换。

迁移:老用户的配置文件怎么活下来

python 复制代码
def migrate_v1_to_v2(cfg):
    server = dict(cfg['Server'])
    server['workers'] = server.pop('threads')
    return {**cfg, 'Server': server}


class AppConfig(ConfigBase):
    _path = 'app.json'
    _schema_version = 2
    _migrate = {1: migrate_v1_to_v2}

    server = Section('Server')
    workers = server.field(default=4)

文件里的 _schema_version 是 1,代码要求 2,读文件时自动调用 1 对应的迁移函数,结果写回并把版本号更新为 2。版本号比代码还新(用户装过更新版又回退)则直接抛 SchemaError,不会拿新格式喂给旧代码。

迁移函数签名就是 dict -> dict,可以随便拆函数、写测试,不需要理解库内部。

还有两个细节

环境变量覆盖 :field(env_key='APP_PORT') 之后,环境变量优先级最高,而且被覆盖的项禁止回写------防止你在代码里改了半天,落盘时把环境变量里的值写进文件。

批量写入 :with AppConfig.server.batch(): 里的多次赋值只在退出时落盘一次,中途异常整批回滚到进入前的状态。桌面应用里「改 10 个设置点一次确定」这种场景,省掉 9 次磁盘 IO。

什么时候别用它

  • 你只是读三个环境变量------python-dotenv 更合适;
  • 配置来自远程配置中心(Nacos、Apollo、etcd)------这个库只管本地文件;
  • 配置需要高频写入(每秒级)------它按「人改配置」的频率设计;
  • 配置结构复杂到需要嵌套模型校验------pydantic-settings 的表达力更强。

它解决的是「本地有一个配置文件,希望它类型安全、能加密、能被校验、能升级」这一类问题,仅此而已。

安装

bash 复制代码
pip install conf-base

不需要任何强制依赖;要 YAML/TOML 或加密再按需装扩展:

bash 复制代码
pip install "conf-base[yaml,toml,aes]"

仓库:GitHub | Gitee 三个可直接运行的示例在 examples/,中英双语文档在 README。

如果这个思路对你有用,点个 star 是最好的反馈;有具体场景想讨论,开 issue 就行。

相关推荐
M--Y1 小时前
LangGraph 架构基石:持久化与运行控制
python·langchain·大模型·llm·持久化·langgraph
用户019027581612 小时前
新浪财经 / 东方财富股票接口不稳、被限?稳定替代方案
python
七夜zippoe2 小时前
Nexent 知识库:调优靠 Chunk 与重排
开发语言·python·ai智能体·nexent·知识库与rag
承渊政道4 小时前
【Python编程—从入门到实践】(用户账户:给Django网站装上登录系统,让每个人拥有自己的学习笔记)
python·学习·pycharm·django
承渊政道6 小时前
【Python编程—从入门到实践】(设置样式并部署:给Django网站换新装,把学习笔记发布到互联网)
python·学习·pycharm·django
用户298698530146 小时前
使用 Python 将 JSON 转换为 Word 文档的实践指南
python·json·api
卷无止境7 小时前
AI 加速开发之后,如何应对尚未发现的代码安全威胁
后端·python
cpolar技术支持7 小时前
容器数是 6 个、6 个、还是 6 个,可服务早被换掉了:用一个 5.5MB 的 Go 单文件把机器每周的变化记下来,再给它套一层别人看不懂的入口
python·docker·ai·cpolar
ONEYAC唯样7 小时前
YXC扬兴科技小型化有源晶振OT4JI-111-24M,提升红外热成像稳定性
人工智能·python·pygame
威哥爱编程7 小时前
模拟面试智能体开发实战 09:把面试官装进手机,鸿蒙端聊天界面用 SSE 流式输出让回复逐字滚出来
python·agent·harmonyos