DRF viewsets 和 routers 是什么？

Question

Accepted Answer

在 Django REST Framework 中，**viewsets** 将一组相关 API 端点（某个资源的 CRUD 操作）的逻辑组织到单个类中，而 **routers** 则自动为其生成 URL 路由。两者结合起来可以显著减少构建 RESTful APIs 的样板代码。

## ModelViewSet — 几行代码实现完整 CRUD

```python
from rest_framework import viewsets

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()             # the data
    serializer_class = ArticleSerializer          # how to serialize it
    # That's it! This provides ALL standard CRUD endpoints automatically:
    #   list (GET), create (POST), retrieve (GET /id), update (PUT/PATCH /id), destroy (DELETE /id)
```

`ModelViewSet` 会自动为某个模型提供**完整的 RESTful CRUD 端点集合**——list、create、retrieve、update、partial update 和 delete——仅需一个 queryset 和 serializer。无需单独编写每个视图。

## Routers — 自动生成 URL

```python
from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register(r"articles", ArticleViewSet)     # register the viewset

urlpatterns = router.urls
# automatically creates the RESTful URLs:
#   GET    /articles/        → list
#   POST   /articles/        → create
#   GET    /articles/{id}/   → retrieve
#   PUT    /articles/{id}/   → update
#   PATCH  /articles/{id}/   → partial update
#   DELETE /articles/{id}/   → destroy
```

**router** 会自动将 viewset 映射到完整的标准 RESTful URLs 集合——注册一个 viewset 就会生成所有常规端点，配备正确的 HTTP 方法，无需手动配置 URL。

## 自定义 viewsets

```python
class ArticleViewSet(viewsets.ModelViewSet):
    serializer_class = ArticleSerializer
    permission_classes = [IsAuthenticated]        # authorization

def get_queryset(self):                        # customize the data per request
        return Article.objects.filter(author=self.request.user)

# add CUSTOM endpoints beyond CRUD with @action
    @action(detail=True, methods=["post"])
    def publish(self, request, pk=None):           # POST /articles/{id}/publish/
        article = self.get_object()
        article.published = True
        article.save()
        return Response({"status": "published"})
```

Viewsets 通过重写方法（`get_queryset`、`perform_create`）、设置权限，以及添加**自定义操作**（`@action`）来进行自定义，以实现超出标准 CRUD 的端点。

## Viewsets 对比 generic API views

```text
ModelViewSet  → ALL CRUD in one class + router → least code for standard REST resources
Generic views (ListCreateAPIView, etc.) → more explicit, one class per endpoint group
APIView       → full manual control for non-standard/custom endpoints
→ Use viewsets+routers for conventional REST resources; generic/APIView for custom needs.
```

## 为什么这很重要

Viewsets 和 routers 是 DRF 中高效构建 RESTful APIs 的强大特性——它们代表了最高的抽象层次，适用于将模型公开为完整 REST 资源这一极其常见的场景，理解它们对高效的 API 开发至关重要。

关键优势是大幅**减少样板代码**：一个 `ModelViewSet` 加上一个 router，就能从仅仅一个 queryset 和 serializer 为某个资源生成一个完整、符合规范的 REST API（包含所有 CRUD 端点，对应正确的 HTTP 方法和 URL）——这本来需要许多单独的视图和手动的 URL 配置。

这使得构建标准 REST APIs 变得异常迅速，同时自动遵循 **RESTful 规范**（一致的 URL 结构和 HTTP 方法语义）。

Viewsets 保持灵活性——你可以通过重写方法来自定义它们（按用户过滤 queryset、控制权限、在 create/update 中加入钩子），以及添加**自定义操作**（`@action`）来实现超出基本 CRUD 的端点。

理解 viewsets 和 routers 的工作原理、如何自定义它们，以及**何时使用它们**（符合规范的 REST 资源）而不是更明确的 generic views 或 APIView（自定义/非标准端点），是 DRF 开发中的重要实践知识。

由于构建 REST APIs 是当今 Django 的主要用途，而 viewsets+routers 是针对标准资源最地道、最高效的方式，它们是 DRF 工具包中经常使用、至关重要的一部分，使开发者能够用最少的代码构建健壮的 APIs，同时保持处理自定义需求的灵活性。