Django中Serializer 序列化器可用字段及参数

1,137 阅读5分钟

一. 常用字段

1. CharField

字符串字段, 表示文本, 对应django models里的 CharField 或 TextField

常用参数:

- max_length        —— 验证输入包含的字符数不超过此数目
- min_length        —— 验证输入包含的字符数不小于此数目
- allow_blank       —— 如果设置为 True,则该字段支持空字符, 反之则不支持空字符,并会引发验证错误。默认为 False
- trim_whitespace   —— 如果设置为 True,则前后空格将被删除。默认为 True

2. EmailField

文本格式, 将文本验证为有效的电子邮件地址, 对应于 django.db.models.fields.EmailField

3. RegexField

文本格式,用于验证给定的值是否与某个正则表达式匹配,对应于 django.forms.fields.RegexField

4. URLField

根据 URL 匹配模式验证输入的 RegexField。期望窗体的完全限定 URL 为 http://host/path, 对应于 django.db.models.fields.URLField

5. UUIDField

确保输入是有效 UUID 字符串的字段。to_internal_value 将返回 uuid.UUID 实例。在输出时,该字段将返回规范的连字符格式的字符串

常用参数:

 - format:确定 uuid 值的表示格式
 'hex_verbose' —— 规范十六进制表示,包含连字符:"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
 'hex'         —— UUID 的紧凑的十六进制表示, 不包含连字符:"5ce0e9a55ffa654bcee01238041fb31a"
 'int'         —— UUID 的 128 位整数表示:"123456789012312313134124512351145145114"
 'urn'         —— UUID 的 RFC 4122 URN 表示:"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 修改 format参数只影响表示值。to_internal_value 接受所有格式。

6. FilePathField

选择限于文件系统上某个目录中的文件名的字段,

常用参数

- path          —— FilePathField 应该从中选择的文件系统到目录的绝对路径
- match         —— 一个正则表达式,作为字符串,FilePathField 将用于过滤文件名
- recursive     —— 指定是否应该包含路径的所有子目录。默认值是 False
- allow_files   —— 指定是否应该包含指定位置的文件。默认值为 True。这个参数或 allow_folders 必须是 True
- allow_folders —— 指定是否应该包含指定位置的文件夹。默认值是 False。这个参数或 allow_files必须是 True

7. IPAddressField

确保输入是有效 IPv4 或 IPv6 字符串的字段,

常用参数:

- protocol 限制指定协议的有效输入。可接受的值是 'both' (默认),'IPv4' 或 'IPv6'。匹配不区分大小写
- unpack_ipv4 解压 IPv4 映射地址,如 ::ffff:192.0.2.1。如果启用此选项,则该地址将解压到 192.0.2.1。默认为禁用。只能在 protocol 设置为 'both' 时使用。

8. SlugField

根据模式 [a-zA-Z0-9_-]+ 验证输入的 RegexField, 对应于 django.db.models.fields.SlugField


9. IntegerField

整数格式, 对应于 django.db.models.fields.IntegerField

常用参数:

- max_value 验证所提供的数字不大于这个值
- min_value 验证所提供的数字不小于这个值

10. FloatField

浮点格式, 对应于 django.db.models.fields.FloatField

常用参数:

- max_value 验证所提供的数字不大于这个值
- min_value 验证所提供的数字不小于这个值

11. DecimalField

十进制格式,由 Decimal 实例在 Python 中表示, 对应于 django.db.models.fields.DecimalField

常用参数:

- max_digits 数字中允许的最大位数。它必须是 None 或大于等于 decimal_places 的整数
- decimal_places 以数字存储的小数位数
- coerce_to_string 如果用于表示应返回字符串值,则设置为 True;如果应返回 Decimal 对象,则设置为 False。默认与 COERCE_DECIMAL_TO_STRING 设置中的键值相同,除非重写,否则将为 True。如果序列化器返回 Decimal 对象,则最终输出格式将由渲染器确定。请注意,设置 localize 会将值强制为 True
- max_value 验证所提供的数字不大于这个值
- min_value 验证所提供的数字不小于这个值
- localize 设置为 True 以便基于当前区域启用输入和输出本地化。这也将强制 coerce_to_string 为 True。默认为 False。请注意,如果在设置文件中设置了 USE_L10N = True,则会启用数据格式化
- rounding 设置量化到配置精度时使用的舍入模式。有效值是 decimal 模块舍入模式。默认为 None

该字段还带有一个可选参数 coerce_to_string。如果设置为 True,则表示将以字符串形式输出。如果设置为 False,则表示将保留为 Decimal 实例,最终表示形式将由渲染器确定, 如果未设置,则默认与 COERCE_DECIMAL_TO_STRING 设置相同的值,除非另行设置,否则该值为 True

用法示例:

#  要使用 2 位小数的精度验证最大为 999 的数字,您可以使用
serializers.DecimalField(max_digits=5, decimal_places=2)

# 要使用 2 位小数的精度验证最大为 999 的数字,您可以使用
serializers.DecimalField(max_digits=19, decimal_places=10)

12. DateTimeField

日期和时间格式, 对应于 django.db.models.fields.DateTimeField

常用参数:

- format —— 表示输出格式的字符串。如果未指定,则默认为与 DATETIME_FORMAT 设置键相同的值,除非设置,否则将为 'iso-8601'。设置为格式字符串表明 to_representation 返回值应该被强制为字符串输出。格式字符串描述如下。将此值设置为 None 表明应由 to_representation 返回 Python datetime 对象。在这种情况下,日期时间编码将由渲染器确定。
- input_formats —— 表示可用于解析日期的输入格式的字符串列表。如果未指定,则将使用 DATETIME_INPUT_FORMATS 设置,默认为 ['iso-8601']

补充:

DateTimeField 格式字符串
格式化字符串可以是显式指定的 Python strftime 格式,也可以是表明使用 ISO 8601 样式的日期时间的特殊字符串 iso-8601。(例如 '2013-01-29T12:34:56.000000Z'), 当格式化日期时间对象使用 None 值时,to_representation 将返回,最终的输出表示将由渲染器类决定

auto_now 和 auto_now_add 模型字段
当使用 ModelSerializer 或 HyperlinkedModelSerializer 时,请注意,任何带有 auto_now=True 或 auto_now_add=True 的模型字段将默认使用 read_only=True 的序列化字段
如果想重写此行为,则需要在序列化器中显式声明 DateTimeField。例如:

class CommentSerializer(serializers.ModelSerializer):
    created = serializers.DateTimeField()
    class Meta:
        model = Comment

待更新