Django REST framework API Guide 之 Responses

发表于 | 分类于

虽然变阅读边翻译有点慢，但是理解会深一些，加油鸭。

概览

在官网上，DRF 的 API Guide 涉及如下模块：

  • Requests 请求
  • Response 响应
  • Views 视图
  • Generic views 通用视图
  • Viewsets 视图集合类
  • Routers 路由器
  • Parsers 解释器
  • Renderers 渲染器
  • Serializers 序列化器
  • Serializer fields 序列化器字段
  • Serializer relations 序列化器之间的关系
  • Validators 验证器
  • Authentication 认证
  • Permissions 权限
  • Caching 缓存
  • throttling 限流
  • Filtering 过滤
  • Pagination 分页
  • Versioning 版本
  • Content negotiation 内容协商
  • Metadata 元数据
  • Schemas 架构
  • Format suffixes 格式后缀
  • Returning URLS 返回url
  • Exceptions 异常
  • Status codes 状态码
  • Testing 测试
  • Settings 设置

Responses

Unlike basic HttpResponse objects, TemplateResponse objects retain the details of the context that was provided by the view to compute the response. The final output of the response is not computed until it is needed, later in the response process.
— Django documentation

REST framework 通过提供一个 Response 类来支持 HTTP 内容协商，这个 Response 类允许你按照客户端的请求，将内容渲染成多种类型后返回。

Response 类继承于 Django 的 SimpleTemplateResponse。Response 对象在初始化时所用的数据应该是 python 原生的数据类型。REST framework 之后会依据 HTTP 内容协商来决定这些数据最终会渲染成何种类型。

你并没有被强制要求使用 Response 类，如果你认为有必要，你也可以返回常规的 HttpResponse 或者 StreamHttpResponse 对象。使用 Response 类仅仅提供了一个更好接口去返回经过内容协商后的 Web API 响应，因为它可以将内容渲染成不同格式。

除非出于某种特殊原因，你想魔改 REST framework，否则对于view而言，你应该用 APIView 类，或者　＠api_view 函数，并返回　Response 对象。这样做可以确保 view 可以进行内容协商，在响应返回前，view 可以选择合适的渲染器（去渲染需要返回的数据）。

Creating Responses

Response()

实例化：　Response(data, status=None, template_name=None, headers=None, content_type=None)
与常规的 HttpResponse 对象不同，你初始化 Response 对象的时候，你并不使用已经渲染好的数据。相反你放入为渲染的数据，可能是任何的　python 基础类型数据。

Response 类所用的渲染器并不能天然地处理复杂的数据类型，比如 Django 的model 实例。所以你需要在创建 Response 对象之前，将数据序列化为 python 基础数据类型。

你可以使用 REST framework 的 Serializer 类来进行数据序列化，或者你自己的序列化器。

参数解释：

  • data: 用于response 的序列化后的数据。
  • status: 用于 response 的状态码，默认值是 200, 更多细节参看https://www.django-rest-framework.org/api-guide/status-codes/
  • template_name: 一个模板名称，如果 HTMLRenderer 被选了。
  • headers: 包含response中HTTP headers 的字典。
  • content_type: response 的内容格式。一般而言，这个会基于内容协商所定的渲染器而自动设置，当然有时候也需要你显示的设置内容格式。

Attributes

.data

response 已经序列化后但是未被渲染的数据。

.status_code

HTTP response 状态码（数字形式）

.content

resonse 已经被渲染后的内容，在获取.content之前，.render()方法需要先被执行。

.template_name

如果提供了模板名。只有在 HTMLRender 或者用户提供的模板渲染器是被接受的渲染器的时候，这个值才是必须的。

.accepted_renderer

被用于渲染response 的渲染器。在 response 即将从view被返回时，这个值被APIView和＠api_view自动设置。

.accepted_media_type

依据内容协商而被选中的媒体格式类型。在 response 即将从view被返回时，这个值被APIView和＠api_view自动设置。

.renderer_context

一组字典形式的额外上下文信息，会被传递到 renderer 的　.render()方法中。
在 response 即将从view被返回时，这个值被APIView和＠api_view自动设置。

Standard HttpResponse attributes

Response 类是对 SimpleTemplateResponse 的扩展，所以后者中所有的普通字段和方法在前者中同样可用。比如，你可以在Response 对象中像在SimpleTemplate　对象中那样去设置HTTP头部信息：

1
2
response = Response()
response['Cache-Control'] = 'no-cache'

.render()

如同想其他 TemplateResponse 那样，当这个方法被调用时，序列化后的数据会被渲染成最后返回的数据。更具体地，该方法被调用时，.content 未被设置为　accepted_renderer.render(data, accepted_media_type, renderer_context)的返回值。

一般而言，你不需要亲自调用 .render()，因为它会被按照 Django 的标准响应流程进行处理。