Django REST framework 3.1

3.1 版本是 Kickstarter 项目发行版中的一个中间步骤，包含了一系列新功能。

一些亮点包括：

• 超级智能光标分页方案。
• 改进的分页 API，支持标头或主体分页样式。
• 分页控制可浏览API中的渲染。
• 更好地支持 API 版本控制。
• 内置国际化支持。
• 支持 Django 1.8 的 HStoreField 和 ArrayField。

分页 (Pagination)

pagination API 经过了改进，使其更易于使用，功能更强大。

以下是标题功能的指南。有关完整详细信息，请参阅分页文档。

注意，作为此工作的结果，许多设置键和通用视图属性现在被移到挂起的弃用状态。控制分页样式现在主要通过覆盖分页类并修改其配置属性来处理。

• PAGINATE_BY 设置键将继续工作，但现在正在等待弃用。现在应该使用更明显命名的 PAGE_SIZE 设置键。
• PAGINATE_BY_PARAM、MAX_PAGINATE_BY 设置键将继续工作，但现在正在等待弃用，以便在配置的分页类上设置配置属性。
• paginate_by、page_query_param、paginate_by_param 和 max_paginate_by 通用视图属性将继续工作，但现在正在等待弃用，以便在配置的分页类上设置配置属性。
• pagination_serializer_class 视图属性和 DEFAULT_PAGINATION_SERIALIZER_CLASS 设置键不再有效。分页 API 不使用序列化器来确定输出格式，您需要在分页类上覆盖 get_paginated_response 方法，以便指定如何控制输出格式。

新的分页方案 (New pagination schemes.)

到目前为止，REST framework 中只有一个内置的分页样式。我们现在有了默认的基于页面、限制/偏移和游标的方案。

基于游标的分页方案特别智能，对于客户端迭代大型或频繁更改的结果集是一种更好的方法。该方案通过使用游标和限制/偏移信息支持对非唯一的索引分页。它还允许正向和反向游标分页。David Cramer 对这个主题的博客文章赞不绝口。

可浏览 API 中的分页控件 (Pagination controls in the browsable API.)

分页结果现在包括直接在可浏览 API 中渲染的控件。如果您正在使用页面或限制/偏移样式，那么您将在可浏览的 API 中看到基于页面的控件：

基于游标的分页渲染出更简单的控件样式：

支持基于标头的分页 (Support for header-based pagination.)

分页 API 以前只能更改响应正文中的分页样式。API 现在支持能够在响应标头中写入分页信息，从而可以使用使用 Link 或 Content-Range 标头的分页方案。

有关更多信息，请参阅自定义分页样式文档。

版本控制 (Versioning)

我们使构建版本化 API 变得更容易。内置版本方案包括基于 URL 和基于 Accept 标头的变体。

当使用基于 URL 的方案时，超链接序列化器将解决与传入请求相同的 API 版本的关系。

例如,当使用 NamespaceVersioning，以下超链接序列化器：

class AccountsSerializer(serializer.HyperlinkedModelSerializer):
    class Meta:
        model = Accounts
        fields = ('account_name', 'users')

输出表示将与传入请求上使用的版本匹配。像这样：

GET http://example.org/v2/accounts/10  # Version 'v2'
{
    "account_name": "europa",
    "users": [
        "http://example.org/v2/users/12",  # Version 'v2'
        "http://example.org/v2/users/54",
        "http://example.org/v2/users/87"
    ]
}

国际化 (Internationalization)

REST framework 现在包含一组内置的翻译，并支持国际化的错误响应。这允许您更改默认语言，或者允许客户端通过 Accept-Language 标头指定语言。

您可以使用标准 Django LANGUAGE_CODE 设置更改默认语言：

LANGUAGE_CODE = "es-es"

您可以通过将 LocalMiddleware 添加到 MIDDLEWARE_CLASSES 设置来打开每个请求的语言请求：

MIDDLEWARE_CLASSES = [
    ...
    'django.middleware.locale.LocaleMiddleware'
]

当启用每个请求的国际化时，客户端请求将尽可能尊重 Accept-Language 标头。例如，让我们请求不受支持的媒体类型：

Request

GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org

Response

HTTP/1.0 406 NOT ACCEPTABLE
{
    "detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
}

注意，错误响应的结构仍然相同。我们在响应中仍然有一个 detail 键。如果需要，您也可以通过使用自定义异常处理程序修改此行为。

我们包含了针对标准异常情况和序列化器验证错误的内置翻译。

支持的语言的完整列表可以在我们的 Transifex 项目页面上找到。

如果您只想支持一部分受支持的语言，请使用 Django 的标准 LANGUAGES 设置：

LANGUAGES = [
    ('de', _('German')),
    ('en', _('English')),
]

有关更多详细信息，请参阅国际化文档。

非常感谢 Craig Blaszczyk 帮助推动这一过程。

新字段类型 (New field types)

Django 1.8 的新 ArrayField，HStoreField 和 UUIDField 现在都完全支持。

这项工作还意味着我们现在有了 serializers.DictField() 和 serializers.ListField() 类型，允许您表达和验证更广泛的表示集。

如果您正在构建一个新的 1.8 项目，那么您应该考虑使用 UUIDField 作为所有模型的主键。此样式将自动与超链接序列化器一起工作，返回以下样式的 URL：

http://example.org/api/purchases/9b1a433f-e90d-4948-848b-300fdc26365d

ModelSerializer API

3.0 中的序列化器重新设计不包含任何公共 API，用于修改 ModelSerializer 类如何从给定的模式类自动生成一组字段。我们现在为此重新引入了一个 API，允许您创建行为不同的新 ModelSerializer 基类，例如为关系使用不同的默认样式。

有关更多信息，请参阅有关为 ModelSerializer 类自定义字段映射的文档。

Moving packages out of core

我们现在已经将许多软件包从 REST framework 的核心移到了独立的可安装包中。如果您当前正在使用这些，则无需担心，您只需要 pip install 新软件包，并更改任何导入路径。

我们进行此更改是为了帮助分配维护工作负载，并更好地关注框架的核心要素。

这一变化也意味着我们可以更灵活地使用我们推荐的外部软件包。例如，出色维护的 Django OAuth 工具包现在已经被提升为集成 OAuth 支持的推荐选项。

以下包现在已移出核心，应单独安装：

• OAuth - djangorestframework-oauth
• XML - djangorestframework-xml
• YAML - djangorestframework-yaml
• JSONP - djangorestframework-jsonp

值得重申的是，除了添加新要求和修改某些导入路径之外，策略的更改不应该意味着您的代码库中的任何工作。例如，要安装 XML 渲染，您现在可以：

pip install djangorestframework-xml

并修改您的设置，如下所示：

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework_xml.renderers.XMLRenderer'
    ]
}

感谢我们维护团队的最新成员 JoséPadilla 处理这项工作并承担这些包的所有权。

弃用 (Deprecations)

request.DATA，request.FILES 和 request.QUERY_PARAMS 属性从等待弃用变为已弃用。请使用 request.data 和 request.query_params，正如 3.0 版本注释中所讨论的那样。

write_only_fields、view_name 和 lookup_field 的 ModelSerializer 元选项也从等待弃用改为弃用。使用 extra_kwargs，正如 3.0 版本注释中所讨论的那样。

所有这些属性和选项在 3.1 中仍然有效，但是它们的使用将引起警告。它们将在 3.2 中被完全删除。

What’s next?

下一个重点是 API 输出的 HTML 渲染，包括：

• 序列化器的 HTML 表单渲染。
• 可浏览 API 内置的过滤控件。
• 另一种管理样式的接口。

这将作为单个 3.2 版本发布，或者分为两个单独的版本，HTML 表单和过滤器控件将在 3.2 中出现，管理样式界面将在 3.3 版本中发布。