Cerberus 数据规范化规则详解：从字段重命名到类型转换-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00149/article/details/148601853

Cerberus 数据规范化规则详解：从字段重命名到类型转换

cerberus Lightweight, extensible data validation library for Python 项目地址: https://gitcode.com/gh_mirrors/cer/cerberus

前言

在数据处理和验证过程中，规范化(Normalization)是一个关键步骤。Cerberus 作为 Python 中强大的数据验证库，提供了一系列规范化规则，帮助开发者对输入数据进行预处理和转换。本文将深入解析 Cerberus 中的规范化规则，包括字段重命名、未知字段清除、默认值设置和类型强制转换等核心功能。

规范化规则概述

Cerberus 的规范化规则可以应用于字段、映射结构(schema)以及批量操作中。这些规则会在验证前对数据进行预处理，按照深度优先的顺序逐层应用。

规范化规则的主要特点包括：

在验证前执行，预处理输入数据
支持多级嵌套结构的处理
提供多种规范化方式，满足不同场景需求

字段重命名规则

基本重命名

在数据处理中，有时需要将输入字段名转换为系统内部使用的名称。Cerberus 提供了简单的字段重命名功能：

v = Validator({'foo': {'rename': 'bar'}})
v.normalized({'foo': 0})  # 输出: {'bar': 0}

这种重命名会在其他规范化操作之前执行，确保后续处理使用新的字段名。

动态重命名处理器

对于更复杂的重命名需求，Cerberus 支持通过可调用对象动态处理字段名：

# 使用内置函数重命名
v = Validator({}, allow_unknown={'rename_handler': int})
v.normalized({'0': 'foo'})  # 输出: {0: 'foo'}

# 使用自定义函数链重命名
even_digits = lambda x: '0' + x if len(x) % 2 else x
v = Validator({}, allow_unknown={'rename_handler': [str, even_digits]})
v.normalized({1: 'foo'})  # 输出: {'01': 'foo'}

动态重命名处理器可以是：

单个可调用对象
可调用对象链（按顺序执行）
自定义方法名称（通过字符串引用）

清除未知字段

在数据处理中，我们经常需要过滤掉不符合预期的字段。Cerberus 提供了清除未知字段的功能：

v = Validator({'foo': {'type': 'string'}}, purge_unknown=True)
v.normalized({'bar': 'foo'})  # 输出: {}

关键点：

通过 purge_unknown 参数控制是否清除未知字段
默认值为 False，保留未知字段
可以在初始化时设置，也可以作为子文档规则
如果子文档定义了 allow_unknown 规则，则该子文档不会清除未知字段

默认值设置

静态默认值

对于可选字段，可以设置默认值：

v.schema = {
    'amount': {'type': 'integer'},
    'kind': {'type': 'string', 'default': 'purchase'}
}
v.normalized({'amount': 1})  # 输出: {'amount': 1, 'kind': 'purchase'}

特点：

当字段缺失或值为 None 时应用默认值
已有值不会被默认值覆盖
可以与只读规则结合使用

动态默认值

对于需要计算的默认值，可以使用 default_setter：

v.schema = {
    'a': {'type': 'integer'},
    'b': {'type': 'integer', 'default_setter': lambda doc: doc['a'] + 1}
}
v.normalized({'a': 1})  # 输出: {'a': 1, 'b': 2}

注意事项：

默认值设置器接收当前(子)文档作为参数
支持设置器之间的依赖关系
循环依赖会导致规范化失败

值强制转换

类型转换是数据规范化中最常用的功能之一，Cerberus 提供了灵活的强制转换机制：

# 基本类型转换
v.schema = {'amount': {'type': 'integer', 'coerce': int}}
v.validate({'amount': '1'})  # True
v.document  # {'amount': 1}

# 链式转换
to_bool = lambda v: v.lower() in ('true', '1')
v.schema = {'flag': {'type': 'boolean', 'coerce': (str, to_bool)}}
v.validate({'flag': 'true'})  # True
v.document  # {'flag': True}

转换器特点：