Back to Details

pydantic

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

pydantic

Pydantic

Type-driven validation and serialization using Pydantic models.
基于Pydantic模型的类型驱动验证与序列化。

Overview

概述

Pydantic validates data using Python type hints and provides rich serialization via 
model_dump()
and JSON schema output.
Pydantic 利用Python类型提示验证数据，并通过
model_dump()
方法和JSON Schema输出提供丰富的序列化功能。

When to Use

适用场景

  • Validating request/response payloads
  • Normalizing untrusted input
  • Generating JSON schema for docs
  • 验证请求/响应负载
  • 规范化不可信输入数据
  • 为文档生成JSON Schema

Quick Start

快速开始

bash
uv pip install pydantic
python
from pydantic import BaseModel

class User(BaseModel):
    id: int
    email: str

user = User(id=1, email="a@example.com")
bash
uv pip install pydantic
python
from pydantic import BaseModel

class User(BaseModel):
    id: int
    email: str

user = User(id=1, email="a@example.com")

Core Patterns

核心模式

  1. Typed fields: strict schema definitions.
  2. Field validators: custom validation logic.
  3. Model validators: cross-field checks.
  4. Serialization: 
    model_dump()
    and 
    model_dump_json()
    .
  5. Settings: environment-driven config via 
    BaseSettings
    .
  1. 类型化字段：严格的数据模式定义。
  2. 字段验证器：自定义验证逻辑。
  3. 模型验证器：跨字段检查。
  4. 序列化：
    model_dump()
    和
    model_dump_json()
    方法。
  5. 配置管理：通过
    BaseSettings
    实现基于环境的配置。

Example: field_validator

示例：field_validator

python
from pydantic import BaseModel, field_validator

class Model(BaseModel):
    name: str

    @field_validator("name")
    @classmethod
    def ensure_not_empty(cls, v: str):
        if not v:
            raise ValueError("name required")
        return v
python
from pydantic import BaseModel, field_validator

class Model(BaseModel):
    name: str

    @field_validator("name")
    @classmethod
    def ensure_not_empty(cls, v: str):
        if not v:
            raise ValueError("name required")
        return v

Example: model_validate + model_dump

示例：model_validate + model_dump

python
from pydantic import BaseModel

class Model(BaseModel):
    foo: int

model = Model.model_validate({"foo": 1})
print(model.model_dump())
python
from pydantic import BaseModel

class Model(BaseModel):
    foo: int

model = Model.model_validate({"foo": 1})
print(model.model_dump())

Troubleshooting

问题排查

  • Coercion surprises: use strict types if needed
  • Slow validators: keep them minimal
  • Mutable defaults: use 
    default_factory
  • 类型转换异常：必要时使用严格类型
  • 验证器性能低下：尽量简化验证逻辑
  • 可变默认值问题：使用
    default_factory

References

参考资料