字段(Field)

基本定义:
在 pydantic 模型里，字段指的是类中定义的属性，它们代表了数据模型的各个组成部分。每个字段都有特定的数据类型和可能的验证规则。在 CaseStage 类中，以下这些就是定义的字段：
1
2
3
4
preparation_stage : List[str]#preparation就是字段
setup_stage : List[str]
execution_stage : List[str]
post_stage : List[str]
这些字段规定了 CaseStage 实例所应包含的数据结构。例如，preparation_stage 字段要求其值是一个字符串列表，用来存储刷单准备阶段的行为。

原始名称(Original Name)

基本定义：

原始名称即字段在类定义中所使用的名称。在 CaseStage 类里，preparation_stage、setup_stage、execution_stage 和 post_stage 就是这些字段的原始名称。在代码中直接引用这些字段时，使用的就是原始名称。例如：

from pydantic import BaseModel, Field
from typing import List
from pydantic.config import ConfigDict

class CaseStage(BaseModel):
    model_config = ConfigDict(populate_by_name = True)
    preparation_stage : List[str] = Field(description="刷单准备阶段行为列表",alias="准备阶段")
    setup_stage : List[str] = Field(description="刷单事前准备行为列表",alias="事前阶段")
    execution_stage : List[str] = Field(description="刷单实施阶段行为列表",alias="实施阶段")
    post_stage : List[str] = Field(description="刷单事后处理行为列表",alias="事后阶段")

# 使用原始名称创建实例
case = CaseStage(
    preparation_stage=["招募刷手", "创建虚假账户"],
    setup_stage=["测试系统漏洞", "建立资金通道"],
    execution_stage=["虚构交易记录", "伪造物流信息"],
    post_stage=["销毁电子证据", "转移资金"]
)

在上述代码中，preparation_stage、setup_stage、execution_stage 和 post_stage 就是在创建 CaseStage 实例时使用的原始名称。

别名(Alias)

别名是通过 Field 函数的 alias 参数为字段设置的另一个名称。设置别名的目的通常是为了增强代码的可读性，或者在与外部系统交互时使用更合适的名称。在 CaseStage 类中，别名的设置如下：

preparation_stage : List[str] = Field(description="刷单准备阶段行为列表",alias="准备阶段")
setup_stage : List[str] = Field(description="刷单事前准备行为列表",alias="事前阶段")
execution_stage : List[str] = Field(description="刷单实施阶段行为列表",alias="实施阶段")
post_stage : List[str] = Field(description="刷单事后处理行为列表",alias="事后阶段")

这里的 “准备阶段”、“事前阶段”、“实施阶段” 和 “事后阶段” 就是对应字段的别名。当 model_config 中的 populate_by_name = True 时，在创建 CaseStage 实例时就可以使用这些别名来赋值：

# 使用别名创建实例
case = CaseStage(
    准备阶段=["招募刷手", "创建虚假账户"],
    事前阶段=["测试系统漏洞", "建立资金通道"],
    实施阶段=["虚构交易记录", "伪造物流信息"],
    事后阶段=["销毁电子证据", "转移资金"]
)

在这个例子中，使用别名创建了 CaseStage 实例，这在实际应用中能让代码更易于理解，尤其是在与非技术人员交流或者处理中文数据时。

综上所述，字段是数据模型的组成部分，原始名称是字段在类定义中的名称，而别名则是为字段额外设置的名称，可在创建实例等场景中替代原始名称使用。

`Field`函数

在使用pydantic库来定义数据模型时，Field函数非常实用，它能让你对模型里的字段进行细致配置。下面会通俗且系统地介绍Field的使用。

1. 基本用途与导入

Field函数主要用于对pydantic模型里的字段进行详细设置，比如设置默认值、数据验证规则、描述信息等。使用之前要先导入：

1	from pydantic import BaseModel, Field

2. 定义字段并设置默认值

可以用Field为字段设定默认值。要是创建模型实例时没有给这个字段赋值，就会使用默认值。

from pydantic import BaseModel, Field

class Person(BaseModel):
    name: str = Field(default="John Doe")
    age: int = Field(default=18)

# 创建实例时不提供值，使用默认值
person1 = Person()
print(person1.name)  # 输出: John Doe
print(person1.age)   # 输出: 18

# 创建实例时提供值，使用提供的值
person2 = Person(name="Alice", age=25)
print(person2.name)  # 输出: Alice
print(person2.age)   # 输出: 25

在这个例子中，name字段的默认值是"John Doe"，age字段的默认值是18。创建Person实例时，如果不提供对应字段的值，就会使用默认值；若提供了值，就会使用提供的值。

3. 数据验证

Field可以用来设定数据验证规则，像限定字段的最大、最小值，字符串的最大、最小长度等。

from pydantic import BaseModel, Field

class Product(BaseModel):
    price: float = Field(gt=0, le=1000)  # 价格必须大于 0 且小于等于 1000
    name: str = Field(min_length=2, max_length=50)  # 名称长度必须在 2 到 50 之间

# 验证通过
product1 = Product(price=500, name="Smartphone")
print(product1.price)  # 输出: 500
print(product1.name)   # 输出: Smartphone

# 验证失败，会抛出 ValueError 异常
try:
    product2 = Product(price=-10, name="A")
except ValueError as e:
    print(e)

在这个例子里，price字段要求值必须大于0且小于等于1000，name字段要求长度在2到50之间。若提供的值不符合这些规则，就会抛出ValueError异常。

4. 字段描述信息

可以用Field为字段添加描述信息，这在生成文档或者调试时很有帮助。

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="书籍的标题")
    author: str = Field(description="书籍的作者")

# 查看字段描述信息
print(Book.model_fields['title'].description)  # 输出: 书籍的标题
print(Book.model_fields['author'].description) # 输出: 书籍的作者

在这个例子中，为title和author字段添加了描述信息，之后可以通过model_fields属性查看这些描述。

5. 设置字段别名

Field还能为字段设置别名，这样在创建实例或者序列化输出时就能使用别名，增强代码的可读性。

from pydantic import BaseModel, Field

class User(BaseModel):
    full_name: str = Field(alias="姓名")

# 使用别名创建实例
user = User(姓名="张三")
print(user.full_name)  # 输出: 张三

# 以 JSON 格式输出，使用别名
print(user.json(by_alias=True, ensure_ascii=False))  # 输出: {"姓名": "张三"}

在这个例子中，为full_name字段设置了别名"姓名"，创建User实例时就可以使用别名赋值，输出 JSON 时也能使用别名。

6. 可选字段与必填字段

默认情况下，没有设置默认值的字段是必填字段，而设置了默认值的字段是可选字段。也可以用Field的default_factory参数为字段提供默认值生成函数。

from pydantic import BaseModel, Field
from typing import List

class ShoppingList(BaseModel):
    items: List[str] = Field(default_factory=list)  # 可选字段，默认值为空列表
    customer: str  # 必填字段

# 创建实例，不提供 items 字段，使用默认值
shopping_list = ShoppingList(customer="李四")
print(shopping_list.items)  # 输出: []
print(shopping_list.customer)  # 输出: 李四

在这个例子中，items字段是可选字段，默认值是一个空列表；customer字段是必填字段，创建实例时必须提供值。