from pydantic import Field，有什么用？

🤖 Assistant

pydantic.fields.Field 函数主要用于自定义和向 Pydantic 模型字段添加元数据和验证约束。它允许开发者对字段的默认值、别名、数值范围、字符串长度、数据类特性、JSON Schema 表示等进行详细配置。

Field 的使用方式

需要从 pydantic 库中导入 Field。通常在定义 Pydantic 模型时，将其赋值给模型字段的类型注解：

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(...) # ... 表示该字段必填
    age: int = Field(default=18, ge=0, le=120) # 带有默认值和数值约束

Field 的主要参数及其作用

Field 接受的参数非常多，以下是一些常用参数及其作用：

1. default / default_factory

• default: 用于为字段定义一个默认值。如果创建模型时未提供该字段的值，则使用此默认值。例如：name: str = Field(default='John Doe')。
• default_factory: 用于定义一个可调用的函数，该函数在需要时被调用以生成默认值。这在默认值是可变类型（如列表、字典）或需要在运行时动态生成（如 uuid、当前时间）时非常有用，以避免所有模型实例共享同一个可变默认值。例如：id: str = Field(default_factory=lambda: uuid4().hex)。
• 注意: default 和 default_factory 参数是互斥的，不能同时使用。

2. 别名 (alias, validation_alias, serialization_alias)

• alias: 为字段定义一个别名，用于验证和序列化。这意味着在创建模型实例时可以使用别名，在导出模型时也可以使用别名。
  例如：name: str = Field(..., alias='username')。在创建 User 实例时，可以使用 User(username='johndoe')。
• validation_alias: 仅用于验证的别名。模型创建时使用此别名，但序列化时仍使用字段本身的名称。
• serialization_alias: 仅用于序列化的别名。模型创建时使用字段本身的名称，但序列化时使用此别名。
• 优先级: 如果同时使用 alias 与 validation_alias 或 serialization_alias，则 validation_alias 在验证方面优先于 alias，serialization_alias 在序列化方面优先于 alias。

3. 数值约束 (gt, lt, ge, le, multiple_of, allow_inf_nan)

• gt: Greater Than，严格大于某个值。在 JSON Schema 中转换为 exclusiveMinimum。
• lt: Less Than，严格小于某个值。在 JSON Schema 中转换为 exclusiveMaximum。
• ge: Greater or Equal，大于或等于某个值。在 JSON Schema 中转换为 minimum。
• le: Less or Equal，小于或等于某个值。在 JSON Schema 中转换为 maximum。
• multiple_of: 要求字段值是给定数字的倍数。在 JSON Schema 中转换为 multipleOf。
• allow_inf_nan: 允许浮点数使用 'inf'、'-inf'、'nan' 值。

4. 字符串约束 (min_length, max_length, pattern)

• min_length: 字符串的最小长度。在 JSON Schema 中转换为 minLength。
• max_length: 字符串的最大长度。在 JSON Schema 中转换为 maxLength。
• pattern: 字符串必须匹配的正则表达式。在 JSON Schema 中转换为 pattern。

5. 小数约束 (max_digits, decimal_places)

• max_digits: Decimal 类型字段的最大数字位数（不包括小数点前的零或尾随的小数零）。
• decimal_places: 允许的最大小数位数（不包括尾随的小数零）。

6. 数据类约束 (init, init_var, kw_only)

• init: 控制该字段是否应包含在数据类的 __init__ 中。
• init_var: 控制该字段是否应在数据类中被视为仅初始化字段。
• kw_only: 控制该字段是否应在数据类构造函数中成为仅限关键字的参数。

7. 验证默认值 (validate_default)

• validate_default: 默认情况下，字段的默认值不进行验证。设置为 True 时，会验证默认值是否符合字段的类型和约束。

8. 字段表示 (repr)

• repr: 控制该字段是否应包含在模型的字符串表示中（例如当 print(model_instance) 时）。

9. 鉴别器 (discriminator)

• discriminator: 用于联合类型（Union）中区分不同模型。它可以是字段名称或 Discriminator 实例。

10. 严格模式 (strict)

• strict: 指定该字段是否应在“严格模式”下进行验证。在严格模式下，Pydantic 在验证期间会引发错误，而不是对数据进行强制类型转换。

11. 不变性 (frozen)

• frozen: 模拟冻结数据类的行为。设置为 True 可防止在创建模型后为字段分配新的值（使字段不可变）。

12. 排除 (exclude)

• exclude: 用于控制在导出模型（如 model_dump()）时应从模型中排除哪些字段。

13. 已弃用字段 (deprecated)

• deprecated: 用于将字段标记为已弃用。访问该字段时会发出运行时弃用警告，并在生成的 JSON Schema 中设置 "deprecated": true。可以设置为字符串（作为弃用消息）、warnings.deprecated 装饰器实例或布尔值。

14. 自定义 JSON Schema (title, description, examples, json_schema_extra)

• 这些参数专门用于自定义生成的 JSON Schema。例如，title 设置字段标题，description 设置字段描述，examples 提供字段示例值。这些元数据在自动生成 API 文档（如 OpenAPI/Swagger UI）时非常有用。

通过这些参数，pydantic.fields.Field 提供了强大的能力来精细控制模型字段的行为、验证逻辑和文档表示。