NoneBot2 的 Pydantic 版本兼容层:nonebot.compat 模块深入解析

原创2026-09-27 14:28:221,645 阅读
文章标签:后端即时通讯

NoneBot2 的 Pydantic 版本兼容层:nonebot.compat 模块深入解析

nonebot.compat 是 NoneBot2 框架中面向 Pydantic V1 与 V2 两个大版本统一封装的兼容层模块,框架内部所有涉及字段定义、模型序列化与类型校验的代码都经由它间接调用 Pydantic。阅读本文后,你将掌握该模块全部公开 API 的语义、版本分支差异,以及它们在 NoneBot2 配置解析、依赖注入和消息序列化中的真实应用方式。

为什么需要 Pydantic 版本兼容层

NoneBot2 的配置系统、依赖注入体系(nonebot.dependencies)、事件模型与消息模型都深度依赖 Pydantic 的数据校验能力,而 Pydantic V2 与 V1 之间存在大量不兼容的 API 差异,例如:

  • V1 使用 model.dict()、parse_obj_as()、validator / root_validator,V2 改用 model.model_dump()、TypeAdapter、field_validator / model_validator;
  • V1 的 Field 默认值写法与 V2 的 FieldInfo 构造方式不同,V1 的 Undefined 与 V2 的 PydanticUndefined 名称不一致;
  • V1 的 ModelField 携带校验逻辑,V2 中已不存在对应公共类。

为了解决这些差异,框架在 compat.py 中集中定义了兼容函数与类,并依据运行时检测出的 Pydantic 大版本号在两条实现分支中自动切换。该模块的判定基准位于源码第 38 行:

PYDANTIC_V2 = int(VERSION.split(".", 1)[0]) == 2

即读取 pydantic.VERSION 的主版本号是否为 2,随后所有兼容 API 在 if PYDANTIC_V2: 与 else: 两个分支中各有一套实现,最终对外暴露完全一致的接口(见 compat.py 及 all 声明)。

基础常量与版本标记

PYDANTIC_V2

PYDANTIC_V2 是一个布尔常量,表示当前环境是否为 Pydantic V2。它不仅在 compat 内部驱动分支选择,也被框架其他模块直接引用,例如 event.py 与 config.py 均通过它判断运行环境,进而决定事件模型构建或配置校验的细节行为。

Required

Required = Ellipsis  # pydantic v2 分支
from pydantic.fields import Required as Required  # pydantic v1 分支

Required 是 Ellipsis(...)的别名,用于与 Pydantic V1 中“必填字段”的标记方式保持兼容。在 V1 中,字段默认值为 ... 表示该字段必填;V2 内部同样以 PydanticUndefined 表示“无默认值即必填”。compat 将两者的语义统一后,框架内声明必填字段时不再关心底层版本。

PydanticUndefined 与 PydanticUndefinedType

  • PydanticUndefined:Pydantic 中表示“字段未定义默认值”的哨兵对象,V2 分支直接重导出 pydantic_core.PydanticUndefined,V1 分支则重导出 pydantic.fields.Undefined;
  • PydanticUndefinedType:上述哨兵对象对应的类型,用于类型注解场合。

框架内部大量用它判断字段是否有默认值,例如 dependencies/init.py 中调用 field.get_default() 前依赖该语义,internal/params.py 也以 PydanticUndefined 作为参数处理中的默认值标记。

DEFAULT_CONFIG

DEFAULT_CONFIG 是 compat 提供的“默认校验配置”,其定义在两个版本分支中语义等价:

# pydantic v2
DEFAULT_CONFIG = ConfigDict(extra="allow", arbitrary_types_allowed=True)
# pydantic v1
class DEFAULT_CONFIG(ConfigDict):
    extra = Extra.allow
    arbitrary_types_allowed = True

它开放了 extra(允许额外字段)与 arbitrary_types_allowed(允许任意类型的注解),供框架内部的动态类型校验使用。测试 test_compat.py 验证了这两个取值:

def test_default_config():
    assert DEFAULT_CONFIG.get("extra") == "allow"
    assert DEFAULT_CONFIG.get("arbitrary_types_allowed") is True

字段定义:FieldInfo 与 LegacyUnionField

FieldInfo

FieldInfo 是 compat 提供的字段信息类,目标是让框架代码能以统一的写法构造字段元数据。V2 分支继承自 pydantic.fields.FieldInfo 并做了两个关键增强(compat.py):

  1. 支持位置参数传入默认值:V2 原生 FieldInfo 不允许把默认值作为位置参数,compat 版通过 def __init__(self, default: Any = PydanticUndefined, **kwargs: Any) 兼容 V1 的 FieldInfo(default) 写法;
  2. 新增 extra 属性:返回所有不属于标准 Pydantic 字段槽位(slots)的附加数据:
@property
def extra(self) -> dict[str, Any]:
    slots = super().__slots__
    return {k: v for k, v in self._attributes_set.items() if k not in slots}

这个 extra 属性正是为了兼容 V1 中 FieldInfo 允许携带任意额外元数据的习惯。测试验证了两种行为(test_compat.py):

def test_field_info():
    # required should be convert to PydanticUndefined
    assert FieldInfo(Required).default is PydanticUndefined
    # field info should allow extra attributes
    assert FieldInfo(test="test").extra["test"] == "test"

注意 V1 分支的 FieldInfo 还有一个预处理逻辑:当传入的默认值恰为 Required 时,会先转换为 PydanticUndefined,保证两个版本下“必填字段”的内部表示一致。

LegacyUnionField

LegacyUnionField 用于声明“采用旧版从左到右(left to right)联合类型匹配模式”的字段。在 Pydantic V2 中,联合类型的默认匹配策略是“智能模式”,而 V1 是从左到右依次尝试,二者对 int | str 这类声明的解析结果可能不同。V2 分支通过包装 Field 强制注入 union_mode="left_to_right"(compat.py):

def _get_legacy_union_field(func: Callable[P, T]) -> Callable[P, T]:
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
        kwargs["union_mode"] = "left_to_right"
        return func(*args, **kwargs)
    return wrapper

LegacyUnionField = _get_legacy_union_field(Field)

V1 分支则直接重导出 pydantic.fields.Field,因为 V1 天然就是从左到右匹配。框架中最典型的应用是 config.py 中的 log_level 配置项:

log_level: int | str = LegacyUnionField(default="INFO")

它允许用户配置 LOG_LEVEL=25(数字等级)或 LOG_LEVEL=INFO(等级名称)两种形式,且保证两个 Pydantic 版本下都优先按 int 尝试解析。

字段描述模型:ModelField

ModelField 是 compat 为兼容 V1 而重新提供的“字段运行时描述”类,承载字段名称、类型注解与字段元数据,并可执行取值与校验。V2 分支下它是一个全新的 dataclass(compat.py):

@dataclass
class ModelField:
    name: str                 # 字段名
    annotation: Any           # 字段类型注解
    field_info: FieldInfo     # 字段元数据

三个核心方法:

  • construct(name, annotation, field_info=None)(类方法):根据给定信息构造 ModelField,未提供 field_info 时自动使用空的 FieldInfo()。V1 分支还会额外调用 get_annotation_from_field_info 将字段信息预处理进注解中。此外该类重写了 __hash__ 为基于对象 id,便于放入集合去重;
  • get_default():获取字段默认值。V2 分支实现为 self.field_info.get_default(call_default_factory=True),即会主动调用默认值工厂函数;V1 分支则直接读取字段的 default / default_factory;
  • validate_value(value):校验传入值。V2 分支通过缓存的 TypeAdapter 调用 validate_python,其中 type_adapter 是一个 cached_property,源码注释说明缓存是为了避免 Pydantic V2 创建 TypeAdapter 的高 CPU 开销(参见 compat.py);V1 分支则调用底层 self.validate(value, {}, loc=()),校验失败时抛出 ValueError。

ModelField 是框架依赖注入体系的地基:参数解析器在 internal/params.py 中用 ModelField.construct(...) 为函数参数构造校验器,而 dependencies/utils.py 中的 check_field_type 则调用 field.validate_value(value) 完成类型检查:

def check_field_type(field: ModelField, value: Any) -> Any:
    try:
        return field.validate_value(value)
    except ValueError:
        raise TypeMisMatch(field, value)

模型操作函数:model_fields、model_config、model_dump

model_fields(model)

返回模型的字段列表,统一为 list[ModelField]:

# pydantic v2
return [
    ModelField._construct(
        name=name,
        annotation=field_info.rebuild_annotation(),
        field_info=FieldInfo._inherit_construct(field_info),
    )
    for name, field_info in model.model_fields.items()
]
# pydantic v1
return [
    ModelField._construct(
        name=model_field.name,
        annotation=model_field.annotation,
        field_info=FieldInfo._inherit_construct(model_field.field_info),
    )
    for model_field in model.__fields__.values()
]

V2 分支会调用 rebuild_annotation() 解析前向引用,并通过 FieldInfo._inherit_construct 继承原字段的全部属性;V1 分支则直接复用 model.__fields__ 中的字段信息。框架在 config.py 与 config.py 中用它枚举配置模型的全部字段,以决定每个配置项从何种来源取值。

model_config(model)

获取模型的配置对象:V2 返回 model.model_config,V1 返回 model.__config__。它被 BaseSettingsSource 用于读取 extra 等配置行为(config.py)。

model_dump(model, ...)

将模型实例序列化为字典,签名与两种版本的语义严格对齐:

def model_dump(
    model: BaseModel,
    include: ModelDumpIncEx = None,
    exclude: ModelDumpIncEx = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
) -> dict[str, Any]
  • include / exclude:支持 set[str]、set[int] 以及嵌套的 dict 形式,可精确控制包含或排除的字段,甚至能按 {"nested": {"hidden"}} 或 {"items": {"__all__": {"hidden"}}} 深入嵌套结构与列表元素;
  • by_alias:是否使用字段别名作为输出键;
  • exclude_unset:排除未被显式设置的字段;
  • exclude_defaults:排除值与默认值相同的字段;
  • exclude_none:排除值为 None 的字段。

底层实现分别为 V2 的 model.model_dump(...) 与 V1 的 model.dict(...)。测试 test_compat.py 用嵌套模型全面验证了 include/exclude 的组合行为。该函数被框架广泛用于序列化事件与消息数据,例如 init.py、drivers/fastapi.py、drivers/quart.py 与 plugin/init.py。

类型校验函数:type_validate_python 与 type_validate_json

这两个函数是框架内最常用的“快速校验”入口:

  • type_validate_python(type_, data) -> T:以给定类型校验 Python 对象。V2 实现为 TypeAdapter(type_).validate_python(data),V1 实现为 parse_obj_as(type_, data);
  • type_validate_json(type_, data: str | bytes) -> T:以给定类型校验 JSON 字符串/字节。V2 实现为 TypeAdapter(type_).validate_json(data),V1 实现为 parse_raw_as(type_, data)。

框架中典型应用包括:消息段与消息数组在 internal/adapter/message.py 中的类型校验、utils.py 与 test_adapters 中的数据类型转换。测试 test_compat.py 验证了复杂 JSON 的完整解析:

assert type_validate_json(
    TestModel,
    '{ "test1": 1, "test2": "2", "test3": true, "test4": {}, "test5": [], "test6": null }',
) == TestModel(test1=1, test2="2", test3=True, test4={}, test5=[], test6=None)

装饰器与校验器兼容层

原文档之外,compat 模块还通过 __all__ 对外暴露了几组在 V1/V2 间语义等价的装饰器与类型工具,是框架编写版本无关校验逻辑的关键补充:

  • field_validator(field, *fields, mode="after", check_fields=None):字段校验器。V1 分支将其翻译为 validator(..., pre=..., allow_reuse=True),默认 mode="after",mode="before" 对应 pre=True;
  • model_validator(*, mode):模型级校验器。V1 分支将 before / after 分别映射为 root_validator(pre=True) 与 root_validator(skip_on_failure=True);
  • TypeAdapter:类型适配器。V2 直接重导出 pydantic.TypeAdapter,V1 分支提供实现了 validate_python / validate_json 的最小等价类;
  • ConfigDict:V1 分支提供支持 get(field, default) 默认值读取的配置类,V2 分支重导出 pydantic.ConfigDict。

测试 test_compat.py 演示了在同一个模型上混用 mode="after" 与 mode="before" 校验器并在两个版本下得到一致行为;test_compat.py 则验证了 model_validator 的 before/after 语义。

custom_validation:让 V1 风格校验器在 V2 中继续工作

custom_validation(class_) 装饰器解决的是“Pydantic V1 风格的 __get_validators__ 类方法在 V2 中失效”的问题。V2 分支会为类注入 __get_pydantic_core_schema__ 类方法(compat.py),把 V1 的校验器生成器转换为 V2 的 Core Schema:单个校验器包装为 no_info_plain_validator_function,多个校验器则串联为 chain_schema;V1 分支则原样返回(V1 原生支持该协议,无需处理)。

custom_validation 是消息模型校验能力的核心支撑——internal/adapter/message.py 中 MessageSegment 与 Message 都带有 @custom_validation 装饰器,并定义 __get_validators__ 生成 _validate 校验器,使事件上报中的消息数据能够被 Pydantic 正确反序列化为消息对象。测试 test_compat.py 验证了多级校验器的执行顺序:

@custom_validation
@dataclass
class TestModel:
    test: int

    @classmethod
    def __get_validators__(cls):
        yield cls._validate_1
        yield cls._validate_2
    ...
assert type_validate_python(TestModel, {"test": 1}) == TestModel(test=1)
assert called == [1, 2]

兼容层在框架中的整体应用链路

汇总源码中的引用点,可以看到 compat 模块覆盖了 NoneBot2 的核心运行链路:

应用场景 使用的 compat API 引用位置
配置模型定义与解析 PYDANTIC_V2、LegacyUnionField、model_config、model_fields、ConfigDict config.py
依赖注入与参数校验 FieldInfo、ModelField、PydanticUndefined dependencies/init.py、internal/params.py
字段类型检查 ModelField.validate_value dependencies/utils.py
消息与消息段反序列化 custom_validation、type_validate_python internal/adapter/message.py
事件模型构建 PYDANTIC_V2、ConfigDict internal/adapter/event.py
驱动与插件数据序列化 model_dump、type_validate_python drivers/fastapi.py、plugin/init.py
启动初始化 model_dump init.py

可见,只要底层 Pydantic 升级或降级,NoneBot2 只需维护 compat.py 这一处适配代码,其余模块无需感知版本差异。对于插件开发者,如果需要在插件中编写与 NoneBot2 相同健壮性的 Pydantic 兼容代码,直接 from nonebot.compat import ... 复用这些 API 即可,而不必自行做版本分支判断。

小结

nonebot.compat 通过约 500 行的双分支实现,将 Pydantic V1/V2 的字段定义、字段描述、模型操作、类型校验与校验器注册五大能力统一为一致接口,并以 PYDANTIC_V2 常量作为运行时判定依据。理解该模块,有助于深入把握 NoneBot2 配置系统、依赖注入与消息序列化的底层机制,也能为你在插件或适配器中编写跨版本可靠的校验逻辑提供现成的最佳实践。

登录后查看全文
nonebot2