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。

settings.py
1
2
3
4
5
6
7
8
9
10
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"school",
"rest_framework",
]

Request 对象

  • DRF 的 Request 是对 Django HttpRequest 的包装,视图里拿到的就是它。实测一个 JSON POST 打进来时的属性:

    1
    2
    3
    4
    5
    6
    data_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: POST
    • request.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
    4
    DEFAULT_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
    2
    Response.__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
    4
    Accept=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
    10
    from 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
    2
    def 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
    3
    HTTP_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=415
    1
    2
    3
    from 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
    4
    GET 打只支持 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 为空。

视图的两种入口

views.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 函数式
from rest_framework.decorators import api_view
from rest_framework.response import Response


@api_view(["GET", "POST"])
def students_list(request, format=None):
if request.method == "GET":
return Response(StudentSerializer(Student.objects.all(), many=True).data)
serializer = StudentSerializer(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)


# class 式(细节见《Django-RESTful-Api之基于类的视图》)
class StudentsList(APIView):
def get(self, request, format=None):
return Response(StudentSerializer(Student.objects.all(), many=True).data)
  • 两者提供的能力一样:把 HttpRequest 换成 DRF Request、把 Response 渲染成协商后的结果、异常统一交给 exception_handler、方法不对自动回 405。
  • 实测 @api_view(["GET"]) 的视图收到 POST 是 405,且 Allow: GET, OPTIONS——OPTIONS 是自动加的,不用自己写。

新手卡点清单

  • 都是实测踩过的:

    卡点 症状(实测原文) 正确做法
    用 request.POST 取 JSON 空字典,字段全 This field is required. 用 request.data
    用 text/plain 发 body 415 Unsupported media type "text/plain" in request. 发 application/json 或表单
    body 是坏 JSON 400 {'detail': 'JSON parse error - ...'} 客户端先自检序列化
    加了 format_suffix_patterns 但视图没 format=None TypeError: ... got an unexpected keyword argument 'format' 视图签名加 format=None
    后缀写成 students/.json 404 写 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/xml 406 客户端别要没提供的表现层
    以为 405 有错误正文 实测响应体为空 判状态码 + Allow 头

参考

本文结束 感谢您的阅读
正在加载今日诗词....