Python Django REST Framework实战：构建高效RESTful API-代码聚汇网

Python Django REST Framework实战：构建高效RESTful API

镝不咸·2026-08-13·阅读 23 GEO检测（免费）

PythonDjango REST FrameworkRESTful API

|难度：普通|阅读约 25 分钟

1. 项目概述：Python百天计划中的RESTful实战日

作为Python百天学习计划的第54天，这一章节聚焦于Web开发中至关重要的RESTful架构设计与Django REST Framework（DRF）的实战应用。这个节点安排在学习曲线中段非常合理——此时学习者已经掌握Python基础语法、Django框架核心概念，正需要将知识体系扩展到现代API开发领域。

RESTful架构作为当前Web服务和前后端分离开发的事实标准，其设计理念直接影响着API的可用性、可维护性和扩展性。而Django REST Framework作为Django生态中最成熟的REST框架，提供了从序列化、视图定义到权限控制的一站式解决方案。通过这一天的学习，开发者将获得构建生产级API服务的完整能力栈。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. RESTful架构核心原理解析

2.1 REST的六大约束原则

REST（Representational State Transfer）由Roy Fielding博士在2000年提出，其核心在于六个架构约束：

客户端-服务器分离：前端与后端完全解耦，通过标准接口通信
无状态：每个请求包含完整上下文，服务端不保存会话状态
可缓存：响应必须明确标识是否可缓存
统一接口：包括资源标识、通过表述操作资源、自描述消息和HATEOAS
分层系统：客户端无需知道是否直接连接最终服务器
按需代码（可选）：可下载并执行客户端脚本

实际开发中最常违反的是无状态原则。我曾见过在服务端用Redis存储临时状态的"伪REST"API，这会导致横向扩展时出现一致性问题。

2.2 资源导向的设计方法论

RESTful设计的核心是资源（Resource）而非动作。以博客系统为例：

错误设计：/getPosts?user=1 （动词导向）
正确设计：/users/1/posts （名词导向）

资源URI应该：

使用名词复数形式
采用层级关系表达关联
避免出现动词和操作后缀（如/addUser）
使用连字符-而非下划线_

2.3 HTTP方法的语义化使用

方法	幂等性	安全	典型用途
GET	是	是	获取资源
POST	否	否	创建资源
PUT	是	否	全量更新资源
PATCH	否	否	部分更新资源
DELETE	是	否	删除资源

常见误区：

用GET执行写操作（如/delete?id=1）
POST滥用导致资源操作语义模糊
忽略PATCH在部分更新时的性能优势

3. Django REST Framework深度配置

3.1 项目初始化与基础配置

安装DRF并添加到INSTALLED_APPS：

bash复制pip install djangorestframework

python复制# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework.authtoken',  # 如需Token认证
]

推荐的基础DRF配置：

python复制REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ],
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/hour',
        'user': '1000/hour'
    }
}

3.2 序列化器（Serializer）高级用法

序列化器是DRF的核心组件，处理数据转换和验证。以博客文章模型为例：

python复制from rest_framework import serializers
from .models import Post, Category

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

class PostSerializer(serializers.ModelSerializer):
    category = CategorySerializer(read_only=True)
    status_display = serializers.CharField(
        source='get_status_display', 
        read_only=True
    )
    
    class Meta:
        model = Post
        fields = ['id', 'title', 'content', 'category', 'status', 'status_display']
        extra_kwargs = {
            'status': {'write_only': True}
        }
    
    def validate_title(self, value):
        if len(value) < 10:
            raise serializers.ValidationError("标题至少需要10个字符")
        return value

高级技巧：

使用source参数映射模型方法或属性
嵌套序列化器处理关联关系
read_only/write_only控制字段可见性
自定义验证方法实现业务规则

3.3 视图与路由配置模式

DRF提供多种视图编写方式，适应不同复杂度需求：

APIView - 基础类，完全控制流程

python复制class PostList(APIView):
    def get(self, request):
        posts = Post.objects.all()
        serializer = PostSerializer(posts, many=True)
        return Response(serializer.data)

GenericAPIView - 通用模式抽象

python复制class PostDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    permission_classes = [IsOwnerOrReadOnly]

ViewSet - 组合操作+路由自动生成

python复制class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    
    @action(detail=True, methods=['post'])
    def publish(self, request, pk=None):
        post = self.get_object()
        post.status = 'published'
        post.save()
        return Response({'status': 'published'})

路由配置：

python复制from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register(r'posts', PostViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls')),
]

4. 生产环境必备功能实现

4.1 认证与权限控制

DRF提供丰富的认证方案：

Token认证 - 适合单页应用

python复制from rest_framework.authtoken.views import obtain_auth_token

urlpatterns = [
    path('api-token-auth/', obtain_auth_token),
]

JWT认证 - 更适合分布式系统

bash复制pip install djangorestframework-simplejwt

python复制REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ]
}

自定义权限示例：

python复制from rest_framework import permissions

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

4.2 过滤、搜索与排序

使用django-filter增强数据查询：

bash复制pip install django-filter

配置：

python复制REST_FRAMEWORK = {
    'DEFAULT_FILTER_BACKENDS': [
        'django_filters.rest_framework.DjangoFilterBackend',
        'rest_framework.filters.SearchFilter',
        'rest_framework.filters.OrderingFilter',
    ]
}

视图中的使用：

python复制class PostListView(generics.ListAPIView):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
    filterset_fields = ['category', 'status']
    search_fields = ['title', 'content']
    ordering_fields = ['created_at', 'view_count']

4.3 分页与限流

自定义分页类：

python复制from rest_framework.pagination import PageNumberPagination

class LargeResultsSetPagination(PageNumberPagination):
    page_size = 100
    page_size_query_param = 'page_size'
    max_page_size = 1000

限流配置：

python复制REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/hour',
        'user': '1000/hour',
        'burst': '50/minute'  # 自定义速率
    }
}

5. 常见问题与性能优化

5.1 N+1查询问题解决方案

使用select_related和prefetch_related优化关联查询：

python复制queryset = Post.objects.select_related('author').prefetch_related('tags')

或在序列化器中指定Prefetch对象：

python复制from django.db.models import Prefetch

queryset = Post.objects.prefetch_related(
    Prefetch('comments', queryset=Comment.objects.filter(is_approved=True))
)

5.2 序列化性能优化

使用SerializerMethodField谨慎，它会导致多次数据库查询
对于复杂计算，考虑在模型中添加缓存字段
使用defer()和only()控制查询字段

python复制queryset = Post.objects.only('id', 'title', 'created_at')

5.3 缓存策略实施

视图级缓存：

python复制from django.utils.decorators import method_decorator
from django.views.decorators.cache import cache_page

class PostListView(generics.ListAPIView):
    @method_decorator(cache_page(60*15))
    def dispatch(self, *args, **kwargs):
        return super().dispatch(*args, **kwargs)

使用cacheops库进行更细粒度缓存：

bash复制pip install django-cacheops

python复制from cacheops import cached_as

@cached_as(Post, timeout=60*60)
def get_queryset(self):
    return Post.objects.all()

6. 测试与文档自动化

6.1 API测试策略

使用DRF的APIClient进行单元测试：

python复制from rest_framework.test import APITestCase

class PostAPITestCase(APITestCase):
    def setUp(self):
        self.user = User.objects.create_user(
            username='test', 
            password='test123'
        )
        self.token = Token.objects.create(user=self.user)
        self.client.credentials(HTTP_AUTHORIZATION='Token ' + self.token.key)
    
    def test_create_post(self):
        data = {'title': 'Test', 'content': '...'}
        response = self.client.post('/api/posts/', data)
        self.assertEqual(response.status_code, 201)

6.2 自动化文档生成

使用drf-yasg或drf-spectacular生成Swagger文档：

bash复制pip install drf-spectacular

配置：

python复制INSTALLED_APPS += ['drf_spectacular']

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'Blog API',
    'DESCRIPTION': 'A sample blog API',
    'VERSION': '1.0.0',
}

添加文档路由：

python复制from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('schema/', SpectacularAPIView.as_view(), name='schema'),
    path('docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

7. 项目进阶与扩展方向

GraphQL集成：使用graphene-django为特定场景提供GraphQL端点
WebSocket支持：结合Django Channels实现实时API
异步视图：DRF 3.13+支持异步视图函数
微服务拆分：将单体DRF应用拆分为多个专门服务
性能监控：集成APM工具如New Relic或Sentry

在真实项目中，我曾遇到一个需要处理高并发写入的场景。最终方案是：

使用DRF的异步支持
写入操作通过Celery异步队列处理
采用读写分离数据库架构
关键端点使用Redis缓存

这种组合使API的吞吐量从200 RPM提升到5000+ RPM，同时保持响应时间在200ms以内。