Django REST framework 3.2

3.2 版本是第一个包含可浏览 API 的管理界面的版本。

Django REST framework 3.2 - 图1

此接口旨在充当 API 的更用户友好的接口。它既可以作为现有 BrowsableAPIRenderer 的替代品，也可以与它一起使用，允许您根据需要在两种样式之间切换。

我们还修复了大量的问题，并进行了大量的清理和改进。

在 3.1.x 系列的过程中，我们在 GitHub 问题跟踪器上解决了近 600 票。这意味着我们目前以每月约 100 个问题关闭或拉取请求的速度运行。

没有我们优秀的 Kickstarter 支持者的支持，这一切都不可能实现。如果您正在寻找 Django 开发的工作，我们强烈建议您查看我们的赞助商并了解谁在招聘。

AdminRenderer

要包含 AdminRenderer，只需将其添加到您的设置：

  1. REST_FRAMEWORK = {
  2.     'DEFAULT_RENDERER_CLASSES': [
  3.         'rest_framework.renderers.JSONRenderer',
  4.         'rest_framework.renderers.AdminRenderer',
  5.         'rest_framework.renderers.BrowsableAPIRenderer'
  6.     ],
  7.     'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
  8.     'PAGE_SIZE': 100
  9. }

AdminRenderer 存在一些限制，特别是它还不能处理列表或字典输入，因为我们没有任何支持这些的 HTML 表单字段。

另请注意，这是初始版本，我们还没有用于修改覆盖模板的行为或文档的公共 API。

我们的想法是尽早将这个版本发布给用户，这样我们就可以开始得到反馈，并在 3.3 版本中发布功能更加完善的版本。

支持的版本 (Supported versions)

此版本放弃了对 Django 1.4 的支持。

我们支持的 Django 版本现在是 1.5.6 +，1.6.3 +，1.7 和 1.8。

弃用 (Deprecations)

3.2 中没有新的弃用，尽管一些现有的弃用已经随着我们的弃用策略而升级。

  • request.DATA 被放在 3.0 的弃用路径中。它现在已被删除，其使用将导致错误。请使用更 pythonic 样式的 request.data。
  • request.QUERY_PARAMS 被放在 3.0 的弃用路径中。它现在已被删除，其使用将导致错误。请使用更 pythonic 样式的 request.query_params。
  • 现在已删除以下 ModelSerializer.Meta 选项：write_only_fields，view_name，lookup_field。请使用更通用的 extra_kwargs 选项。

自 3.1 以来，以下分页视图属性和设置已移至分页类的属性中。它们的使用以前处于 “待定弃用” 状态，现在已升级为 “弃用”。它们将继续行使职责但会引发错误。

  • view.paginate_by - 使用 paginator.page_size 代替。
  • view.page_query_param - 使用 paginator.page_query_param 代替。
  • view.paginate_by_param - 使用 paginator.page_size_query_param 代替。
  • view.max_paginate_by - 使用 paginator.max_page_size 代替。
  • settings.PAGINATE_BY - 使用 paginator.page_size 代替。
  • settings.PAGINATE_BY_PARAM - 使用 paginator.page_size_query_param 代替。
  • settings.MAX_PAGINATE_BY - 使用 paginator.max_page_size 代替。

列出行为的修改 (Modifications to list behaviors)

当他们引入不同的行为时，有一些 bug 修复值得一提。

这些有点微妙，可能不会影响到大多数用户，但是在升级项目之前值得了解。

ManyToMany fields and blank=True

我们现在添加了 allow_empty 参数，它可以与 ListSerializer 或 many=True 关系一起使用。默认情况下为 True，但是如果您不允许空列表作为有效输入，则可以将其设置为 False。

作为这方面的后续工作，我们现在能够正确地反映 Django 的 ModelForm 在验证多对多字段方面的行为。

以前，模型上的多对多字段会映射到允许空或非空列表输入的序列化器字段。现在，多对多字段将映射到需要至少一个输入的序列化器字段，除非模型字段具有 blank=True 设置。

这是映射在实践中的样子：

  • models.ManyToManyField() → serializers.PrimaryKeyRelatedField(many=True, allow_empty=False)
  • models.ManyToManyField(blank=True) → serializers.PrimaryKeyRelatedField(many=True)

结果是这样的：如果模型中有多对多字段，那么如果要在等效的 ModelSerializer 字段中允许空输入，请确保包含参数 blank=True。

List fields and allow_null

当使用带有 ListField 的 allow_null 或嵌套的 many=True 序列化器时，前面的行为是允许 null 值作为列表中的项。现在的行为是允许 null 值而不是列表。

例如，请使用以下字段：

  1. NestedSerializer(many=True, allow_null=True)

以前的验证行为是：

  • [{…}, null, {…}] 有效。
  • null 无效。

我们从 3.2.0 开始的验证行为现在是：

  • [{…}, null, {…}] 无效。
  • null 有效。

如果希望允许 null 子项，则需要在子类上指定 allow_null，使用显式 ListField 而不是 many=True。例如：

  1. ListField(child=NestedSerializer(allow_null=True))

What’s next?

3.3 版本目前计划于 10 月初发布，这将是 kickstarter 资助的最后一个版本。

此版本计划包括：

  • 在可浏览的 API 和管理界面中搜索和过滤控件。
  • 管理界面的改进和公共 API。
  • 我们模板化的 HTML 表单和字段的改进和公共 API。
  • HTML 表单中的嵌套对象和列表支持。

再次感谢所有赞助商和支持者。