DRF 自带的资源处理方法

RESTFul 将路由处理成对资源的操纵，资源 直接与数据库的数据表和 django 中的数据模型绑定。

例如 /users/1 关联的资源是 users，一个 user 就是一个资源，它对应的数据表是 user，数据模型是 User。

继承自 ModelViewSet 的 ViewSet 会自带资源的常用处理方法：

• create() 创建一个资源
• retrieve() 取出一个资源
• update() 整体更新一个资源（更新全部字段）
• partial_update() 部分更新一个资源（更新部分字段）
• destroy() 删除一个资源
• list() 取出多个资源（可以是所有，也可以按照实际需要进行筛选和排序）

整体上，处理法可以分为两类：处理资源列表的方法和处理单个资源的方法。

继承 ModelViewSet 的子类必须指定queryset，在没有重写资源处理方法时，它是处理方法使用的默认查询集。

重写处理方法时，可以通过自带的get_queryset()方法获取默认的查询集，也可以使用其他查询集。

处理方法内部不能使用queryset属性获取默认查询集，该属性仅用作初始化默认查询集。

DRF 自定义资源处理方法

默认的 6 个资源处理方法往往不能满足复杂的需求，我们可能需要对资源添加更多的处理方法。

通过@action()装饰器方法添加额外的处理方法，添加的处理方法可以分为两类：处理资源列表的和处理单个资源的。

from rest_framework import viewsets
from rest_framework.decorators import action

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    
    @action(methods=['get'], detail=False, url_path='search')
    def search_users(self, request): pass
    
    @action(methods=['get'], detail=True, url_path='refresh')
    def refresh_status(self, request, pk): pass

@action()装饰器方法添加到动作方法的上方，它有三个重要的参数：

• url_path 处理方法对应的路由关键字，在处理资源列表和单个资源时这个关键字会被添加到不同位置
  • 处理资源列表的路由，例如 /users/search/
  • 处理单个资源的路由，例如 /users/1/refresh/
• detail True 表示这是一个处理单个资源的方法，False 表示这是一个处理资源列表的方法
• methods 哪些 http 请求方法能够被路由到这个处理方法

一个定义良好的自定义资源处理方法在 API Web 端能够被正确显示给用户：

• A: url_path设置的参数会被显示在 URL 的合适位置
• B: 动作方法的 注释文档 会被显示在这里
• C: 动作方法的函数名称会被适当转换然后显示在这里

所以一个规范的自定义动作需要：

• url_path 定义好动作的名称
• 函数名称能够表达动作的简要目的
• 函数注释文档能够表达动作的详细目的