DjangoRESTframeworkAPI指南(10):序列化·字段转载请注明出处
Serializer 字段
Form 类中的每个字段不仅负责验证数据,还负责 “清洗” 它 — 将其规范化为⼀致的格式。
—
序列化字段处理基本数据类型和其他数据类型(⽐如⾃定义的类)之间的转换。它们还可以对数据进⾏验证,以及从其⽗对象中检索和设置值。
注意: 序列化字段都声明在 fields.py 中,但按照惯例,应该使⽤ from rest_framework import rializers ,并⽤ rializers.<FieldName>的⽅式引⽤。
核⼼参数
每个序列化字段类的构造函数都需要⼀些参数。某些字段类需要附加特定于该字段的参数,但应始终接受以下参数:
read_only
只读字段包含于输出 API 中,不应该包含在需要创建或更新操作的输⼊ API 中。在序列化类输⼊中错误的包含 'read_only' 会被忽略。
将其设置为 True 可确保在序列化表⽰时使⽤该字段,但在反序列化期间创建或更新实例时不使⽤该字段。
默认为 Fal
write_only
将其设置为 True 以确保在更新或创建实例时可以使⽤该字段,但在序列化表⽰时不包括该字段。
默认为 Fal
required支持的英文
如果在反序列化过程中没有该提供字段,通常会出现错误。如果在反序列化过程中不需要此字段,则应该设置为 fal。
将此设置为 Fal 还允许在序列化实例时从输出中省略对象属性或字典密钥。如果密钥不存在,它将不会包含在输出表⽰中。
默认为 True
allow_null
如果把 None 传递给序列化字段,通常会引发错误。如果 None 应被视为有效值,则将此关键字参数设置为 True 。
请注意,将此参数设置为 True 将意味着序列化输出的缺省值为 null,但并不意味着输⼊反序列化的缺省值。
默认为 Fal
default
如果设置,则会给出默认值,在没有提供输⼊值时,将使⽤该默认值。如果未设置,则默认⾏为是不填充该属性。
部分更新操作时不应该使⽤ default。因为有些情况下,只有传⼊数据中提供的字段才会返回验证值。
可以设置为函数或其他可调⽤的对象,在这种情况下,每次使⽤该值时都会对其进⾏调⽤。被调⽤时,
它将不会收到任何参数。如果可调⽤对象具有 t_context ⽅法,那么在每次将字段实例作为参数获取值之前都会调⽤该⽅法。这与验证器的⼯作⽅式相同。
在序列化实例时,如果对象属性或字典关键字不存在于实例中,将使⽤缺省值。
请注意,设置默认值意味着该字段不是必需的。同时包括 default 和 required 的关键字参数都是⽆效的,会引发错误。
source
将⽤于填充字段的属性的名称。可以是⼀个只接受 lf 参数的⽅法,如 URLField(source='get_absolute_url'),或者使⽤点符号来遍历属性,如 EmailField(source='ur.email')。在使⽤点符号时,如果在属性遍历期间任何对象不存在或为空,则可能需要提供缺省值。
source ='*' 具有特殊含义,⽤于表⽰整个对象应该传递到该字段。这对创建嵌套表⽰或对于需要访问完整对象以确定输出表⽰的字段⾮常有⽤。
默认为该字段的名称。
validators
应该应⽤于传⼊字段输⼊的验证函数列表,该列表中的函数应该引发验证错误或仅返回。验证器函数通常应该引发
rializers.ValidationError ,但 Django 的内置 ValidationError 也⽀持与 Django 代码库或第三⽅ Django 包中定义的验证器兼容。error_messages
⼀个字典,key 是错误代码, value 是对应的错误信息。
label
⼀个简短的⽂本字符串,可⽤作 HTML 表单字段或其他描述性元素中字段的名称。
help_text
⼀个⽂本字符串,可⽤作 HTML 表单字段或其他描述性元素中字段的描述。
initial
应该⽤于预填充 HTML 表单字段的值。你可能会传递⼀个可调⽤对象,就像你对任何常规 Django Field 所做的⼀样:
import datetime
from rest_framework import rializers
class ExampleSerializer(rializers.Serializer):
day = rializers.DateField(initial=day)
复制代码
style
可⽤于控制渲染器渲染字段的键值对的字典。
这⾥有两个例⼦是 'input_type' 和 'ba_template' :
# U <input type="password"> for the input.
password = rializers.CharField(
style={'input_type': 'password'}
)
# U a radio input instead of a lect input.
color_channel = rializers.ChoiceField(
choices=['red', 'green', 'blue'],
style={'ba_template': 'radio.html'}
)
复制代码
Boolean 字段
BooleanField
表⽰⼀个 boolean 值。
使⽤ HTML 编码表单时需要注意,省略⼀个 boolean 值被视为将字段设置为 Fal,即使它指定了 default=True 选项。这是因为 HTML 复选框通过省略该值来表⽰未选中的状态,所以 REST framework 将省略看作是空的复选框。
请注意,将使⽤ required=Fal 选项⽣成默认的 BooleanField 实例(因为 Django models.BooleanField 始终为 blank=True)。如果想要更改此⾏为,请在序列化类上显式声明 BooleanField。
对应与 dels.fields.BooleanField.
签名: BooleanField()
NullBooleanField
表⽰⼀个布尔值,它也接受 None 作为有效值。
对应与 dels.fields.NullBooleanField.
签名: NullBooleanField()
字符串字段
CharField
表⽰⽂本。可以使⽤ max_length , min_length 验证(或限定)⽂本的长短。
对应与 dels.fields.CharField 或 dels.fields.TextField.
签名: CharField(max_length=None, min_length=None, allow_blank=Fal, trim_whitespace=True)
max_length - 验证输⼊所包含的字符数不超过这个数⽬。
min_length - 验证输⼊所包含的字符数不少于这个数⽬。
allow_blank - 如果设置为 True,则空字符串应被视为有效值。如果设置为 Fal,那么空字符串被认为是⽆效的并会引发验证错误。
默认为 Fal。
trim_whitespace - 如果设置为 True,则前后空⽩将被删除。默认为 True。
allow_null 选项也可⽤于字符串字段,尽管它相对于 allow_blank 来说不被推荐。同时设置 allow_blank=True 和 allow_null=True 是有效的,但这样做意味着字符串表⽰允许有两种不同类型的空值,这可能导致数据不⼀致和微妙的应⽤程序错误。
EmailField
表⽰⽂本,将⽂本验证为有效的电⼦邮件地址。
对应与 dels.fields.EmailField
签名: EmailField(max_length=None, min_length=None, allow_blank=Fal)
RegexField
表⽰⽂本,⽤于验证给定的值是否与某个正则表达式匹配。
对应与 django.forms.fields.RegexField.
签名: RegexField(regex, max_length=None, min_length=None, allow_blank=Fal)
强制的 regex 参数可以是⼀个字符串,也可以是⼀个编译好的 Python 正则表达式对象。
使⽤ Django 的 validators.RegexValidator 进⾏验证。
SlugField
⼀个根据模式 [a-zA-Z0-9_-]+ 验证输⼊的 RegexField 。
对应与 dels.fields.SlugField.
签名: SlugField(max_length=50, min_length=None, allow_blank=Fal)
URLField
⼀个根据 URL 匹配模式验证输⼊的 RegexField。完全合格的 URL 格式为 <host>/<path>。
对应与 dels.fields.URLField. 使⽤ Django 的 validators.URLValidator 进⾏验证。
宫保鸡丁正宗做法签名: URLField(max_length=200, min_length=None, allow_blank=Fal)
UUIDField
确保输⼊的字段是有效的 UUID 字符串。to_internal_value ⽅法将返回⼀个 uuid.UUID 实例。在输出时,字段将以规范的连字符格式返回⼀个字符串,例如:
"de305d54-75b4-431b-adb2-eb6b9e546013"
复制代码
签名: UUIDField(format='hex_verbo')
击沉战舰format: 确定 uuid 值的表⽰形式
研究生统考
'hex_verbo' - 权威的⼗六进制表⽰形式,包含连字符: "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
'hex' - 紧凑的⼗六进制表⽰形式, 不包含连字符:"5ce0e9a55ffa654bcee01238041fb31a"
'int' - 128 位整数表⽰形式:"123456789012312313134124512351145145114"
'urn' - RFC 4122 URN 表⽰形式: "urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 修改 format 仅影响表⽰值。所有格式都被 to_internal_value 接受。
FilePathField
⼀个其选项仅限于⽂件系统上某个⽬录中的⽂件名的字段。
对应于 django.forms.fields.FilePathField.
签名: FilePathField(path, match=None, recursive=Fal, allow_files=True, allow_folders=Fal, required=None, **kwargs) path - FilePathField 应该从中选择的⽬录的绝对⽂件系统路径。
match - ⽤来过滤⽂件名的正则表达式,string 类型。
recursive - 指定是否应该包含路径的所有⼦⽬录。默认值是 Fal。
allow_files - 是否应该包含指定位置的⽂件。默认值为 True。这个参数或 allow_folders 必须是 True。(两个属性必须有⼀个为 true)
allow_folders - 是否应该包含指定位置的⽂件夹。默认值是 Fal。这个参数或 allow_files 必须是 True。(两个属性必须有⼀个为true)
IPAddressField天下壮士
确保输⼊是有效的 IPv4 或 IPv6 字符串。
对应于 django.forms.fields.IPAddressField 和 django.forms.fields.GenericIPAddressField.九连环的解法
签名: IPAddressField(protocol='both', unpack_ipv4=Fal, **options)
protocol 将有效输⼊限制为指定的协议。接受的值是 'both' (默认),'IPv4' 或 'IPv6' 。匹配不区分⼤⼩写。
unpack_ipv4 解压 IPv4 映射的地址,如 ::ffff:192.0.2.1。如果启⽤此选项,则该地址将解压到 192.0.2.1。 默认是禁⽤的。只能在protocol 设置为 'both' 时使⽤。
数字字段
IntegerField
表⽰整数。
猜一成语对应于 dels.fields.IntegerField, dels.fields.SmallIntegerField, dels.fields.PositiveIntegerField 和dels.fields.PositiveSmallIntegerField。
签名: IntegerField(max_value=None, min_value=None)
max_value 验证所提供的数字不⼤于这个值。
min_value 验证所提供的数字不⼩于这个值。
依依图片网FloatField
表⽰浮点。
对应于 dels.fields.FloatField.
签名: FloatField(max_value=None, min_value=None)
max_value 验证所提供的数字不⼤于这个值。
min_value 验证所提供的数字不⼩于这个值。
DecimalField
表⽰⼗进制,由 Python ⽤ Decimal 实例表⽰。
对应于 dels.fields.DecimalField.
签名: DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)
max_digits 允许的最⼤位数。它必须是 None 或⼤于等于 decimal_places 的整数。
decimal_places ⼩数位数。
coerce_to_string 如果应返回字符串值,则设置为 True ;如果应返回 Decimal 对象,则设置为 Fal 。默认值与
COERCE_DECIMAL_TO_STRING ttings key 的值相同,除⾮被覆盖,否则该值将为 True。如果序列化对象返回 Decimal 对象,则最终的输出格式将由渲染器决定。请注意,设置 localize 将强制该值为 True。
max_value 验证所提供的数字不⼤于这个值。