1. DRF入门基础为什么选择Django REST framework如果你正在用Django开发Web应用迟早会遇到需要构建API的场景。Django REST framework简称DRF就是为此而生的利器。我最初接触DRF是在一个电商项目里当时需要快速构建商品和订单的RESTful API接口。相比自己从头实现DRF提供的功能简直像开了外挂。DRF的核心价值在于它解决了API开发中的三大痛点数据序列化、请求处理和权限管理。举个例子当你需要把Django模型转换成JSON格式返回给前端时DRF的序列化器Serializer能自动处理字段类型转换、关联关系等复杂问题。我曾在没有DRF的项目中手动实现过类似功能光是处理日期格式和外键关联就写了上百行代码而用DRF只需要定义一个简单的序列化器类。提示DRF的浏览器友好API界面是它的一大特色。开发时可以直接在浏览器中测试接口这对前后端协作非常友好。记得我第一次演示这个功能时前端同事当场决定把项目技术栈换成DjangoDRF。2. 环境搭建与基础配置2.1 安装与基础配置安装DRF只需要一条简单的pip命令pip install djangorestframework然后在settings.py中添加配置INSTALLED_APPS [ ... rest_framework, ] REST_FRAMEWORK { DEFAULT_PERMISSION_CLASSES: [ rest_framework.permissions.AllowAny, # 初学者可以先设置为允许所有访问 ] }这里有个实际项目中的经验建议同时安装django-filter和markdown这两个可选依赖。前者用于API过滤后者能让浏览器API界面显示更友好的文档。我在一个客户项目中就因为没有安装django-filter导致后来添加过滤功能时不得不中断开发去解决依赖问题。2.2 第一个API示例让我们创建一个简单的博客文章API。首先在models.py中定义模型from django.db import models class Article(models.Model): title models.CharField(max_length200) content models.TextField() created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue)接着创建serializers.pyfrom rest_framework import serializers from .models import Article class ArticleSerializer(serializers.ModelSerializer): class Meta: model Article fields __all__ # 包含所有字段最后在views.py中创建视图from rest_framework import viewsets from .models import Article from .serializers import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet): queryset Article.objects.all() serializer_class ArticleSerializer在urls.py中配置路由from django.urls import path, include from rest_framework.routers import DefaultRouter from .views import ArticleViewSet router DefaultRouter() router.register(rarticles, ArticleViewSet) urlpatterns [ path(, include(router.urls)), path(api-auth/, include(rest_framework.urls, namespacerest_framework)), ]现在访问http://localhost:8000/articles/就能看到你的第一个DRF API了这个简单的例子包含了DRF最核心的三大组件序列化器、视图集和路由器。3. DRF核心组件深度解析3.1 序列化器Serializer详解序列化器是DRF的灵魂组件它负责将QuerySet和模型实例转换为Python原生数据类型序列化将请求数据验证后转换为Django模型反序列化处理复杂的数据验证逻辑来看一个更复杂的序列化器例子class ArticleSerializer(serializers.ModelSerializer): # 添加计算字段 summary serializers.SerializerMethodField() # 自定义字段验证 title serializers.CharField(min_length5, max_length200) class Meta: model Article fields [id, title, content, summary, created_at] def get_summary(self, obj): return obj.content[:100] ... if len(obj.content) 100 else obj.content def validate_title(self, value): 自定义标题验证不能包含敏感词 forbidden_words [暴力, 色情, 政治] for word in forbidden_words: if word in value: raise serializers.ValidationError(f标题包含敏感词{word}) return value我在实际项目中遇到过的一个坑当序列化器包含嵌套关系时一定要小心处理循环引用。比如用户和文章互相引用时不加限制会导致无限递归。解决方法是在Meta中设置depth属性或明确定义嵌套序列化器。3.2 视图View与视图集ViewSetDRF提供了多种视图类从最基本的APIView到高度封装的ModelViewSet。选择哪种视图取决于你的需求复杂度APIView最基础的视图类相当于Django的ViewGenericAPIView增加了对序列化器和查询集的支持ListCreateAPIView同时支持列表和创建操作ModelViewSet完整支持CRUD操作视图集(ViewSet)的特别之处在于它将多个视图逻辑组合在一起并通过路由器自动生成URL。下面是一个自定义视图集的例子from rest_framework.decorators import action from rest_framework.response import Response class ArticleViewSet(viewsets.ModelViewSet): ... action(detailTrue, methods[post]) def publish(self, request, pkNone): article self.get_object() article.is_published True article.save() return Response({status: published})这个自定义动作可以通过/articles/ /publish/访问。我在一个CMS系统中就用这种方式实现了文章的发布、撤回和置顶等业务逻辑。4. 高级功能与实战技巧4.1 认证与权限控制DRF提供了完善的认证系统常用的认证方式包括TokenAuthentication适合前后端分离项目SessionAuthentication适合传统Django项目JWT认证需要安装djangorestframework-simplejwt权限控制示例from rest_framework.permissions import IsAuthenticated, BasePermission class IsAuthorOrReadOnly(BasePermission): 自定义权限只有文章作者可以编辑其他用户只读 def has_object_permission(self, request, view, obj): if request.method in SAFE_METHODS: return True return obj.author request.user class ArticleViewSet(viewsets.ModelViewSet): permission_classes [IsAuthenticated, IsAuthorOrReadOnly] ...重要提示永远不要在生产环境使用AllowAny权限。我曾接手过一个项目因为开发阶段设置了AllowAny上线后忘记修改导致数据被恶意篡改。4.2 过滤、搜索与分页DRF与django-filter配合可以实现强大的过滤功能from django_filters.rest_framework import DjangoFilterBackend from rest_framework.filters import SearchFilter, OrderingFilter class ArticleViewSet(viewsets.ModelViewSet): filter_backends [DjangoFilterBackend, SearchFilter, OrderingFilter] filterset_fields [is_published, author] search_fields [title, content] ordering_fields [created_at, views] ordering [-created_at] # 默认排序分页配置通常在settings.py中REST_FRAMEWORK { DEFAULT_PAGINATION_CLASS: rest_framework.pagination.PageNumberPagination, PAGE_SIZE: 20 }4.3 性能优化技巧使用select_related和prefetch_related优化查询queryset Article.objects.select_related(author).prefetch_related(tags)对于复杂查询可以考虑使用SerializerMethodField替代嵌套序列化器使用cache_page装饰器缓存API响应from django.views.decorators.cache import cache_page class ArticleViewSet(viewsets.ModelViewSet): cache_page(60 * 15) # 缓存15分钟 def list(self, request): ...5. 常见问题与解决方案5.1 跨域问题CORS解决方法安装django-cors-headerspip install django-cors-headers配置settings.pyINSTALLED_APPS [ ... corsheaders, ] MIDDLEWARE [ corsheaders.middleware.CorsMiddleware, ... ] CORS_ALLOW_ALL_ORIGINS True # 开发环境可以这样设置生产环境应该指定具体域名5.2 接口版本管理推荐使用URL路径版本控制REST_FRAMEWORK { DEFAULT_VERSIONING_CLASS: rest_framework.versioning.URLPathVersioning }然后在urls.py中urlpatterns [ path(api/v1/articles/, include(articles.urls)), path(api/v2/articles/, include(articles.v2.urls)), ]5.3 文档自动化DRF自带API文档功能也可以通过swagger或redoc增强from drf_yasg.views import get_schema_view from drf_yasg import openapi schema_view get_schema_view( openapi.Info( titleAPI文档, default_versionv1, ), publicTrue, ) urlpatterns [ path(swagger/, schema_view.with_ui(swagger, cache_timeout0)), path(redoc/, schema_view.with_ui(redoc, cache_timeout0)), ]6. 项目结构最佳实践经过多个DRF项目后我总结出以下推荐的项目结构myproject/ ├── apps/ │ ├── articles/ │ │ ├── serializers/ │ │ │ ├── v1.py │ │ │ └── v2.py │ │ ├── api/ │ │ │ ├── v1/ │ │ │ │ ├── views.py │ │ │ │ └── urls.py │ │ │ └── v2/ │ │ ├── models.py │ │ └── services.py # 业务逻辑 ├── config/ │ ├── settings/ │ │ ├── base.py │ │ ├── development.py │ │ └── production.py └── requirements/ ├── base.txt ├── development.txt └── production.txt这种结构的特点按功能划分应用articles, users等API版本分离v1, v2业务逻辑集中在services.py中配置和环境分离最后分享一个实用技巧使用drf-spectacular库可以自动生成OpenAPI 3.0规范的文档并且支持更丰富的字段描述和参数定义。我在最近的项目中使用它前端团队反馈文档的可读性提高了至少50%。
