深入理解msgspec中的Struct结构体-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00782/article/details/148757970

深入理解msgspec中的Struct结构体

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数据序列化库，其中的Struct结构体是其核心特性之一。Struct提供了一种高效定义结构化数据类型的方式，在性能上显著优于Python中常见的dataclasses、attrs和pydantic等方案。

Struct基础用法

定义Struct

Struct通过继承msgspec.Struct类并使用类型注解来定义字段：

import msgspec
from typing import Set, Optional

class User(msgspec.Struct):
    """用户结构体"""
    name: str           # 必填字段
    email: Optional[str] = None  # 可选字段，默认为None
    groups: Set[str] = set()    # 可选字段，默认为空集合

自动生成的方法

Struct类型会自动生成以下方法：

__init__：初始化方法
__repr__：对象表示
__copy__：浅拷贝
__replace__：创建修改后的副本
__eq__和__ne__：相等性比较
__match_args__：支持Python 3.10+的模式匹配
__rich_repr__：支持rich库的漂亮打印

高级特性

默认值设置

Struct支持三种默认值设置方式：

静态默认值：直接赋值

class Example(msgspec.Struct):
    a: int = 1

动态默认值：使用default_factory

import uuid
from msgspec import field

class Example(msgspec.Struct):
    b: uuid.UUID = field(default_factory=uuid.uuid4)

空可变集合：自动转换为default_factory

class Example(msgspec.Struct):
    c: list[int] = []  # 等价于field(default_factory=list)

初始化后处理

可以通过__post_init__方法添加初始化后逻辑：

class Interval(msgspec.Struct):
    low: float
    high: float
    
    def __post_init__(self):
        if self.low > self.high:
            raise ValueError("low不能大于high")

字段顺序控制

Struct字段默认按定义顺序排列，但可以通过kw_only=True改为关键字参数：

class Example(msgspec.Struct, kw_only=True):
    a: str = ""
    b: int  # 现在可以放在有默认值的字段后面

类型验证

Struct的类型验证主要在反序列化时进行：

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

# 直接创建时不验证类型
p = Point(x=1, y="oops")  # 不会报错

# 反序列化时会验证类型
msgspec.json.decode(b'{"x":1,"y":"oops"}', type=Point)  # 会报错

模式匹配(Python 3.10+)

Struct支持Python 3.10的模式匹配：

def where_is(point):
    match point:
        case Point(0, 0):
            print("原点")
        case Point(0, y):
            print(f"Y={y}")
        case _:
            print("其他位置")

相等性与排序

默认支持相等性比较，可通过order=True启用排序：

class Point(msgspec.Struct, order=True):
    x: float
    y: float

不可变实例

使用frozen=True创建不可变实例：

class Point(msgspec.Struct, frozen=True):
    x: float
    y: float

标记联合(Tagged Unions)

用于处理多种可能类型的字段：

class Get(msgspec.Struct, tag=True):
    key: str

class Put(msgspec.Struct, tag=True):
    key: str
    val: str

# 解码时自动识别类型
dec = msgspec.json.Decoder(Union[Get, Put])