Django REST framework教程二: 请求和响应

教程索引目录

Django REST framework的系列教程

对于需要通篇了解的同学，可以点击教程索引目录。

从现在开始，我们要开始，真正接触到REST framework的核心部分了。当然，我们需要先认识一些重要的基本元素。

请求对象（Request object）

REST framework引入了一个

Request

对象， 它继承自普通的

HttpRequest

,但能够更加灵活的解析收到的请求。

Request

对象的核心功能，就是其中的

request.data

属性。这个属性跟

request.POST

相似，但对我们的Web API来说，更加的有用。

request.POST  # 只能处理表单(form)数据，只能处理“POST”方法.
request.data  # 处理任意数据.可以处理'POST', 'PUT' 和 'PATCH'方法.

响应对象（Response object）

REST framework 同时引入了

Response

对象，是一种

TemplateResponse

，它携带着纯粹的内容，通过内容协商（Content Negotiation）来决定，将以何种形式，返回给客户端。

return Response(data)  # 根据客户端的要求，把内容，生成对应的形式.

状态码（Status codes）

在你的视图里，使用纯数字的状态码，并不利于代码阅读，如果你写错了状态码，也不会很容易的察觉。REST framework为每个状态码提供了更加明确的标识，比如

HTTP_400_BAD_REQUEST

，这个标识符在

status

模块中。我们在各处，使用这种标识符，而不是纯数字的状态码，这是个很好的想法。

包装API视图（wrapping API views）

REST framework提供了两种编写API view的封装。

使用

@api_view

装饰器，基于方法的视图

继承

APIView

类，基于类的视图

这些视图封装，提供了些许的功能，比如：确保你的视图能够收到

Request

实例；还有，将内容赋予

Response

对象，使得 内容协商（content negotiation) 可以正常的运作。

视图封装，也内置了一些行为，比如：在遇到错误请求时，自动响应

405 Method Not Allowed

；在处理

request.data

时，因为输入的格式不恰当，而发生的任何

ParseError

异常（exception），视图封装都会处理。

将所有元素 合起来

现在，让我们继续，用这些新的元素来写几个视图。

我们不再需要

view.py

文件中

JSONResponse

类了，所以尽管删掉它吧。然后，我们可以开始有一点，细微的重构了。

from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer

@api_view(['GET', 'POST'])
def snippet_list(request):
"""
列出所有的代码片段（snippets），或者创建一个代码片段（snippet）
"""
if request.method == 'GET':
snippets = Snippet.objects.all()
serializer = SnippetSerializer(snippets, many=True)
return Response(serializer.data)

elif request.method == 'POST':
serializer = SnippetSerializer(data=request.data)
if serializer.is_valid():
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

当前的实例，相比之前的例子，有了改进：它变得，简洁了一点，并且，如果你曾经使用过Forms API，你会发现，它们非常的相识。我们也用了命名式的状态码，这让响应的状态，易于阅读。

下面是snippet的详细视图，它在

views.py

模块中。

@api_view(['GET', 'PUT', 'DELETE'])
def snippet_detail(request, pk):
"""
读取, 更新 或 删除 一个代码片段实例（snippet instance）。
"""
try:
snippet = Snippet.objects.get(pk=pk)
except Snippet.DoesNotExist:
return Response(status=status.HTTP_404_NOT_FOUND)

if request.method == 'GET':
serializer = SnippetSerializer(snippet)
return Response(serializer.data)

elif request.method == 'PUT':
serializer = SnippetSerializer(snippet, data=request.data)
if serializer.is_valid():
serializer.save()
return Response(serializer.data)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

elif request.method == 'DELETE':
snippet.delete()
return Response(status=status.HTTP_204_NO_CONTENT)

目前为止，你应该感觉到很熟悉——它跟一般的Django视图，没多大的区别。

值得一提的是，我们已经不再明确地，解析/定义视图中 Request/Response的内容类型。

request.data

会自行处理输入的

json

请求，当然，也能处理别的格式。同样的，我们只需返回响应对象以及数据，REST framework会帮我们，将响应内容，渲染（render）成正确的格式。

为我们的URLs添加可选的格式后缀

现在，我们的响应，不再硬性绑定在，某一种返回格式上，利用这点优势，我们可以为API端，添加格式的后缀。使用格式后缀，可以定制我们的URLs，使它明确的指向指定的格式，这意味着，我们的API可以处理一些URLs，类似这样的格式

http://example.com/api/items/4/.json

。

首先，需要添加一个

format

关键字参数，如下所示：

def snippet_list(request, format=None):

还有：

def snippet_detail(request, pk, format=None):

然后对

urls.py

文件，做些小改。在现有的URLs基础上，追加一套

format_suffix_patterns

：

from django.conf.urls import url
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views

urlpatterns = [
url(r'^snippets/$', views.snippet_list),
url(r'^snippets/(?P<pk>[0-9]+)$', views.snippet_detail),
]

urlpatterns = format_suffix_patterns(urlpatterns)

我们不需要逐一地，添加对格式支持的 url 样式（patterns），这是一个简洁的方法，来快速支持特定的格式。

效果如何？

接着，我们可以从命令行中测试我们的API，跟教程一（tutorial part 1）中的操作一样。尽管我们对一些无效的请求，提供了很好的处理，但仍然没有太大的改变。

我们可以获取所有snippet的列表，就跟之前一样。

http http://127.0.0.1:8000/snippets/ 
HTTP/1.1 200 OK
...
[
{
"id": 1,
"title": "",
"code": "foo = \"bar\"\n",
"linenos": false,
"language": "python",
"style": "friendly"
},
{
"id": 2,
"title": "",
"code": "print \"hello, world\"\n",
"linenos": false,
"language": "python",
"style": "friendly"
}
]

我们也可以控制响应内容的格式，通过Http中的

Accept

头(header)：

http http://127.0.0.1:8000/snippets/ Accept:application/json  # 请求 JSON
http http://127.0.0.1:8000/snippets/ Accept:text/html         # 请求 HTML

或通过追加格式后缀（format suffix）：

http http://127.0.0.1:8000/snippets.json  # JSON 后缀
http http://127.0.0.1:8000/snippets.api   # 可视化 API 后缀

同样的，我们可以控制，发送的请求类型，通过http中的

Content-Type

头(header)：

# POST 使用表单数据
http --form POST http://127.0.0.1:8000/snippets/ code="print 123"

{
"id": 3,
"title": "",
"code": "print 123",
"linenos": false,
"language": "python",
"style": "friendly"
}

# POST 使用 JSON
http --json POST http://127.0.0.1:8000/snippets/ code="print 456"

{
"id": 4,
"title": "",
"code": "print 456",
"linenos": false,
"language": "python",
"style": "friendly"
}

现在，我们使用浏览器，访问 http://127.0.0.1:8000/snippets/ ，来请求我们的API。

可视化

由于 API 选择响应格式，是基于客户端发起的请求，因此，当接收到来着浏览器的请求时，会默认以HTML格式来描述数据。这让API能够返回，可以网页浏览（web-browsable）的HTML表现。

拥有网页浏览（web-browsable）的API，实在是非常的有用，使得开发和使用API，变成非常便利。这也大大降低了使用壁垒，让其它开发者，更加容易的查看和使用，你的API。

如需了解更多，有关可视化API的特性，以及如何定制，可以查阅专题：可视化API（browsable api）

下步做什么？

在教程第三部(tutorial part 3)，我们开始用基于类的视图，并看看通用视图(generic views)如何替我们省去大量的代码。

如果你觉得这个翻译非常有帮助，不妨小额赞助我一下，你的认可，是我的动力！