Django-RESTful Api设计风格

这篇讲什么

  • 这篇是接口设计的约定清单:协议与域名、版本号放哪、路径怎么命名、HTTP 方法怎么用对、过滤排序分页怎么做、状态码和错误响应怎么定。
  • 每条约定都配了 DRF 里的落地写法,能在本机验证的(分页、排序、状态码、格式后缀)都按 Django 5.2.19 + DRF 3.18.3 跑过。

协议与域名

  • 协议:API 与用户的通信一律用 HTTPS。HTTP 明文会把令牌(Token)、会话 cookie 全暴露在链路上,等于没做认证。

  • 域名:尽量把 API 部署在专用域名下,例如 https://api.example.com;如果 API 很简单、不会扩展,放在主域名的子路径(https://www.example.com/api/)也可以。

  • 本项目里 API 挂在子路径上(实测路由写法):

    proj/urls.py
    1
    2
    3
    4
    5
    6
    from django.urls import include, path

    urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("school.urls")),
    ]

版本

  • 版本要显式化,常见两种放法:放进 URL 路径(/api/v1/students/)或放进请求头(Accept: application/json; version=1.0)。

  • DRF 把版本控制做成可插拔的类,实测 rest_framework.versioning 里可用的有 5 个(外加基类):

    1
    2
    AcceptHeaderVersioning, BaseVersioning, HostNameVersioning,
    NamespaceVersioning, QueryParameterVersioning, URLPathVersioning
    版本类 版本写在哪 适用场景
    URLPathVersioning URL 路径 v1/ 最常见,浏览器里一眼能看出来
    NamespaceVersioning Django 命名空间 每个版本一套 urls.py,隔离最彻底
    AcceptHeaderVersioning Accept 头 严格 REST 派,路径不变
    QueryParameterVersioning ?version=1.0 调试方便,但污染查询串
    HostNameVersioning 域名 v1.api.example.com 需要 DNS/网关配合
    settings.py
    1
    2
    3
    4
    5
    6
    REST_FRAMEWORK = {
    "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",
    "DEFAULT_VERSION": "v1",
    "ALLOWED_VERSIONS": ["v1", "v2"],
    "VERSION_PARAM": "version",
    }

    一个实测坑:override_settings(REST_FRAMEWORK=...) 不会改变已经导入的视图行为——DRF 的 APIView 把 filter_backends、pagination_class 这类默认值在类定义时就绑成了类属性。要验证这类配置,得在视图上显式写,或者改完 settings.py 重启进程。

路径

  • 路径表示资源的具体网址。每个 URI 代表一种资源,所以 URL 里不要有动词,只用名词,且名词一般与表名对应。
  • 单数还是复数要统一(本项目统一用复数:/api/students/、/api/students/1/)。
  • 实测 DRF 生成的路由就是这种形状(DefaultRouter 注册 StudentViewSet 后):
    1
    2
    student-list    ^vs/students/$
    student-detail ^vs/students/(?P<pk>[^/.]+)/$
    注意主键那段是 [^/.]+ 而不是 [^/]+:故意排除点号,好让格式后缀(.json)能被单独识别。
  • 层级关系用路径表达,别用查询串:/api/grades/1/students/(某班学生)优于 /api/students?grade=1(后者适合过滤,不适合表达归属)。

使用正确的 HTTP 方法

  • HTTP 方法与 SQL 操作的对应关系:

    方法 语义 对应 SQL 是否幂等
    GET 查 SELECT 是
    POST 增 INSERT 否
    PUT 全量改 UPDATE(整行) 是
    PATCH 部分改 UPDATE(指定列) 是
    DELETE 删 DELETE 是
  • 实测 DRF 各写法支持的方法集合:

    1
    2
    3
    @api_view(["GET", "POST"]) 的视图收到 DELETE -> 405 | Allow: POST, GET, OPTIONS
    mixins 只挂 list/create 时收到 PATCH -> 405
    generics.RetrieveUpdateDestroyAPIView 收到 PATCH -> 200 | 只改传上来的字段
    • Allow 头是 405 的标配,客户端据此知道该换哪个方法。
    • PATCH 在 DRF 里对应 serializer(..., partial=True) 语义:必填字段可以缺省。
  • 安全方法(不改状态)在权限里被单列出来,实测:

    1
    permissions.SAFE_METHODS: ('GET', 'HEAD', 'OPTIONS')

    IsAuthenticatedOrReadOnly 就是靠它判断「读放行、写要登录」。

过滤、排序、搜索、分页

  • 资源多时不能一次全返回,要提供参数让客户端筛选。约定式的写法:

    1
    GET /api/students?grade=1&sex=true&search=张&ordering=-age&page=2&size=3
    • 参数允许冗余:/api/grades/1/students/?sex=true 这种「路径 + 查询」重复是可以的。
  • 实测:光在视图上写 filterset_fields 不生效,必须挂后端。 同一个视图类,一个显式写了 filter_backends、一个没写:

    1
    2
    3
    4
    5
    6
    本班过滤(显式写了 DjangoFilterBackend): 200 | 条数: 25
    另一个班过滤: 200 | 条数: 0
    search=pgx1: 200 | 条数: 3 | 第一条: pgx1
    ordering=-age 前两条: [60, 60]
    乱写 ordering: 200 | 条数: 25 # 非法值直接忽略,不报错
    同一 search 参数打给没写 filter_backends 的视图: 200 | 条数: 25 # 参数被无视
    school/views.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    from django_filters.rest_framework import DjangoFilterBackend
    from rest_framework.filters import OrderingFilter, SearchFilter
    from rest_framework.generics import ListAPIView


    class FilteredStudents2(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    filter_backends = (DjangoFilterBackend, SearchFilter, OrderingFilter)
    filterset_fields = ("grade", "sex")
    search_fields = ("name",)
    ordering_fields = ("age", "name")
    • django-filter 本机版本 26.2;DRF 自带的只有 SearchFilter / OrderingFilter(实测 rest_framework.filters 里还有 UnaccentedSearchFilter),字段级过滤要靠 DjangoFilterBackend。
  • 分页同理,实测三种分页类的响应形状:

    1
    2
    3
    4
    5
    6
    7
    8
    PageNumberPagination: 200 | 键: ['count', 'next', 'previous', 'results'] | count: 25 | 本页: 3
    next: http://testserver/api/paged/?page=2 | previous: None
    第二页: 200 | 条数: 3
    越界页 ?page=999: 404 | {'detail': 'Invalid page.'}
    page_size_query_param(?size=5): 200 | 条数: 5
    LimitOffsetPagination(?limit=3&offset=2): 键 ['count', 'next', 'previous', 'results'] | 条数: 3
    CursorPagination: 键 ['next', 'previous', 'results'] # 没有 count
    视图没写 pagination_class 时: 200 | 类型: ReturnList # 还是裸数组
    • ?page=999 是 404(Invalid page.),不是空列表——前端要按 404 处理。

    • CursorPagination 不返回总数,适合无限下拉;但它要求 queryset 有序,否则实测会打警告:

      1
      2
      UnorderedObjectListWarning: Pagination may yield inconsistent results with an
      unordered object_list: <class 'school.models.Student'> QuerySet.

      解决:模型 Meta.ordering 或 queryset 上 order_by("id")。

状态码

  • 状态码是服务器给客户端的结论,光靠数字不够直观,DRF 提供了常量(实测 dir(rest_framework.status) 里 HTTP_* 共 64 个):

    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
    • 还有分类函数:status.is_client_error(404)、status.is_success(204)、status.is_server_error(500) 实测都是 True。
  • 本项目里实测到的真实对应关系:

    场景 状态码 实测响应
    新建成功 201 返回新对象
    删除成功 204 响应体为空
    校验失败 400 {"name": ["This field is required."]}
    请求体不是合法 JSON 400 {"detail": "JSON parse error - ..."}
    只配了 TokenAuthentication 且没带令牌 401 {"detail": "Authentication credentials were not provided."}
    默认(Session+Basic)下未登录写数据 403 {"detail": "You do not have permission to perform this action."}
    非资源所有者改数据 403 同上
    资源不存在 404 {"detail": "No Student matches the given query."}
    方法不支持 405 带 Allow 头
    Accept 要的表现层没有 406 —

    401 与 403 的区别实测得很干净:有没有「认证类能接住你」决定 401/403。配了 TokenAuthentication 时缺凭据是 401;只有 Session/Basic 时缺凭据是 403。

错误处理

  • 4xx 一定要带出错信息,且结构要固定。DRF 的默认形状有两类:

    • 视图层异常(ValidationError、ParseError、NotFound…)走 exception_handler,返回 {"detail": "..."};
    • 序列化器错误是按字段的字典:{"字段名": ["消息", ...]}。
  • 实测原文:

    1
    2
    3
    4
    5
    raise_exception=True: 400 | {"age": ["Ensure this value is greater than or equal to 0."]}
    缺字段: 400 | {"name": ["This field is required."], "grade_name": ["This field is required."]}
    方法不允许: 405 | {"detail": "Method \"GET\" not allowed."}
    解析错误: 400 | {"detail": "JSON parse error - Expecting property name enclosed in double quotes: line 1 column 2 (char 1)"}
    detail 不存在: 404 | {"detail": "No Student matches the given query."}
  • 一个反直觉的点(实测):视图里 return Response(serializer.errors, status=400) 不走异常处理器,所以自定义 EXCEPTION_HANDLER 对它无效。想让所有错误形状统一,就在视图里用 serializer.is_valid(raise_exception=True),把出错交给 exception_handler:

    school/views.py
    1
    2
    3
    4
    5
    class PlainView(APIView):
    def post(self, request):
    serializer = PlainSerializer(data=request.data)
    serializer.is_valid(raise_exception=True) # 不合法就抛 ValidationError
    return Response({"收到": serializer.validated_data})
    settings.py
    1
    REST_FRAMEWORK = {"EXCEPTION_HANDLER": "school.exceptions.my_exception_handler"}
    school/exceptions.py
    1
    2
    3
    4
    5
    6
    7
    8
    from rest_framework.views import exception_handler


    def my_exception_handler(exc, ctx):
    response = exception_handler(exc, ctx)
    if response is not None:
    response.data = {"code": "bad_request", "detail": response.data}
    return response

响应结果与超链接

  • 约定每种操作的返回体:

    • GET /students/:资源列表(配了分页则是 {count, next, previous, results})。
    • GET /students/1/:单个资源对象。
    • POST /students/:新建成功返回这个对象本身(201),方便前端拿到服务端生成的 id。
    • PUT / PATCH:返回更新后的对象。
    • DELETE:204,不返回内容。
  • 资源之间用链接关联,而不是只给裸 id。DRF 的 HyperlinkedModelSerializer 实测:

    1
    2
    3
    4
    不带 context: AssertionError `HyperlinkedIdentityField` requires the request in the
    serializer context. Add `context={'request': request}` ...
    带 context 仍报错: ImproperlyConfigured Could not resolve URL for hyperlinked
    relationship using view name "student-detail". ...
    • 第一条好懂:超链接字段需要 request 才能拼绝对地址。

    • 第二条是命名空间坑(实测):应用的 urls.py 里写了 app_name = "school",路由真实名字是 school:student-detail,而序列化器默认找 student-detail,于是整个接口 500。要么去掉 app_name,要么显式指定:

      1
      2
      3
      4
      5
      6
      7
      8
      class StudentHyperSerializer(serializers.HyperlinkedModelSerializer):
      class Meta:
      model = Student
      fields = ("url", "id", "name", "age", "grade", "owner")
      extra_kwargs = {
      "url": {"view_name": "school:student-detail"},
      "grade": {"view_name": "school:grade-detail"},
      }
      1
      带命名空间反解: /api/vs/students/8/
  • 一份「设计规范 ↔ DRF 落地」对照表:

    规范条目 DRF 里的落地手段
    只用 HTTPS 部署层 + SECURE_SSL_REDIRECT、SESSION_COOKIE_SECURE
    URL 无动词 Router / path() 生成的 list/detail 路由
    版本显式化 versioning 的 5 个版本类
    表现层协商 Accept / 格式后缀 / DEFAULT_RENDERER_CLASSES
    过滤排序搜索 DjangoFilterBackend + SearchFilter + OrderingFilter
    分页 三种 Pagination 类
    语义化状态码 rest_framework.status 的 64 个常量
    统一错误结构 exception_handler + raise_exception=True
    资源互链 HyperlinkedModelSerializer(注意命名空间)
    接口文档 drf-spectacular 生成 OpenAPI 3.0.3(见《Django-常用插件》)

新手卡点清单

  • 都是实测踩过的:

    卡点 症状(实测原文) 正确做法
    只写 filterset_fields 不挂后端 参数完全被忽略,返回全量 视图上写 filter_backends,或 settings 配好再重启
    用 override_settings(REST_FRAMEWORK=...) 验证过滤/分页 行为没变(类属性在定义时已绑定) 显式写在视图类上
    分页越界当空列表处理 404 {'detail': 'Invalid page.'} 按 404 分支处理
    分页 queryset 没排序 UnorderedObjectListWarning 加 Meta.ordering 或 order_by("id")
    乱写 ordering 参数 不报错,静默忽略 前端只传 ordering_fields 里的名字
    自定义 EXCEPTION_HANDLER 后错误形状没变 视图自己 return Response(errors) 不走它 用 is_valid(raise_exception=True)
    Hyperlinked 序列化器不带 context AssertionError ... requires the request in the serializer context 传 context={"request": request}
    应用有 app_name 还用裸名做超链接 ImproperlyConfigured Could not resolve URL ... "student-detail" view_name="school:student-detail"
    以为缺凭据一定 401 只有 Session/Basic 时实测是 403 按认证类判断,401/403 都要处理

参考

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