Python大数据分析&人工智能教程 - Django-RestFramework框架（深入解析+实操案例）

1. Django-RestFramework 基础

1.1 Django-RestFramework 概述

Django-RestFramework（简称DRF）是一个强大的、灵活的工具集，用于构建Web API。它基于Django框架，允许开发者快速构建RESTful API。DRF的核心优势在于其提供了一系列工具，包括API的可视化、文档化、自动化测试以及自动化的API路由、序列化、视图、验证、分页、版本管理、认证等功能。

1.2 安装与配置

要开始使用DRF，首先需要安装Django和DRF。可以通过pip安装这两个库：

pip install django
pip install djangorestframework

在Django项目的settings.py文件中添加rest_framework到INSTALLED_APPS列表中，以启用DRF：

INSTALLED_APPS = [
    ...
    'rest_framework',
]

1.3 构建第一个API

创建一个简单的API，我们需要定义一个模型、一个序列化器、一个视图和一个URL路由。

1.3.1 定义模型

在models.py中定义一个模型：

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=100)
    publish_date = models.DateField()

    def __str__(self):
        return self.title

1.3.2 创建序列化器

在serializers.py中创建一个序列化器：

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'

1.3.3 定义视图

在views.py中定义一个视图：

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializerserializers import BookSerializerclass BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

1.3.4 配置URL路由

在urls.py中配置URL路由：

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

1.4 进阶功能

DRF提供了许多高级功能，包括权限控制、限流、版本控制等。

1.4.1 权限控制

在视图中添加权限控制：

from rest_framework.permissions import IsAuthenticated

class BookViewSet(viewsets.ModelViewSet):
    permission_classes = [IsAuthenticated]
    # ...

1.4.2 限流

在settings.py中配置限流：

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day'
    }
}

1.5 实战案例

假设我们需要构建一个图书管理系统的API，用户可以查看、创建、更新和删除图书信息。

1.5.1 创建图书

使用HTTP POST请求创建图书：

curl -X POST -H "Content-Type: application/json" -d '{"title": "New Book", "author": "Author Name", "publish_date": "2024-12-12"}' http://localhost:8000/books/

1.5.2 查询图书

使用HTTP GET请求查询图书：

curl http://localhost:8000/books/

1.5.3 更新图书

使用HTTP PUT请求更新图书：

curl -X PUT -H "Content-Type: application/json" -d '{"title": "Updated Book", "author": "Updated Author", "publish_date": "2024-12-12"}' http://localhost:8000/books/1/

1.5.4 删除图书

使用HTTP DELETE请求删除图书：

curl -X DELETE http://localhost:8000/books/1/

以上步骤展示了如何使用Django-RestFramework构建一个简单的图书管理系统API，包括创建、查询、更新和删除操作。通过这些基本操作，可以进一步扩展和构建更复杂的API功能。

2. 序列化器(Serializers)

2.1 序列化器概念与作用

序列化器在Django-RestFramework中扮演着至关重要的角色，它们充当模型实例和API表示之间的中间层。序列化器的主要功能是将复杂的数据类型，如查询集和模型实例，转换为Python数据类型，然后可以进一步渲染成JSON、XML等格式。反序列化是序列化的逆过程，它允许解析来自客户端的数据，并将这些数据转换回复杂的类型，同时进行数据验证。

2.2 序列化器的基本使用

在DRF中，定义一个序列化器通常涉及创建一个继承自serializers.Serializer的类，并在其中定义字段。以下是一个简单的序列化器示例：

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'

在这个例子中，BookSerializer自动为Book模型的每个字段生成一个序列化字段。fields = '__all__'表示序列化所有模型字段。

2.3 自定义字段和验证

序列化器允许自定义字段和验证逻辑。可以通过定义一个字段并指定其属性来实现：

class BookSerializer(serializers.ModelSerializer):
    title = serializers.CharField(max_length=100, allow_blank=False)

    class Meta:
        model = Book
        fields = ['title', 'author', 'publish_date']

在上面的代码中，title字段被定义为一个字符字段，并且不允许为空。如果客户端提交的title为空，DRF将返回一个验证错误。

2.4 序列化器方法

序列化器提供了一些方法来处理复杂的数据转换和验证。例如，可以使用SerializerMethodField来添加一个字段，其值由一个方法动态返回：

class BookSerializer(serializers.ModelSerializer):
    author_name = serializers.SerializerMethodField()

    class Meta:
        model = Book
        fields = ['title', 'author_name', 'publish_date']

    def get_author_name(self, obj):
        return obj.author.get_full_name()

在这个例子中，author_name字段的值是通过调用get_author_name方法动态生成的，该方法可以访问序列化器的当前对象obj。

2.5 序列化器与模型关系

序列化器与模型之间的关系是通过ModelSerializer类来定义的，它提供了一个快捷方式来自动生成与模型字段相对应的序列化器字段：

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publish_date']

在这个例子中，BookSerializer自动为Book模型的每个字段创建了一个序列化器字段，无需手动定义每个字段。

2.6 序列化器的嵌套使用

当模型之间存在外键或多对多关系时，可以通过嵌套序列化器来处理复杂的数据结构：

class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = ['id', 'name']

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True)

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publish_date']

在这个例子中，BookSerializer嵌套了一个AuthorSerializer来序列化Book模型中的author外键字段。

2.7 序列化器的验证

序列化器提供了在字段级别和对象级别进行数据验证的能力。可以通过定义validate_<field_name>方法来进行字段级别的验证：

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['title', 'author', 'publish_date']

    def validate_title(self, value):
        if len(value) < 5:
            raise serializers.ValidationError("Title must be at least 5 characters.")
        return value

在这个例子中，如果title字段的长度小于5个字符，将引发一个验证错误。

3. 视图(Views)

3.1 视图概念与作用

在Django-RestFramework（DRF）中，视图是处理请求、返回响应的中心环节。视图负责接收客户端的请求，调用相应的逻辑处理数据，并返回一个HTTP响应。DRF提供了多种视图类型，包括APIView、ViewSet、GenericAPIView等，它们提供了不同的功能和灵活性。

3.2 视图的基本使用

在DRF中，视图通常继承自rest_framework.views.APIView类，并实现get、post、put、patch、delete等方法来处理不同的HTTP请求。

from rest_framework.views import APIView
from rest_framework.response import Response
from .models import Book
from .serializers import BookSerializer

class BookList(APIView):
    def get(self, request, format=None):
        books = Book.objects.all()
        serializer = BookSerializer(books, many=True)
        return Response(serializer.data)

    def post(self, request, format=None):
        serializer = BookSerializer(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)

在这个例子中，BookList视图处理了获取图书列表（GET请求）和创建新图书（POST请求）的逻辑。

3.3 ViewSet的使用

ViewSet是DRF中处理路由和视图逻辑的另一种方式，它通过组合不同的动作（如list、create、retrieve、update、partial_update、destroy）来简化视图的编写。

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

使用ViewSet时，DRF会自动为我们处理标准的CRUD操作，并且可以通过路由器自动生成URL路由。

3.4 视图与序列化器的协作

视图和序列化器在DRF中紧密协作。序列化器负责数据的序列化和反序列化，而视图则负责调用序列化器，并处理业务逻辑。

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

    def update(self, request, *args, **kwargs):
        partial = kwargs.pop('partial', False)
        instance = self.get_object()
        serializer = self.get_serializer(instance, data=request.data, partial=partial)
        serializer.is_valid(raise_exception=True)
        self.perform_update(serializer)

        if getattr(instance, '_prefetched_objects_cache', None):
            # If 'prefetch_related' has been applied to a queryset, we need to
            # forcibly invalidate the prefetch cache on the instance.
            instance._prefetched_objects_cache = {}

        return Response(serializer.data)

在这个例子中，update方法展示了如何使用序列化器来更新数据。

3.5 视图的权限控制

视图可以通过设置permission_classes属性来控制权限，确保只有授权用户才能访问API。

from rest_framework.permissions import IsAuthenticated

class BookViewSet(viewsets.ModelViewSet):
    permission_classes = [IsAuthenticated]
    # ...

在这个例子中，IsAuthenticated权限类确保只有认证过的用户才能访问BookViewSet提供的API。

3.6 视图的异常处理

视图可以通过覆盖get_exception_handler方法来自定义异常处理逻辑。

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from rest_framework.exceptions import APIException

class BookList(APIView):
    def get(self, request, format=None):
        try:
            books = Book.objects.all()
            serializer = BookSerializer(books, many=True)
            return Response(serializer.data)
        except Exception as e:
            return Response({'error': str(e)}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

在这个例子中，如果查询图书时发生异常，视图将返回一个包含错误信息的HTTP 500响应。

3.7 视图的实际应用案例

以下是一个实际的应用案例，展示了如何使用视图来处理图书的查询和更新操作。

3.7.1 查询图书

使用HTTP GET请求查询图书：

curl http://localhost:8000/books/

3.7.2 更新图书

使用HTTP PUT请求更新图书：

curl -X PUT -H "Content-Type: application/json" -d '{"title": "Updated Book", "author": "Updated Author", "publish_date": "2024-12-12"}' http://localhost:8000/books/1/

以上步骤展示了如何使用Django-RestFramework的视图来处理图书查询和更新的实际应用案例。通过这些基本操作，可以进一步扩展和构建更复杂的API功能。

4. 路由(Routing)

4.1 路由概念与作用

在Django-RestFramework中，路由系统负责将HTTP请求映射到相应的视图函数。DRF提供了一个强大的路由器类DefaultRouter，它可以自动为我们的视图生成标准的CRUD路由。

4.2 使用DefaultRouter

DefaultRouter可以自动为我们的ViewSet生成路由，简化了手动创建URL模式的过程。以下是如何使用DefaultRouter的示例：

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

在这个例子中，DefaultRouter为BookViewSet自动生成了包括列表、创建、检索、更新、部分更新和删除操作的路由。

4.3 自定义路由

除了使用DefaultRouter，我们还可以手动定义路由，以满足更复杂的需求。以下是手动定义路由的示例：

from django.urls import path
from .views import BookList, BookDetail

urlpatterns = [
    path('books/', BookList.as_view(), name='book-list'),
    path('books/<int:pk>/', BookDetail.as_view(), name='book-detail'),
]

在这个例子中，我们为图书列表和详细视图定义了两个路由，分别处理图书的查询和更新操作。

4.4 路由的HTTP方法

DRF的路由系统支持所有标准的HTTP方法，包括GET、POST、PUT、PATCH和DELETE。这允许我们为不同的操作定义不同的路由。

4.5 路由的权限控制

DRF的路由系统可以与权限系统结合使用，以控制对特定路由的访问。以下是如何在路由级别添加权限控制的示例：

from rest_framework.permissions import IsAuthenticated

router = DefaultRouter()
router.register(r'books', BookViewSet, basename='book')
urlpatterns = [
    path('', include(router.urls)),
]

在这个例子中，如果BookViewSet设置了permission_classes，那么所有生成的路由都将应用这些权限。

4.6 路由的版本控制

DRF的路由系统支持版本控制，允许我们为不同的API版本定义不同的路由。以下是如何实现版本控制的示例：

from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books/v1', BookViewSet, basename='book-v1')

urlpatterns = [
    path('v1/', include(router.urls)),
]

在这个例子中，我们为API的第一个版本定义了一个前缀为v1的路由。

4.7 路由的实际应用案例

以下是一个实际的应用案例，展示了如何使用路由来处理图书的查询和更新操作。

4.7.1 查询图书列表

使用HTTP GET请求查询图书列表：

curl http://localhost:8000/v1/books/

4.7.2 更新图书

使用HTTP PUT请求更新图书：

curl -X PUT -H "Content-Type: application/json" -d '{"title": "Updated Book", "author": "Updated Author", "publish_date": "2024-12-12"}' http://localhost:8000/v1/books/1/

以上步骤展示了如何使用Django-RestFramework的路由来处理图书查询和更新的实际应用案例。通过这些基本操作，可以进一步扩展和构建更复杂的API功能。

5. 认证(Authentication)与权限(Permissions)

5.1 认证概念与实现

认证是确认用户身份的过程，它是保护API安全的第一道防线。在Django-RestFramework中，认证可以通过多种方式实现，包括Token认证、Session认证、Basic认证等。

5.1.1 Token认证

Token认证是一种常见的认证方式，适用于分布式系统和移动应用。以下是如何在DRF中实现Token认证的示例：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
    ],
}

# views.py
from rest_framework.authtoken.views import ObtainAuthToken
from rest_framework.authtoken.models import Token
from rest_framework.response import Response

class CustomAuthToken(ObtainAuthToken):
    def post(self, request, *args, **kwargs):
        serializer = self.serializer_class(data=request.data,
                                           context={'request': request})
        serializer.is_valid(raise_exception=True)
        user = serializer.validated_data['user']
        token, created = Token.objects.get_or_create(user=user)
        return Response({
            'token': token.key,
            'user_id': user.pk,
            'email': user.email
        })

# urls.py
from django.urls import path
from .views import CustomAuthToken

urlpatterns = [
    path('api-token-auth/', CustomAuthToken.as_view()),
]

在这个例子中，我们创建了一个自定义的Token认证视图CustomAuthToken，它在用户登录时返回一个Token，用户后续请求中需要在HTTP头部中包含这个Token。

5.1.2 Session认证

Session认证使用Django的会话框架来管理用户会话。以下是如何在DRF中启用Session认证的示例：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
    ],
}

在这个例子中，我们只需在settings.py中添加SessionAuthentication到DEFAULT_AUTHENTICATION_CLASSES即可启用Session认证。

5.2 权限控制

权限控制是限制用户对API资源访问的手段。DRF提供了多种权限类，可以根据不同的业务需求来配置权限。

5.2.1 基本权限类

以下是一些DRF内置的权限类及其用途：

• AllowAny：允许所有用户访问。
• IsAuthenticated：只允许认证过的用户访问。
• IsAdminUser：只允许管理员用户访问。
• IsAuthenticatedOrReadOnly：认证用户可以进行读写操作，未认证用户只能进行读操作。

5.2.2 自定义权限类

在某些情况下，内置的权限类可能无法满足需求，这时可以创建自定义权限类。以下是如何创建自定义权限类的示例：

from rest_framework.permissions import BasePermission

class IsOwnerOrReadOnly(BasePermission):
    def has_object_permission(self, request, view, obj):
        if request.method in permissions.SAFE_METHODS:
            return True
        return obj.owner == request.user

在这个例子中，IsOwnerOrReadOnly权限类允许只有对象的所有者可以进行写操作，其他用户只能进行读操作。

5.2.3 在视图中应用权限

以下是如何在视图中应用权限类的示例：

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer
from .permissions import IsOwnerOrReadOnly

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    permission_classes = [IsOwnerOrReadOnly]

    # ...

在这个例子中，BookViewSet使用了IsOwnerOrReadOnly权限类，确保只有图书的所有者可以更新或删除图书。

6. 分页(Pagination)与过滤(Filtering)

6.1 分页概念与实现

分页是将大量数据分割成多个页面的过程，这在处理大量数据时非常有用，可以提高应用的性能并改善用户体验。Django-RestFramework（DRF）提供了强大的分页功能，允许开发者轻松实现分页。

6.1.1 分页类

DRF内置了多种分页类，可以方便地实现分页功能。以下是如何配置和使用分页的示例：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

在这个配置中，我们设置了默认的分页类为PageNumberPagination，并指定了每页显示10条数据。

6.1.2 自定义分页类

如果内置的分页类不满足需求，可以创建自定义分页类。以下是自定义分页类的示例：

from rest_framework.pagination import PageNumberPagination

class CustomPagination(PageNumberPagination):
    page_size = 5
    page_size_query_param = 'size'
    max_page_size = 100

在这个自定义分页类中，我们设置了每页显示5条数据，允许通过查询参数size来指定每页的数据量，并且限制了最大请求页面大小为100。

6.1.3 分页的实际应用案例

以下是一个实际的应用案例，展示了如何在图书API中实现分页：

curl http://localhost:8000/books/?page=2

使用这个命令可以查询图书列表的第二页数据。

6.2 过滤概念与实现

过滤是限制返回数据集的一种方式，它允许客户端根据需要请求特定数据。DRF提供了通用的过滤后端，可以轻松实现过滤功能。

6.2.1 通用过滤后端

以下是如何在settings.py中配置通用过滤后端的示例：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
}

在这个配置中，我们添加了DjangoFilterBackend作为默认的过滤后端。

6.2.2 自定义过滤器

如果需要更复杂的过滤逻辑，可以创建自定义过滤器。以下是自定义过滤器的示例：

import django_filters
from .models import Book

class BookFilter(django_filters.FilterSet):
    min_price = django_filters.NumberFilter(name='price', lookup_expr='gte')
    max_price = django_filters.NumberFilter(name='price', lookup_expr='lte')

    class Meta:
        model = Book
        fields = ['category', 'in_stock', 'min_price', 'max_price']

在这个自定义过滤器中，我们为Book模型添加了价格范围过滤和库存状态过滤。

6.2.3 过滤的实际应用案例

以下是一个实际的应用案例，展示了如何在图书API中实现过滤：

curl http://localhost:8000/books/?category=fiction&in_stock=True

使用这个命令可以查询分类为小说且有库存的图书。

通过以上内容，我们详细介绍了Django-RestFramework中的分页和过滤功能，包括概念、原理、解决方案以及应用场景实操案例的代码及详细说明。这些内容可以帮助开发者在实际项目中快速实现分页和过滤功能，提高API的性能和用户体验。