龙岗住房和建设局网站,网站建设就找桥三科技,做一钓鱼网站吗,安卓app制作入门教程关系字段用于表示模型关系。它们可以应用于 ForeignKey、ManyToManyField 和OneToOneField 关系#xff0c;也可以应用于反向关系和自定义关系#xff08;如GenericForeignKey#xff09;。
注意#xff1a;关系字段是在relations.py中声明的#xff0c;但按照惯例#…关系字段用于表示模型关系。它们可以应用于 ForeignKey、ManyToManyField 和OneToOneField 关系也可以应用于反向关系和自定义关系如GenericForeignKey。
注意关系字段是在relations.py中声明的但按照惯例您应该使用 from rest_framework import serializers 从 serializers 模块导入它们并将字段引用为 serializers.FieldName
注意REST框架不会尝试根据 select_related 和 prefetc_related 自动优化传递给序列化程序的查询集因为这太神奇了。具有通过其源属性跨越orm关系的字段的序列化程序可能需要额外的数据库命中才能从数据库中获取相关对象。程序员有责任优化查询以避免在使用此类序列化程序时可能发生的额外数据库命中。
例如如果未预取tracks字段则以下序列化程序每次评估tracks字段时都会导致数据库命中
class AlbumSerializer(serializers.ModelSerializer):tracks serializers.SlugRelatedField(manyTrue,read_onlyTrue,slug_fieldtitle)class Meta:model Albumfields [album_name, artist, tracks]# For each album object, tracks should be fetched from database
qs Album.objects.all()
print(AlbumSerializer(qs, manyTrue).data)如果使用 AlbumSerializer 序列化一个相当大的查询集其中 manyTrue那么这可能是一个严重的性能问题。
使用优化传递给 AlbumSerializer 的查询集
qs Album.objects.prefetch_related(tracks)
# No additional database hits required
print(AlbumSerializer(qs, manyTrue).data)会解决此问题。
检查关系
使用ModelSerializer类时将自动为您生成序列化程序字段和关系。检查这些自动生成的字段是确定如何自定义关系样式的有用工具。
要做到这一点请使用 python manage.py shell 打开Django shell然后导入序列化程序类实例化它并打印对象表示… from myapp.serializers import AccountSerializerserializer AccountSerializer()print(repr(serializer))
AccountSerializer():id IntegerField(labelID, read_onlyTrue)name CharField(allow_blankTrue, max_length100, requiredFalse)owner PrimaryKeyRelatedField(querysetUser.objects.all())1 api 参考
为了解释各种类型的关系字段我们将使用几个简单的模型作为示例。我们的模型将用于音乐专辑以及每张专辑中列出的曲目。
class Album(models.Model):专辑album_name models.CharField(max_length100)artist models.CharField(max_length100)class Track(models.Model):歌曲album models.ForeignKey(Album, related_nametracks, on_deletemodels.CASCADE)order models.IntegerField()title models.CharField(max_length100)duration models.IntegerField()class Meta:unique_together [album, order]ordering [order]def __str__(self):return %d: %s % (self.order, self.title)1.1 StringRelatedField
StringRelatedField 可用于使用其__str__方法表示关系的目标。 例如以下序列化程序
class AlbumSerializer(serializers.ModelSerializer):tracks serializers.StringRelatedField(manyTrue)class Meta:model Albumfields [album_name, artist, tracks]将序列化为以下表示形式
{album_name: Things We Lost In The Fire,artist: Low,tracks: [1: Sunflower,2: Whitetail,3: Dinosaur Act,...]
}此字段为只读字段。
参数:
many - 如果应用于多对多关系则应将此参数设置为 True。
1.2 PrimaryKeyRelatedField
PrimaryKeyRelatedField可用于使用其主键来表示关系的目标。
例如以下序列化程序
class AlbumSerializer(serializers.ModelSerializer):tracks serializers.PrimaryKeyRelatedField(manyTrue, read_onlyTrue)class Meta:model Albumfields [album_name, artist, tracks]将序列化为以下表示形式 {album_name: Undun,artist: The Roots,tracks: [89,90,91,...]
}默认情况下此字段是读写的尽管您可以使用read_only标志更改此行为。
参数:
queryset - 验证字段输入时用于模型实例查找的queryset。关系必须显式设置查询集或者设置 read_onlyTrue。many - 如果应用于多对多关系则应将此参数设置为True。allow_null - 如果设置为True则字段将接受None值或可为null关系的空字符串。默认为False。pk_field — 设置为用于控制主键值的序列化/反序列化的字段。例如pk_fieldUUIDField(formathex)会将UUID主键序列化为其紧凑的十六进制表示。
1.3 HyperlinkedRelatedField
HyperlinkedRelatedField可用于使用超链接来表示关系的目标。
例如以下序列化程序
class AlbumSerializer(serializers.ModelSerializer):tracks serializers.HyperlinkedRelatedField(manyTrue,read_onlyTrue,view_nametrack-detail)class Meta:model Albumfields [album_name, artist, tracks]将序列化为以下表示形式
{album_name: Graceland,artist: Paul Simon,tracks: [http://www.example.com/api/tracks/45/,http://www.example.com/api/tracks/46/,http://www.example.com/api/tracks/47/,...]
}默认情况下此字段是读写的尽管您可以使用read_only标志更改此行为。 注意此字段是为映射到接受单个URL关键字参数的URL的对象设计的如使用lookup_field 和lookup_url_kwarg参数设置的。 这适用于包含单个主键或段塞参数作为URL一部分的URL。 如果需要更复杂的超链接表示则需要自定义字段如下面的自定义超链接字段部分所述。 参数: view_name - 应用作关系目标的视图名称。如果您使用的是标准路由器类这将是一个格式为modelname-detail 的字符串。必需。 queryset - 验证字段输入时用于模型实例查找的queryset。关系必须显式设置查询集或者设置 read_onlyTrue。 many - 如果应用于多对多关系则应将此参数设置为True。 allow_null -如果设置为True则字段将接受None值或可为null关系的空字符串。默认为False。 lookup_field - 目标上应用于查找的字段。应与引用视图上的URL关键字参数相对应。默认值为pk。 lookup_url_kwarg - 在url conf中定义的关键字参数的名称该名称对应于查找字段。默认使用与lookup_field相同的值。 format - 如果使用格式后缀则超链接字段将对目标使用相同的格式后缀除非使用 format参数重写。
1.4 SlugRelatedField
SlugRelatedField可用于使用目标上的字段来表示关系的目标。 例如以下序列化程序
class AlbumSerializer(serializers.ModelSerializer):tracks serializers.SlugRelatedField(manyTrue,read_onlyTrue,slug_fieldtitle)class Meta:model Albumfields [album_name, artist, tracks]将被序列化为如下表示形式:
{album_name: Dear John,artist: Loney Dear,tracks: [Airport Surroundings,Everything Turns to You,I Was Only Going Out,...]
}默认情况下此字段是读写的尽管您可以使用 read_only 标志更改此行为。
当使用SlugRelatedField作为读写字段时通常需要确保 slug 字段对应于uniqueTrue的模型字段。 参数: slug_field - 目标上用来表示目标的字段。这应该是一个唯一标识任何给定实例的字段。例如username。必需 queryset - 验证字段输入时用于模型实例查找的queryset。关系必须显式设置查询集或者设置read_onlyTrue。 many - 如果应用于多对多关系则应将此参数设置为True。 allow_null - 如果设置为True则字段将接受None值或可为null关系的空字符串。默认为False。
1.5 HyperlinkedIdentityField
此字段可以作为标识关系应用例如 HyperlinkedModelSerializer 上的 url字段。它也可以用于对象上的属性。例如以下序列化程序
class AlbumSerializer(serializers.HyperlinkedModelSerializer):track_listing serializers.HyperlinkedIdentityField(view_nametrack-list)class Meta:model Albumfields [album_name, artist, track_listing]将会被序列化为如下表达式:
{album_name: The Eraser,artist: Thom Yorke,track_listing: http://www.example.com/api/track_list/12/,
}此字段始终是只读的。 参数:
view_name - 应用作关系目标的视图名称。如果您使用的是标准路由器类这将是一个格式为 model_name-detail 的字符串。必需。lookup_field - 目标上应用于查找的字段。应与引用视图上的URL关键字参数相对应。默认值为 pk。lookup_url_kwarg - 在url conf中定义的关键字参数的名称该名称对应于查找字段。默认使用与 lookup_field 相同的值。format - 如果使用格式后缀则超链接字段将对目标使用相同的格式后缀除非使用format 参数重写。
2 嵌套关系
与前面讨论的对另一个实体的引用相反被引用的实体也可以嵌入或嵌套在引用它的对象的表示中。这种嵌套关系可以通过使用序列化程序作为字段来表示。
如果该字段用于表示多对多关系则应将manyTrue标志添加到序列化程序字段中。
2.1 示例
class TrackSerializer(serializers.ModelSerializer):歌曲序列化器class Meta:model Trackfields [order, title, duration]class AlbumSerializer(serializers.ModelSerializer):专辑序列化器tracks TrackSerializer(manyTrue, read_onlyTrue)class Meta:model Albumfields [album_name, artist, tracks]将序列化为如下嵌套表达式 album Album.objects.create(album_nameThe Grey Album, artistDanger Mouse)Track.objects.create(albumalbum, order1, titlePublic Service Announcement, duration245)
Track: Track objectTrack.objects.create(albumalbum, order2, titleWhat More Can I Say, duration264)
Track: Track objectTrack.objects.create(albumalbum, order3, titleEncore, duration159)
Track: Track objectserializer AlbumSerializer(instancealbum)serializer.data
{album_name: The Grey Album,artist: Danger Mouse,tracks: [{order: 1, title: Public Service Announcement, duration: 245},{order: 2, title: What More Can I Say, duration: 264},{order: 3, title: Encore, duration: 159},...],
}2.2 可写嵌套序列化程序
默认情况下嵌套的序列化程序是只读的。如果您想支持对嵌套序列化程序字段的写操作则需要创建 create() 和/或 update() 方法以便显式指定应如何保存子关系
class TrackSerializer(serializers.ModelSerializer):歌曲序列化器class Meta:model Trackfields [order, title, duration]class AlbumSerializer(serializers.ModelSerializer):专辑序列化器tracks TrackSerializer(manyTrue)class Meta:model Albumfields [album_name, artist, tracks]def create(self, validated_data):tracks_data validated_data.pop(tracks)album Album.objects.create(**validated_data)for track_data in tracks_data:Track.objects.create(albumalbum, **track_data)return album data {album_name: The Grey Album,artist: Danger Mouse,tracks: [{order: 1, title: Public Service Announcement, duration: 245},{order: 2, title: What More Can I Say, duration: 264},{order: 3, title: Encore, duration: 159},],
}serializer AlbumSerializer(datadata)serializer.is_valid()
Trueserializer.save()
Album: Album object3 自定义关系字段
在极少数情况下现有的关系样式都不适合您需要的表示形式您可以实现一个完全自定义的关系字段该字段准确地描述了如何从 model instance 生成输出表示形式。
要实现自定义关系字段您应该重写 RelatedField并实现 .to_representation(self, value) 方法。此方法将字段的目标作为值参数并应返回用于序列化目标的表示形式。值参数通常是一个模型实例。
如果要实现读写关系字段还必须实现 .to_internal_value(selfdata) 方法。
要提供基于上下文的动态查询集还可以重写 .get_queryset(self)而不是在类上或初始化字段时指定 .queryset。
3.1 示例
例如我们可以定义一个关系字段使用其 order 顺序、title 标题和 dration 持续时间将歌曲序列化为自定义字符串表示
import timeclass TrackListingField(serializers.RelatedField):def to_representation(self, value):duration time.strftime(%M:%S, time.gmtime(value.duration))return Track %d: %s (%s) % (value.order, value.title, duration)class AlbumSerializer(serializers.ModelSerializer):tracks TrackListingField(manyTrue)class Meta:model Albumfields [album_name, artist, tracks]将会序列化为如下表示形式
{album_name: Sometimes I Wish We Were an Eagle,artist: Bill Callahan,tracks: [Track 1: Jim Cain (04:39),Track 2: Eid Ma Clack Shaw (04:19),Track 3: The Wind and the Dove (04:34),...]
}4 自定义超链接字段
在某些情况下您可能需要自定义超链接字段的行为以便表示需要多个查找字段的URL。 您可以通过覆盖 HyperlinkedRelatedField 来实现这一点。有两种方法可以被重写
get_url(self、obj、view_name、request、format)
get_url 方法用于将对象实例映射到其 url 表示形式。
如果 view_name 和 lookup_field 属性未配置为正确匹配URL conf则可能引发NoReverseMatch。
get_object(self、view_name、view_args、view_kwargs)
如果您想支持可写的超链接字段那么您还需要覆盖 get_object以便将传入的URL映射回它们所代表的对象。对于只读超链接字段不需要重写此方法。
此方法的返回值应该是与匹配的URL-conf参数相对应的对象。
可能引发ObjectDoesNotExist异常。
4.1 示例
假设我们有一个 customer object 的URL它接受两个关键字参数如下所示
/api/organization_slug/customers/customer_pk/这不能用默认实现来表示默认实现只接受单个查找字段。
在这种情况下我们需要覆盖HyperlinkedRelatedField以获得我们想要的行为
from rest_framework import serializers
from rest_framework.reverse import reverseclass CustomerHyperlink(serializers.HyperlinkedRelatedField):# We define these as class attributes, so we dont need to pass them as arguments.view_name customer-detailqueryset Customer.objects.all()def get_url(self, obj, view_name, request, format):url_kwargs {organization_slug: obj.organization.slug,customer_pk: obj.pk}return reverse(view_name, kwargsurl_kwargs, requestrequest, formatformat)def get_object(self, view_name, view_args, view_kwargs):lookup_kwargs {organization__slug: view_kwargs[organization_slug],pk: view_kwargs[customer_pk]}return self.get_queryset().get(**lookup_kwargs)请注意如果要将此样式与通用视图一起使用则还需要覆盖视图上的 .get_object以便获得正确的查找行为。
一般来说我们建议在可能的情况下为API表示使用平面样式但在适度使用时嵌套URL样式也是合理的。
5 进一步说明
5.1 The queryset argument
queryset 参数只对可写关系字段是必需的在这种情况下它用于执行从原始用户输入映射到模型实例的模型实例查找。
在2.x版本中如果正在使用 ModelSerializer 类序列化程序类有时可以自动确定 queryset 参数。 此行为现在被替换为始终使用可写关系字段的显式查询集参数。 这样做可以减少 ModelSerializer 提供的隐藏“魔法”数量使字段的行为更加清晰并确保在使用 ModelSerializer 快捷方式或使用完全显式的 Serializer 类之间切换是微不足道的。
5.2 自定义HTML显示
The built-in __str__ method of the model will be used to generate string representations of the objects used to populate the choices property.
这些选择用于在可浏览的API中填充 select HTML input。
要为此类输入提供自定义表示请重写 RelatedField 子类的 display_value()。此方法将接收一个模型对象并应返回一个适合表示它的字符串。例如
class TrackPrimaryKeyRelatedField(serializers.PrimaryKeyRelatedField):def display_value(self, instance):return Track: %s % (instance.title)5.3 Select field 截断
当在可浏览的API中呈现时关系字段将默认为最多只显示1000个可选项。如果存在更多项目则将显示一个禁用选项其中包含“超过1000个项目…”。
此行为旨在防止模板由于显示了大量关系而无法在可接受的时间跨度内进行渲染。
有两个关键字参数可用于控制此行为
html_cutoff-如果设置这将是html选择下拉菜单显示的最大选择数。设置为“无”可禁用任何限制。默认值为1000。
html_cutoff_text-如果设置此项则如果html选择下拉菜单中的最大项目数已被截断则会显示一个文本指示符。默认为“超过count个项目…”
您也可以使用设置HTML_SELECT_CUTOFF_TEXT全局控制这些。
在强制执行截断的情况下您可能希望在HTML表单中使用纯输入字段。您可以使用style关键字参数来执行此操作。例如
assigned_to serializers.SlugRelatedField(querysetUser.objects.all(),slug_fieldusername,style{base_template: input.html}
)5.4 反向关系
请注意ModelSerializer和HyperlinkedModelSerializeer类不会自动包含反向关系。若要包含反向关系必须将其显式添加到字段列表中。例如
class AlbumSerializer(serializers.ModelSerializer):class Meta:fields [tracks, ...]通常您需要确保在关系上设置了一个适当的related_name参数可以用作字段名。例如:
class Track(models.Model):album models.ForeignKey(Album, related_nametracks, on_deletemodels.CASCADE)...如果没有为反向关系设置相关名称则需要在fields参数中使用自动生成的相关名称。例如
class AlbumSerializer(serializers.ModelSerializer):class Meta:fields [track_set, ...]5.5 一般关系
如果要序列化通用外键则需要定义一个自定义字段以明确确定如何序列化关系的目标。
例如给定标签的以下模型该模型与其他任意模型具有通用关系
class TaggedItem(models.Model):Tags arbitrary model instances using a generic relation.See: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/tag_name models.SlugField()content_type models.ForeignKey(ContentType, on_deletemodels.CASCADE)object_id models.PositiveIntegerField()tagged_object GenericForeignKey(content_type, object_id)def __str__(self):return self.tag_name以及以下两个模型它们可能具有关联的标签
class Bookmark(models.Model):A bookmark consists of a URL, and 0 or more descriptive tags.url models.URLField()tags GenericRelation(TaggedItem)class Note(models.Model):A note consists of some text, and 0 or more descriptive tags.text models.CharField(max_length1000)tags GenericRelation(TaggedItem)我们可以定义一个自定义字段该字段可用于序列化标记的实例使用每个实例的类型来确定应如何序列化
class TaggedObjectRelatedField(serializers.RelatedField):A custom field to use for the tagged_object generic relationship.def to_representation(self, value):Serialize tagged objects to a simple textual representation.if isinstance(value, Bookmark):return Bookmark: value.urlelif isinstance(value, Note):return Note: value.textraise Exception(Unexpected type of tagged object)如果需要关系的目标具有嵌套表示则可以在 .to_representation() 方法中使用所需的序列化程序 def to_representation(self, value):Serialize bookmark instances using a bookmark serializer,and note instances using a note serializer.if isinstance(value, Bookmark):serializer BookmarkSerializer(value)elif isinstance(value, Note):serializer NoteSerializer(value)else:raise Exception(Unexpected type of tagged object)return serializer.data请注意使用 GenericRelation 字段表示的反向泛型键可以使用常规关系字段类型进行序列化因为关系中目标的类型总是已知的。 有关更多信息请参阅关于通用关系的Django文档
5.6 ManyToManyFields with a Through Model
默认情况下以指定了 Through Model 的 ManyToManyField 为目标的关系字段设置为只读。
如果显式指定指向具有 Through Model 的ManyToManyField的关系字段请确保将 read_only 设置为 True。
如果希望表示Through Model 上的额外字段则可以将直通模型序列化为嵌套对象。
6 第三方软件包
