用途：在 Python 中用 Pydantic v2 定义、校验、序列化和配置数据。适用于声明带类型与约束的数据模型、配置对象或 DTO，编写字段级/模型级校验与自定义序列化，用 pydantic-settings 从环境变量或 .env 读取配置，用 TypeAdapter 批量校验列表、字典等非模型结构，以及把 v1 旧代码升级到 v2。不适用于 FastAPI 请求/响应接线与 response_model，也不涉及 Pydantic-AI 或 Logfire。
主要能力：BaseModel 子类以类型注解声明字段，构造时校验并强制转换，实例可通过 model_dump* 往返为 dict/JSON。用 Annotated[T, Field(...)] 添加 gt/ge/lt/le、min_length/max_length/pattern 等约束。@field_validator 做单字段校验，@model_validator 做跨字段校验。model_dump()/model_dump_json() 支持 include/exclude/exclude_unset/exclude_defaults/exclude_none/by_alias 等参数，并可用 @field_serializer、@computed_field 定制输出。model_config = ConfigDict(...) 配置 strict、from_attributes、validate_assignment、extra、frozen 等。BaseSettings 来自独立的 pydantic-settings 包，用 SettingsConfigDict 配置 env_prefix、env_file 等。枚举、Literal、可判别联合与 TypeAdapter 用于结构化类型。
必要用法：字段写作 name: Type，无默认值即必填；Optional[int] 只表示可空，不提供默认值，需显式写 = None。可变默认值用 default_factory，不要用字面量 [] 或 {}。@field_validator 下方必须紧跟 @classmethod；@model_validator(mode="after") 作用于 self，不需要。校验失败抛 ValidationError，可用 .errors()、.error_count()、.json() 读取。
限制：仅使用 v2 API，避免 class Config、.dict()、.json()、@validator、@root_validator、.parse_obj()、.schema() 等 v1 写法。TypeAdapter 不应作为 BaseModel 内的字段注解，应独立使用。默认宽松转换会把 "123" 转为 123，需要精确时设 strict=True。exclude_unset 与 exclude_defaults 语义不同，不可互换。2.11+ 建议用 validate_by_name=True 与 validate_by_alias=True 替代 populate_by_name。