I. `msgspec.Struct` — High-Performance Typed Data Structures#

Overview: msgspec.Struct is a high-performance (高性能), type-safe (类型安全) data class alternative from the msgspec library. It is designed as a faster, leaner replacement for Python dataclasses, attrs, and Pydantic models — with native support for JSON / MessagePack serialization (序列化) and validation (验证) baked in at the C level.

1. Installation & Import#

1
pip install msgspec
2
import msgspec
3
from msgspec import Struct, field

2. Defining a Struct (定义结构体)#

1) Basic Definition#

1
from msgspec import Struct
2

3
class Point(Struct):
4
    x: float
5
    y: float
6

7
p = Point(x=1.0, y=2.0)
8
print(p)        # Point(x=1.0, y=2.0)
9
print(p.x)      # 1.0

Note: Unlike Python dataclasses, Struct instances are immutable by default (默认不可变) and implemented in C — construction and attribute access are significantly faster.

2) Fields with Default Values (默认值)#

1
class User(Struct):
2
    name: str
3
    age: int = 0
4
    active: bool = True
5

6
u = User(name="Alice")
7
print(u)   # User(name='Alice', age=0, active=True)

3) `field()` — Advanced Field Configuration#

1
from msgspec import Struct, field
2

3
class Config(Struct):
4
    tags: list[str] = field(default_factory=list)   # Mutable default
5
    name: str = field(default="unnamed")

Note: Never use a mutable object (list, dict) directly as a default value. Use field(default_factory=list) instead — just like with Python dataclasses.

4) Nested Structs (嵌套结构体)#

1
class Address(Struct):
2
    city: str
3
    country: str
4

5
class Person(Struct):
6
    name: str
7
    address: Address
8

9
p = Person(name="Bob", address=Address(city="NYC", country="US"))
10
print(p.address.city)   # NYC

3. Struct Configuration Options (结构体配置)#

Pass options to the class definition via keyword arguments:

1
class MyStruct(Struct, frozen=True, order=True, eq=True, kw_only=True):
2
    x: int
3
    y: int

1) Option Reference Table#

Option	Default	Effect
`frozen=True`	`False`	Makes the struct immutable (不可变) — fields cannot be reassigned after creation
`order=True`	`False`	Enables `<`, `>`, `<=`, `>=` comparison operators
`eq=True`	`True`	Enables `==` / `!=` based on field values
`kw_only=True`	`False`	All fields must be passed as keyword arguments
`array_like=True`	`False`	Serializes as a JSON array `[...]` instead of object `{...}`
`gc=False`	`True`	Disables garbage collector tracking — faster for structs with no reference cycles
`weakref=True`	`False`	Enables weak references to the struct instance
`rename`	`None`	Rename fields during (de)serialization — e.g., `rename="camel"`
`tag`	`None`	Adds a type tag for tagged unions (标签联合)
`tag_field`	`"type"`	The field name used to store the tag value

2) `frozen=True` — Immutable Struct#

1
class ImmutablePoint(Struct, frozen=True):
2
    x: float
3
    y: float
4

5
p = ImmutablePoint(x=1.0, y=2.0)
6
p.x = 99.0   # ❌ TypeError: immutable type

Scenario: Configuration objects, cache keys, value objects (值对象) that should never change.

3) `order=True` — Sortable Structs#

1
class Version(Struct, order=True):
2
    major: int
3
    minor: int
4
    patch: int
5

6
versions = [Version(1, 2, 0), Version(1, 0, 5), Version(2, 0, 0)]
7
print(sorted(versions))
8
# [Version(1,0,5), Version(1,2,0), Version(2,0,0)]

Scenario: Sorting records, priority queues, range comparisons.

4) `rename="camel"` — Field Name Mapping#

1
class ApiResponse(Struct, rename="camel"):
2
    user_name: str
3
    created_at: str
4

5
import msgspec
6
obj = ApiResponse(user_name="Alice", created_at="2025-01-01")
7
print(msgspec.json.encode(obj))
8
# b'{"userName":"Alice","createdAt":"2025-01-01"}'

`rename` value	Effect
`”camel”`	`user_name` → `userName`
`”pascal”`	`user_name` → `UserName`
`”lower”`	`userName` → `username`
`dict`	Explicit per-field mapping

Scenario: Interoperating with REST APIs that use camelCase JSON keys.

4. Serialization & Deserialization (序列化与反序列化)#

1) JSON Encoding#

1
import msgspec
2

3
class Order(Struct):
4
    id: int
5
    item: str
6
    price: float
7

8
order = Order(id=1, item="book", price=9.99)
9

10
# Encode to JSON bytes
11
data = msgspec.json.encode(order)
12
print(data)   # b'{"id":1,"item":"book","price":9.99}'

2) JSON Decoding with Type Validation#

1
# Decode + validate in one step
2
order2 = msgspec.json.decode(data, type=Order)
3
print(order2)          # Order(id=1, item='book', price=9.99)
4
print(order2 == order) # True

Note: msgspec.json.decode() performs schema validation (模式验证) at decode time. If the JSON does not match the expected type, it raises msgspec.ValidationError with a descriptive message.

3) MessagePack Encoding (二进制序列化)#

1
# Encode to binary MessagePack
2
binary = msgspec.msgpack.encode(order)
3
print(binary)   # b'\x83\xa2id\x01\xa4item\xa4book\xa5price\xcb@#\xeb...'
4

5
# Decode from binary
6
order3 = msgspec.msgpack.decode(binary, type=Order)

Format	Function	Output
JSON	`msgspec.json.encode/decode`	Human-readable bytes
MessagePack	`msgspec.msgpack.encode/decode`	Compact binary

4) `array_like=True` — Array Serialization#

1
class Point(Struct, array_like=True):
2
    x: float
3
    y: float
4

5
p = Point(1.0, 2.0)
6
print(msgspec.json.encode(p))   # b'[1.0,2.0]'

Scenario: Compact serialization for large volumes of records (matrices, time series, coordinate data).

5) Handling Validation Errors#

1
bad_json = b'{"id": "not-a-number", "item": "book", "price": 9.99}'
2

3
try:
4
    msgspec.json.decode(bad_json, type=Order)
5
except msgspec.ValidationError as e:
6
    print(e)
7
    # Expected `int`, got `str` - at `$.id`

5. Type Annotations & Supported Types (类型注解)#

1) Built-in Types#

1
class Example(Struct):
2
    a: int
3
    b: float
4
    c: str
5
    d: bool
6
    e: bytes
7
    f: None

2) Collections (集合类型)#

1
from typing import Optional
2

3
class Collections(Struct):
4
    items: list[str]
5
    mapping: dict[str, int]
6
    pair: tuple[int, str]
7
    unique: set[int]
8
    maybe: Optional[str] = None        # str | None

3) `Optional` and `Union` Types#

1
from typing import Union
2

3
class Response(Struct):
4
    data: Union[str, int, None]        # Can be str, int, or None
5
    error: str | None = None           # Python 3.10+ shorthand

4) `Literal` Types — Constrained Values (约束值)#

1
from typing import Literal
2

3
class Status(Struct):
4
    state: Literal["pending", "running", "done", "failed"]
5

6
s = Status(state="running")
7
msgspec.json.decode(b'{"state":"invalid"}', type=Status)
8
# ❌ ValidationError: Expected one of 'pending', 'running', 'done', 'failed'

Scenario: Enforcing valid enum-like values without a full Enum class.

5) `datetime`, `UUID`, `Decimal`#

1
from datetime import datetime
2
from uuid import UUID
3
from decimal import Decimal
4

5
class Event(Struct):
6
    id: UUID
7
    timestamp: datetime
8
    amount: Decimal

Note: datetime is serialized as an ISO 8601 string. UUID as a string. Decimal as a JSON number string.

6. Tagged Unions (标签联合) — Polymorphic Types#

1) Defining a Tagged Union#

Use tag=True (or a custom tag string) to enable discriminated unions (判别联合):

1
from typing import Union
2

3
class Cat(Struct, tag=True):
4
    name: str
5
    indoor: bool
6

7
class Dog(Struct, tag=True):
8
    name: str
9
    breed: str
10

11
Animal = Union[Cat, Dog]

When serialized, a "type" field is added automatically:

1
cat = Cat(name="Whiskers", indoor=True)
2
print(msgspec.json.encode(cat))
3
# b'{"type":"Cat","name":"Whiskers","indoor":true}'
4

5
dog = Dog(name="Rex", breed="Husky")
6
print(msgspec.json.encode(dog))
7
# b'{"type":"Dog","name":"Rex","breed":"Husky"}'

2) Decoding a Tagged Union#

1
data = b'{"type":"Dog","name":"Rex","breed":"Husky"}'
2
animal = msgspec.json.decode(data, type=Animal)
3
print(type(animal))   # <class 'Dog'>
4
print(animal.breed)   # Husky

Scenario: Event systems, polymorphic API responses, command/event patterns where the same endpoint can return different shapes.

3) Custom Tag Values#

1
class Circle(Struct, tag="circle"):
2
    radius: float
3

4
class Rectangle(Struct, tag="rect"):
5
    width: float
6
    height: float
7

8
Shape = Union[Circle, Rectangle]
9

10
c = Circle(radius=5.0)
11
print(msgspec.json.encode(c))
12
# b'{"type":"circle","radius":5.0}'

7. Utility Methods (工具方法)#

1) `msgspec.structs.asdict()` — Convert to Dict#

1
from msgspec import structs
2

3
p = Point(x=1.0, y=2.0)
4
d = structs.asdict(p)
5
print(d)   # {'x': 1.0, 'y': 2.0}

2) `msgspec.structs.astuple()` — Convert to Tuple#

1
t = structs.astuple(p)
2
print(t)   # (1.0, 2.0)

3) `msgspec.structs.replace()` — Copy with Changes#

Like dataclasses.replace() — creates a new instance with some fields updated:

1
p2 = structs.replace(p, x=99.0)
2
print(p2)   # Point(x=99.0, y=2.0)
3
print(p)    # Point(x=1.0, y=2.0)  ← original unchanged

Scenario: Immutable update patterns (不可变更新模式) — create a modified copy without mutating the original.

4) `msgspec.structs.fields()` — Inspect Field Definitions#

1
for f in structs.fields(Point):
2
    print(f.name, f.type, f.default)
3
# x  <class 'float'>  NODEFAULT
4
# y  <class 'float'>  NODEFAULT

Scenario: Writing generic serializers, validators, or introspection tools.

8. Inheritance (继承)#

1
class Animal(Struct):
2
    name: str
3
    age: int
4

5
class Dog(Animal):
6
    breed: str
7

8
d = Dog(name="Rex", age=3, breed="Husky")
9
print(d)   # Dog(name='Rex', age=3, breed='Husky')

Note: A child Struct cannot override a field defined in the parent. Fields defined in the parent always come first in the constructor signature.

9. Performance Comparison (性能对比)#

Library	Construct	JSON Encode	JSON Decode+Validate
msgspec.Struct	⚡ Fastest	⚡ Fastest	⚡ Fastest
`dataclasses`	Fast	Needs `json.dumps`	No validation
`attrs`	Fast	Needs extra lib	No validation
`pydantic v2`	Medium	Fast	Fast (Rust core)
`pydantic v1`	Slow	Slow	Slow

Note: In benchmarks, msgspec is typically 5–10× faster than Pydantic v1 and 2–3× faster than Pydantic v2 for both encoding and decoding, while using significantly less memory.

10. Real-World Scenarios (实战场景)#

1) FastAPI / HTTP API Request/Response Models#

1
from msgspec import Struct
2
import msgspec
3

4
class CreateUserRequest(Struct):
5
    username: str
6
    email: str
7
    age: int | None = None
8

9
class UserResponse(Struct):
10
    id: int
11
    username: str
12
    email: str
13

14
# Decoding incoming JSON body
15
body = b'{"username":"alice","email":"alice@example.com"}'
16
req = msgspec.json.decode(body, type=CreateUserRequest)
17

18
# Encoding outgoing response
19
resp = UserResponse(id=42, username=req.username, email=req.email)
20
print(msgspec.json.encode(resp))
21
# b'{"id":42,"username":"alice","email":"alice@example.com"}'

2) Config File Parsing with Validation#

1
import msgspec
2
from msgspec import Struct
3
from typing import Literal
4

5
class ServerConfig(Struct):
6
    host: str = "0.0.0.0"
7
    port: int = 8080
8
    mode: Literal["debug", "production"] = "production"
9
    workers: int = 4
10

11
config_json = b'{"host":"127.0.0.1","port":9000,"mode":"debug"}'
12
config = msgspec.json.decode(config_json, type=ServerConfig)
13
print(config.mode)   # debug

3) High-throughput MessagePack Messaging (e.g., vLLM, message queues)#

1
class InferenceRequest(Struct):
2
    request_id: str
3
    prompt: str
4
    max_tokens: int = 512
5
    temperature: float = 1.0
6

7
class InferenceResponse(Struct):
8
    request_id: str
9
    output: str
10
    finish_reason: Literal["stop", "length", "error"]
11

12
# Fast binary serialization for IPC / queue transport
13
req = InferenceRequest(request_id="req-001", prompt="Hello!")
14
binary = msgspec.msgpack.encode(req)
15

16
resp_data = msgspec.msgpack.decode(binary, type=InferenceRequest)

4) Event / Command Pattern with Tagged Unions#

1
from typing import Union
2
from msgspec import Struct
3
import msgspec
4

5
class StartJob(Struct, tag=True):
6
    job_id: str
7
    config: dict
8

9
class StopJob(Struct, tag=True):
10
    job_id: str
11
    reason: str
12

13
Command = Union[StartJob, StopJob]
14

15
# Dispatcher
16
def handle(data: bytes):
17
    cmd = msgspec.json.decode(data, type=Command)
18
    if isinstance(cmd, StartJob):
19
        print(f"Starting job {cmd.job_id}")
20
    elif isinstance(cmd, StopJob):
21
        print(f"Stopping job {cmd.job_id}: {cmd.reason}")
22

23
handle(b'{"type":"StartJob","job_id":"abc","config":{}}')
24
# Starting job abc

💡 One-line Takeaway
msgspec.Struct gives you the ergonomics of a dataclass, the validation of Pydantic, and the serialization speed of hand-written C — use frozen=True for immutable value objects, tag=True for polymorphic types, and rename="camel" for seamless REST API integration.

I. msgspec.Struct — High-Performance Typed Data Structures#