msgspec转换器详解：实现自定义协议支持-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00663/article/details/148757929

msgspec转换器详解：实现自定义协议支持

msgspec A fast serialization and validation library, with builtin support for JSON, MessagePack, YAML, and TOML 项目地址: https://gitcode.com/gh_mirrors/ms/msgspec

概述

msgspec是一个高效的Python数据序列化库，它内置了对JSON、MessagePack、YAML和TOML等常见协议的支持。但它的强大之处在于提供了灵活的转换器机制，允许开发者轻松扩展对其他协议的支持。本文将深入解析msgspec中的两个核心转换函数：to_builtins和convert，以及如何利用它们实现自定义协议的编解码。

核心转换函数

1. to_builtins函数

to_builtins函数的作用是将复杂的数据结构转换为仅包含Python基本类型的结构。它接受任何msgspec支持的类型，输出只包含以下基本类型的数据：

基础类型：str, int, float, bool, None
容器类型：dict, list, tuple, set, frozenset

这个函数通常在序列化前使用，将高级数据结构"扁平化"为序列化库能够处理的简单结构。

2. convert函数

convert函数则执行相反的操作，它将基本类型的数据结构转换为符合指定类型模式的高级结构。在转换过程中会进行类型验证，如果数据与模式不匹配，会抛出清晰的错误信息。

这个函数通常在反序列化后使用，将原始数据重新构造为具有明确类型的高级数据结构。

实际应用示例

实现JSON编解码

虽然msgspec已经内置了JSON支持，但我们可以通过以下方式自行实现：

import json
from typing import Any
import msgspec

def encode(obj):
    """将对象编码为JSON字符串"""
    return json.dumps(msgspec.to_builtins(obj))

def decode(msg, type=Any):
    """将JSON字符串解码为指定类型的对象"""
    return msgspec.convert(json.loads(msg), type=type)

使用示例：

class Point(msgspec.Struct):
    x: int
    y: int

# 编码
point = Point(1, 2)
json_str = encode(point)  # 结果为 '{"x": 1, "y": 2}'

# 解码
restored_point = decode(json_str, type=Point)  # 返回Point对象

实现TOML编解码

TOML协议有一些特殊要求：

原生支持datetime相关类型
只支持字符串作为字典键

实现方式如下：

import datetime
import tomllib
from typing import Any
import msgspec

def decode_toml(msg, *, type=Any, dec_hook=None):
    return msgspec.convert(
        tomllib.loads(msg),
        type,
        builtin_types=(datetime.datetime, datetime.date, datetime.time),
        str_keys=True,
        dec_hook=dec_hook,
    )

高级配置选项

这两个转换函数提供了一些有用的配置选项：

builtin_types：指定额外被视为基本类型的类型集合
str_keys：设置为True表示目标协议只支持字符串键
strict：控制类型转换的严格程度
- True（默认）：严格模式，类型必须精确匹配
- False：宽松模式，允许更多自动类型转换（如字符串到数字）
from_attributes：是否允许从对象属性构造结构化类型
enc_hook/dec_hook：用于扩展支持的自定义类型的钩子函数