Django-RESTful Api之请求与响应
这篇讲什么
- DRF 在 Django 的请求与响应之上各包了一层:
Request多了统一的.data,Response能按Accept头或 URL 后缀渲染成不同格式。 - 这篇把这两层的差异、格式后缀、状态码与错误响应的形状讲清楚,并对照
@api_view与APIView两种入口。实测环境 Django 5.2.19 + DRF 3.18.3。
配置应用
本篇实测环境:Django 5.2.19 + DRF 3.18.3。
1 | INSTALLED_APPS = [ |
Request 对象
-
DRF 的
Request是对 DjangoHttpRequest的包装,视图里拿到的就是它。实测一个 JSON POST 打进来时的属性:1
2
3
4
5
6data_type: dict | data: {"a": 1, "b": [2, 3]}
query_params: {"x": "1", "y": "2"}
POST: {}
user: AnonymousUser | auth: None | version: None
accepted_renderer: JSONRenderer | accepted_media_type: application/json
content_type: application/json | method: POSTrequest.data能接住所有请求体的格式(JSON、表单、multipart),而request.POST只有表单数据、且只认 POST;实测同样一份数据用application/json发时request.POST是空字典。request.data还能接住PUT/PATCH的 body,这是老笔记最需要的改动点。- 表单进来时
request.data是QueryDict,值是列表(实测{'a': ['表单值']});JSON 进来时是普通dict,值就是标量。写视图时按这个差别取值。 request.query_params就是 URL 查询串(等价于request.GET,但语义更清楚)。request.auth是认证类返回的凭据对象(Token 认证时是Token实例),request.version是版本控制类解析出来的版本。
-
解析器(parser)决定能不能读 body
实测默认三个:
1
2
3
4DEFAULT_PARSER_CLASSES:
rest_framework.parsers.JSONParser
rest_framework.parsers.FormParser
rest_framework.parsers.MultiPartParser-
用没装的 Content-Type 发请求,直接 415(实测原文):
1
不支持的 Content-Type: 415 | {'detail': 'Unsupported media type "text/plain" in request.'}
-
body 不是合法 JSON 时是 400(实测):
1
解析错误: 400 | {'detail': 'JSON parse error - Expecting property name enclosed in double quotes: line 1 column 2 (char 1)'}
-
Response 对象
-
实测签名:
1
2Response.__init__: (self, data=None, status=None, template_name=None,
headers=None, exception=False, content_type=None)1
resp = Response({"k": 1}, status=202, headers={"X-Test": "abc"})
1
status: 202 | header: abc | CT: text/html; charset=utf-8
-
Response不是立刻渲染的响应:它是「数据 + 待协商」,真正的Content-Type由内容协商决定(实测构造时给的content_type=也会被渲染阶段覆盖),所以别指望用它来指定 MIME。 -
脱离视图直接
render()会炸(实测):1
AssertionError: .accepted_renderer not set on Response
- 原因:渲染器是视图分发阶段挂到
request.accepted_renderer上的,手工 new 出来的Response没有这个上下文。
- 原因:渲染器是视图分发阶段挂到
-
-
内容协商实测
1
2
3
4Accept=application/json -> 200 | Content-Type=application/json
Accept=text/html -> 200 | Content-Type=text/html; charset=utf-8 # 可浏览 API
Accept=application/xml -> 406 | Content-Type=application/json
Accept=*/* -> 200 | Content-Type=application/json- 默认渲染器实测是
JSONRenderer+BrowsableAPIRenderer,所以只要 JSON 和 HTML 两种表现层,要 XML 就是 406。 - 浏览器直接打开接口地址看到的那个能填表单的页面,就是
BrowsableAPIRenderer:实测响应里有<form,但匿名时页面里的登录框才带 CSRF,接口本身不返回csrfmiddlewaretoken。
- 默认渲染器实测是
格式后缀(format suffix)
-
路由上包一层
format_suffix_patterns,就能用.json这种后缀指定表现层:school/urls.py 1
2
3
4
5
6
7
8
9
10from django.urls import path
from rest_framework.urlpatterns import format_suffix_patterns
from school import views
urlpatterns = [
path("fbv/students/", views.students_list),
path("fbv/students/<int:pk>", views.student_detail),
]
urlpatterns = format_suffix_patterns(urlpatterns) -
视图必须多接一个
format参数,否则实测直接 500:1
TypeError: students_list() got an unexpected keyword argument 'format'
views.py 1
2def students_list(request, format=None):
... -
实测哪些写法能用:
1
2
3
4
5/api/fbv/students.json -> 200 | application/json
/api/fbv/students/?format=json -> 200 | application/json
/api/fbv/students/.json -> 404 # 斜杠后面加点是错的
/api/fbv/students.json?format=api -> 200 | application/json # 后缀优先于查询参数
/api/fbv/students.bogus -> 404- 正确形式是
资源.json(不带结尾斜杠)或资源/?format=json;老笔记写的students.api属于前者,是对的。 - router 生成的路由里主键写成
(?P<pk>[^/.]+),就是为了把点号留给后缀。
- 正确形式是
状态码与错误响应
-
别写裸数字。实测
rest_framework.status里有 64 个HTTP_*常量:1
2
3HTTP_200_OK=200 HTTP_201_CREATED=201 HTTP_204_NO_CONTENT=204
HTTP_400_BAD_REQUEST=400 HTTP_401_UNAUTHORIZED=401 HTTP_403_FORBIDDEN=403
HTTP_404_NOT_FOUND=404 HTTP_405_METHOD_NOT_ALLOWED=405 HTTP_415_UNSUPPORTED_MEDIA_TYPE=4151
2
3from rest_framework import status
return Response(serializer.data, status=status.HTTP_201_CREATED)- 还有分类函数:
status.is_client_error(404)、is_success(204)、is_server_error(500)实测均为True。
- 还有分类函数:
-
实测这一组响应形状(
/api/plain/是is_valid(raise_exception=True)的视图):1
2
3
4GET 打只支持 POST 的视图: 405 | Allow: POST, OPTIONS
合法 POST: 200 | {'收到': {'name': 'n', 'age': 5, 'grade_name': 'g'}}
同样数据用表单发: 400 | {'name': ['This field is required.'], 'age': [...], 'grade_name': [...]}
不支持的 Content-Type: 415 | {'detail': 'Unsupported media type "text/plain" in request.'}- 405 的响应体是空的,判断要看状态码和
Allow头。 - 「用表单的方式发 JSON 的字段」会得到 400 + 每个字段都 required,这是新手最常见的假 bug:其实是 Content-Type 不对导致
request.data为空。
- 405 的响应体是空的,判断要看状态码和
视图的两种入口
1 | # 函数式 |
- 两者提供的能力一样:把
HttpRequest换成 DRFRequest、把Response渲染成协商后的结果、异常统一交给exception_handler、方法不对自动回 405。 - 实测
@api_view(["GET"])的视图收到 POST 是 405,且Allow: GET, OPTIONS——OPTIONS是自动加的,不用自己写。
新手卡点清单
-
都是实测踩过的:
卡点 症状(实测原文) 正确做法 用 request.POST取 JSON空字典,字段全 This field is required.用 request.data用 text/plain发 body415 Unsupported media type "text/plain" in request.发 application/json或表单body 是坏 JSON 400 {'detail': 'JSON parse error - ...'}客户端先自检序列化 加了 format_suffix_patterns但视图没format=NoneTypeError: ... got an unexpected keyword argument 'format'视图签名加 format=None后缀写成 students/.json404 写 students.json或students/?format=json手工 Response(...).render()AssertionError: .accepted_renderer not set on Response只在视图里返回,让它走协商 用 Response(content_type=...)指定 MIME头还是 text/html; charset=utf-8用渲染器/ Accept协商决定只配 JSON 渲染器却收 Accept: application/xml406 客户端别要没提供的表现层 以为 405 有错误正文 实测响应体为空 判状态码 + Allow头
参考
- Django REST framework:Requests and Responses:
request.data、query_params、auth等属性说明。 - Django REST framework:Serializers(Content negotiation):渲染器与内容协商。
- Django REST framework:Parsers:
JSONParser/FormParser/MultiPartParser。 - Django REST framework:API Reference — status:
HTTP_*常量表。 - Django REST framework:Format suffixes:
format_suffix_patterns与format参数约定。