36.序列化器通用字段参数和字段类型

drf在Django字段类型的基础上派生了自己的字段类型以及字段参数

序列化器的字段类型用于处理原始值和内部数据类型直接的转换

还可以用于验证输入、以及父对象检索和设置值

通用字段参数

read_only
    该参数默认为false，设置为True的话则将字段变为只读
    被设置成只读的字段可以包含在api输出中，但是创建或者更新期间不应该包含在输入中
    即使你再序列化的时候为一个read_only字段提供值，也会被忽略
    也就是说validated_data中不会包含发送过来的设置为只读字段的数据
    
write_only
    默认为False
    设置为True则表示只写不读 

required
    默认为True,表示该字段必填
    设置为False表示该字段的内容可以空缺
    
default
    为字段设置默认值
    在字段中同时设置default和required关键字参数是无效的，并且会引发错误
    
allow_null
    该参数的默认值为False，表示该字段不允许为空
    如果设置为True，表示字段的值可以为空，或者是none
    类型Django原生自动参数中的blank和null
    
source
     指定字段的值的来源如何获取
     如果指定了该参数，那么该字段就不需要从请求中获取
     可以序列化的时候知道获取对应的值
     参数的值:
         只接受self参数的方法URLField(source='get_absolute_url')
         是使用点分表示来遍历属性EmailField(source='user.email'
         source='*' 具有特殊含义，用于指示整个对象应该传递到该字段
         这对于创建嵌套表示或者需要访问整个对象以确定输出表示的字段非常有用
     
     值示例：
          user_role = serializers.CharField(source='user_type') # 获取model中user_type字段的内容
          url = serializers.URLField(source='get_absolute_url') # 获取完整url地址 
          group_id = serializers.CharField(source='group.id') # 获取外键关联的组的id

validators
    为字段指定专门的验证器
    
error_messages
    错误消息的错误代码字典
    可以自定义错误信息

label
    一个简短的文本字符串
    可以用作html表单或其他描述性元素中生成的字段的标签
    
help_text
    一个文本字符串
    可以用作html表单或其他描述性元素中生成的字段的描述文字
    
initial
    用于预先填充html表单字段的值
    也就是给字段一个初始化值
    也可以将一个callable可调用方法传递给他
    
style
    该参数的值必须是字典
    可用于控制渲染器如何渲染字段
    也就是为字段添加额外的css或者html控制

布尔类型字段

BooleanField
    普通的布尔字段。也就是值只能为True或者False
    # 示例
    status = serializer.BooleanField()
    
NullBooleanField
    接受 None 作为有效值的布尔字段，也就是说这个字段也可以为空
     # 示例
    status = serializer.NullBooleanField()

字符串类型字段

CharField
    最基本的文本类型。常用的参数是验证文本是否短于 max_length 和长于 min_length
    不同于Django原生，这两个参数非必须
    参数:
        max_length - 字段最大长度
        min_length - 字段最小长度
        allow_blank - 字段是否可以为空，默认为 False 
        trim_whitespace - 如果设置为 True 则会自动修剪字符串的前导和尾随的空格
        相当于自动应用了一个字符串的strip方法。默认为 True 
        
        
EmailField
    文本格式，验证为有效的电子邮件地址
    #示例:
    EmailField(max_length=None, min_length=None, allow_blank=False)
    
RegexField
    文本格式，字段的值必须与regex参数指定的正则表达式相匹配
    #示例:
    RegexField(regex, max_length=None, min_length=None,allow_blank=False)
    必填的第一位置参数 regex 可以是字符串，也可以是编译过的python正则表达式对象
    
SlugField
     RegexField 字段，根据 [a-zA-Z0-9_-]+ 正则模式验证输入。也就是定死了正则表达式
       
URLField
    RegexField 类型字段，规定字段必须是个合法的URL类型的字符串
    
UUIDField
    确保输入的字段是有效的UUID字符串
    to_internal_value 方法将返回一个 uuid.UUID 实例，在输出时，该字段将以规范的以短横线连接的格式返回一个字符串
    #示例:
    UUIDField(format='hex_verbose')
    format指定uuid值的表示格式:
        'hex_verbose' - 十六进制表示，包括连字符
        'hex' - UUID的紧凑十六进制表示形式，不包括连字符
        'int' - UUID的128位整数表示
        'urn' - UUID的RFC 4122 URN表示
        
FilePathField
    文件路径类型字段，其选择仅限于文件系统上某个目录中的文件名
    #示例:
    FilePathField(path, match=None, recursive=False, allow_files=True,allow_folders=False, required=None, **kwargs)    
    path - 此FilePathField应从中选择的目录的绝对文件系统路径
    match - 作为字符串的正则表达式，FilePathField用它过滤文件名
    recursive - 指定是否应递归搜索路径的所有子目录。默认是 False 
    allow_files - 指定是否应包括指定位置的文件。默认是 True 
    allow_folders - 指定是否应包括指定位置的文件夹。默认是 False 
    
IPAddressField
    确保输入是有效的IPv4或IPv6的字符串
    #示例:
    IPAddressField(protocol='both', unpack_ipv4=False, **options)
    protocol ：接受协议的类型。可接受的值是“both”（默认）、“IPv4”或“IPv6”。匹配不区分大小写。
    unpack_ipv4 ：解包IPv4映射地址，如:: ww：192.0.2.1
    如果启用此选项，则该地址将解压缩到192.0.2.1。默认为禁用。只能在协议设置为“both”时使用

数字类型字段

IntegerField
    整数
    IntegerField(max_value=None, min_value=None)
    max_value 允许的最大值
    min_value 允许的最小值
    
FloatField
    FloatField(max_value=None, min_value=None)
    max_value 验证提供的数字是否不大于此值
    min_value 验证提供的数字是否不低于此值
    
    
DecimalField
    科学十进制表示，Python的 Decimal 实例
    #示例:
    DecimalField(max_digits, decimal_places, coerce_to_string=None,max_value=None, min_value=None)
    max_digits 数字中允许的最大位数。它必须是 None 或大于或等于 decimal_places的整数。
    decimal_places 与数字一起存储的小数位数。
    max_value ：验证提供的数字是否不大于此值。
    min_value ： 验证提供的数字是否不低于此值。
    localize ：默认为 False 。设置为 True ，则根据当前区域设置启用输入和输出的本地化。这也将迫使 coerce_to_string 设置为 True 。如果已在设置文件中进行了 USE_L10N=True 设置，则会启用数据格式设置。
    rounding ：设置量化到配置精度时使用的舍入模式。默认为 None

日期和时间类型字段

DateTimeField
    日期和时间表示
    #示例:
    DateTimeField(format=api_settings.DATETIME_FORMAT,input_formats=None, default_timezone=None)
    format - 时间字符串的格式。如果未指定，则默认为settings中的 DATETIME_FORMAT 设置。
    input_formats - 用于解析日期的输入格式的字符串列表。如果未指定，
    DATETIME_INPUT_FORMATS 将使用默认设置 ['iso-8601'] 。
    default_timezone - 默认时区
    auto_now 和 auto_now_add 模型字段
    使用 ModelSerializer 或 HyperlinkedModelSerializer 序列化器时，，带有auto_now=True 或 auto_now_add=True 的模型字段将自动设置 read_only=True 参数
    如果要覆盖此行为，则需要在序列化类中显式声明一个 DateTimeField 字段
    
    
    
    
DateField
    日期类型字段
    DateField(format=api_settings.DATE_FORMAT, input_formats=None)

TimeField
    时间类型字段
    TimeField(format=api_settings.TIME_FORMAT, input_formats=None)
    
    
DurationField
    持续时间长度类型的字段
    你定义了这种类型的字段，那么在 validated_data 变量中将包含一个datetime.timedelta 实例
    max_value 验证提供的持续时间不大于此值
    min_value 验证提供的持续时间不小于此值

选择类型字段

ChoiceField
    接受有限选择集中的值的字段
    如果相应的模型字段包含 choices=… 参数，则 ModelSerializer 会自动生成一个对应的字段
    #示例:
    ChoiceField(choices)
    choices - 有效值列表或 (key, display_name) 元组列表。
    allow_blank - 如果设置为 True 则应将空字符串视为有效值。如果设置为 False 则空字符串被视为无效并将引发验证错误。默认为 False 。
    html_cutoff - 如果设置，这将是HTML下拉列表标签将显示的最大选择数。
    html_cutoff_text - 如果设置，如果在HTML选择下拉列表中截断了最大项目数，则将显示文本指示符。默认为 "More than {count} items…"
    allow_blank 与 allow_null 两个参数都可以用于 ChoiceField 字段
    但建议只使用一个，而不是同时用两个
     allow_blank 应是文本选择的首选 allow_null 对应数字或其他非文本选择
    
MultipleChoiceField
    可多选的类型字段
    可以接受零个、一个或多个值的字段。 to_internal_value 方法可以返回包含所选值的集合
    #示例:
    MultipleChoiceField(choices)
    choices - 有效值列表或 (key, display_name) 元组列表，必填参数。
    allow_blank - 如果设置为 True 则应将空字符串视为有效值。如果设置为 False 则空字符串被视为无效并将引发验证错误。默认为 False 。
    html_cutoff - 同上
    html_cutoff_text - 同上

文件和图片字段

FileField 和 ImageField 字段仅适用于使用 MultiPartParser 或 FileUploadParser解析器的情况
大多数解析器（例如JSON）不支持文件上载
Django原生的FILE_UPLOAD_HANDLERS用于上传文件的处理

FileField
    文件字段。执行Django标准的FileField验证
    max_length - 指定文件名的最大长度。
    allow_empty_file - 指定是否允许空文件。
    use_url - 如果设置为 True ，则URL字符串将用于输出表示。如果设置为 False 
    则文件名字符串值将用于输出表示。默认为settings中 UPLOADED_FILES_USE_URL 设置的值，除非另有设置


ImageField
    图像字段。将上载的文件内容验证为与已知图像格式匹配
    max_length - 指定文件名的最大长度。
    allow_empty_file - 指定是否允许空文件。
    use_url - 同上
    使用此字段需要提前安装 Pillow 包

复合类型字段

ListField
    列表的字段类型
    #示例:
    ListField(child=<A_FIELD_INSTANCE>, min_length=None,max_length=None)
    child - 用于验证列表中对象的字段实例。如果未提供此参数，则不会进行验证
    min_length - 列表包含的元素数量不少于该值
    max_length - 列表包含的元素个数不超过该值    
    验证整数列表:serializers.ListField(child=serializers.IntegerField(min_value=0, max_value=100))
    编写可重用的列表字段类：
    在可以在整个应用程序中重用我们自定义的 StringListField 类，而无需为其提供 child参数
    class StringListField(serializers.ListField):
        child = serializers.CharField()

DictField
    字典的字段类型
    DictField(child=<A_FIELD_INSTANCE>)
    child - 同上，但对元素个数没有要求
    验证字符串到字符串的映射的字段示例
    DictField(child=CharField())
    自定义字段类
    class DocumentField(DictField):
        child = CharField()

HStoreField
    预配置的 DictField 。与Django的postgres HStoreField 兼容
    child - 用于验证字典中的值的字段实例。默认子字段接受空字符串和空值
    子字段必须是 CharField 实例
    
JSONField
    json字段类型，用于验证传入数据是否有效的JSON结构    
    JSONField(binary)
    binary - 如果设置为 True 则该字段将输出并验证JSON编码的字符串，而不是原始数据结构。默认为 False

其他字段类型

ReadOnlyField
    只读类型，它只返回字段的值而不进行修改
    默认情况下，此字段用于 ModelSerializer 包含与属性相关的字段名称而不是模型字段

HiddenField
    隐藏的字段，它不根据用户输入获取值，而是从默认值或可调用的值中获取值    
    serializers.HiddenField(default=timezone.now)
    
ModelField
    可以绑定到任意模型字段的通用字段
    此字段用于 ModelSerializer 对应于自定义模型字段类。一般不使用
    
SerializerMethodField
    一个只读字段。它通过调用附加到的序列化类上的方法来获取值。可用于将任何类型的数据添加到序列化对象中
    相当于自定义字段数据
    SerializerMethodField(method_name=None)
    method_name - 要调用的序列化程序上方法的名称。如果不包含，则默认为get_<field_name>  
    extra_info = serializers.SerializerMethodField()
    def get_extra_info(self, obj): # obj参数表示每一条数据库记录
        return {
        'email': 'xxxx',
        'xxxx': 'xxxx',
        'status':obj.related_filed.some_filed,