用Django REST framework写API的示例分析

# 用Django REST framework写API的示例分析

## 目录
1. [Django REST framework简介](#django-rest-framework简介)
2. [环境准备与项目创建](#环境准备与项目创建)
3. [快速创建第一个API](#快速创建第一个api)
4. [序列化器(Serializer)详解](#序列化器serializer详解)
5. [视图(Views)的多种实现方式](#视图views的多种实现方式)
6. [路由(Routers)配置](#路由routers配置)
7. [认证与权限控制](#认证与权限控制)
8. [分页与过滤](#分页与过滤)
9. [API文档生成](#api文档生成)
10. [最佳实践与性能优化](#最佳实践与性能优化)

---

## Django REST framework简介

Django REST framework（简称DRF）是建立在Django框架之上的强大而灵活的工具包，用于构建Web API。它提供了以下核心功能：

- **序列化**：支持ORM和非ORM数据源的转换
- **视图和路由**：简化API端点的创建
- **认证与权限**：内置多种认证方案
- **测试客户端**：方便API测试
- **可浏览的API界面**：自动生成Web界面

```python
# 典型DRF项目结构
project/
├── settings.py       # Django配置
├── urls.py          # 主路由
└── api/
    ├── serializers.py  # 序列化器
    ├── views.py       # 视图
    └── urls.py       # API路由

---

环境准备与项目创建

1. 安装依赖

pip install django djangorestframework

2. 创建Django项目和应用

django-admin startproject api_project
cd api_project
python manage.py startapp books

3. 配置settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
    'books',
]

# DRF全局配置
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

---

快速创建第一个API

1. 定义模型

# books/models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    published_date = models.DateField()
    isbn = models.CharField(max_length=13)
    
    def __str__(self):
        return self.title

2. 创建序列化器

# books/serializers.py
from rest_framework import serializers
from .models import Book

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

3. 编写视图

# books/views.py
from rest_framework import generics
from .models import Book
from .serializers import BookSerializer

class BookListCreateView(generics.ListCreateAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

class BookRetrieveUpdateDestroyView(generics.RetrieveUpdateDestroyAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

4. 配置路由

# api_project/urls.py
from django.urls import path, include
from books import views

urlpatterns = [
    path('api/books/', views.BookListCreateView.as_view()),
    path('api/books/<int:pk>/', views.BookRetrieveUpdateDestroyView.as_view()),
]

---

序列化器(Serializer)详解

基本序列化器类型

1. ModelSerializer：自动根据模型生成字段
2. Serializer：手动定义字段
3. ListSerializer：处理多个对象

自定义字段验证

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'isbn']
    
    def validate_isbn(self, value):
        if len(value) not in [10, 13]:
            raise serializers.ValidationError("ISBN必须是10或13位")
        return value

嵌套关系处理

class AuthorSerializer(serializers.ModelSerializer):
    books = BookSerializer(many=True, read_only=True)
    
    class Meta:
        model = Author
        fields = ['id', 'name', 'books']

---

视图(Views)的多种实现方式

1. 基于函数的视图

from rest_framework.decorators import api_view

@api_view(['GET'])
def book_list(request):
    books = Book.objects.all()
    serializer = BookSerializer(books, many=True)
    return Response(serializer.data)

2. 基于类的视图

from rest_framework.views import APIView

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

3. 通用视图

from rest_framework import generics

class BookListCreate(generics.ListCreateAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

4. 视图集(ViewSets)

from rest_framework import viewsets

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

---

路由(Routers)配置

简单路由

from django.urls import path
from . import views

urlpatterns = [
    path('books/', views.BookList.as_view()),
    path('books/<int:pk>/', views.BookDetail.as_view()),
]

使用DefaultRouter

from rest_framework.routers import DefaultRouter
from .views import BookViewSet

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

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

---

认证与权限控制

常用认证方式

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ]
}

自定义权限

from rest_framework.permissions import BasePermission

class IsAdminOrReadOnly(BasePermission):
    def has_permission(self, request, view):
        if request.method in ['GET', 'HEAD', 'OPTIONS']:
            return True
        return request.user and request.user.is_staff

---

分页与过滤

基本分页配置

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20
}

使用DjangoFilterBackend

from django_filters.rest_framework import DjangoFilterBackend

class BookList(generics.ListAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    filter_backends = [DjangoFilterBackend]
    filterset_fields = ['author', 'published_date']

---

API文档生成

使用CoreAPI

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path('docs/', include_docs_urls(title='Book API')),
]

使用Swagger

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
   openapi.Info(
      title="Book API",
      default_version='v1',
   ),
   public=True,
)

urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0)),
]

---

最佳实践与性能优化

1. 性能优化技巧

• 使用select_related和prefetch_related
• 分页大数据集
• 使用缓存

2. 安全建议

• 始终使用HTTPS
• 限制敏感字段的序列化
• 实施适当的权限控制

3. 项目结构建议

api_project/
├── apps/
│   ├── books/
│   └── users/
├── config/
│   ├── settings/
│   └── urls.py
└── requirements/

4. 测试API

from rest_framework.test import APITestCase

class BookAPITestCase(APITestCase):
    def setUp(self):
        self.book = Book.objects.create(title="Test Book", author="Test Author")
    
    def test_get_books(self):
        response = self.client.get('/api/books/')
        self.assertEqual(response.status_code, 200)

---

通过本文的详细示例，您应该已经掌握了使用Django REST framework构建API的核心技术。DRF的强大之处在于它的灵活性和可扩展性，可以适应从简单到复杂的各种API开发需求。 “`