目录

    笔者从事的SaaS开发,对开发效率有着比较高的要求。从项目立项、原型设计评估、需求确定、前端设计、后台开发到最后的验收,几个星期完成一次迭代。在敏捷开发的指导下,开始推行前后端分离模式。前端专注于页面和交互,后端专注于API接口。后端提供API,涉及权限认证、参数校验、异常处理、分页等一系列问题。同时,这些功能在项目之间又存在共性,寻找合适的API脚手架十分迫切。笔者之前研究过Django Restful接口之Tastypie,相比较于Tastypie的简易、快速上手,Django REST Framework(DRF)需要更多的配置,同时功能更加强大,可以用于快速开发API接口。

    1. 功能简介

    • 支持 OAuth 认证
    • 支持对 ORM 和非 ORM 数据源的序列化
    • 丰富的定制层级:函数视图、类视图、视图集合
    • 内置Mixins,可以用于快速组装

    2. 基本概念

    • Serializer序列化

    序列化是将 Python 数据结构转换为其它数据格式,比如将Django Model映射到Json。

    序列化是提供了数据的验证和渲染功能。其工作方式类似于 Django Form,基于 Field 进行字段验证。序列化之后的数据保存在 serializer.data中的,可以使用 SomeRenderer().render(serializer.data) 将其序列化为字符串对象作为 Response body 返回。

    • ViewSet视图

    DRF 通过 View 提供 API 接口,一个 View 可以对应多个 Renderer,针对不同的渲染条件提供不同的输出格式(HTML/XML/JSON)。

    ViewSet 则是 View 的一个封装,一个 ViewSet 可以为同一个 URL 根据请求方法提供不同的接口。尤其是 ModelViewSet 会自动根据 Model 的定义生成 REST 接口和 URL,能够快速生成网站的一整套 API。

    • Request对象。

    DRF使用Requests对象扩展了原生的HttpRequest,并提供了更灵活的请求处理。Requests对象的核心属性就是request.data,可以处理任意数据,接受POST、PUT和PATCH方法。

    3. DRF处理流程

    4. DRF应用

    DRF的使用主要分为三步:定义资源 - 实现HTTP方法 - 配置URL。

    4.1 安装配置

    pip install djangorestframework
    

    在settings.py的INSTALLED_APPS中加入:

    INSTALLED_APPS = (
        ...
        'rest_framework',
        ...
    )
    

    4.2 定义资源,实现序列化

    models.py

    from django.db import models
    
    class Fruit(models.Model):
        name = models.CharField(u'名称', default="", max_length=255)
        price = models.FloatField(u"单价", default=0)
    

    serializers.py

    from rest_framework import serializers
    from .models import Fruit
    
    class FruitSerializer(serializers.HyperlinkedModelSerializer):
        class Meta:
            model = Fruit
            fields = ('name', 'price')
    

    4.3 继承View,重写HTTP Method

    views.py

    from rest_framework.viewsets import ModelViewSet
    from .models import Fruit
    from .serializers import FruitSerializer
    
    class FruitViewSet(ModelViewSet):
        queryset = Fruit.objects.all()
        serializer_class = FruitSerializer
    
    

    FruitViewSet直接继承ModelViewSet,ModelViewSet继承了一系列Mixins类的HTTP方法。如果需要自定义HTTP方法,可以继承APIView类,或者Mixins类,还可以完全自定义。

    4.4 配置URL

    urls.py

    from django.conf.urls import patterns, url, include
    from rest_framework import routers
    from .views import FruitViewSet
    
    router = routers.DefaultRouter()
    router.register(r'fruit', FruitViewSet)
    
    urlpatterns = [
        url(r'^api/v1/', include(router.urls)),
    ]
    

    配置到此,一个基本的API接口已经完成。访问http://localhost:8000/api/v1/,会显示:

    4.5 权限

    REST_FRAMEWORK = {
        'DEFAULT_PERMISSION_CLASSES': [
            'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
        ]
    }
    

    4.6 分页控制

    class YourView(BaseView):
        paginate_by = 10                 # 覆盖 settings 中的默认分页
        max_paginate_by = 100             # 限制最大分页大小
    

    也可以动态地去判断最大分页大小:

    class YouView(BaseView):
        ...
        def paginate_queryset(self, queryset):
            self.paginator.max_page_size = YOUR_PAGE_SIZE_LIMIT
            return super(YouView, self).paginate_queryset(queryset)
    

    4.7 外键处理

    from rest_framework import serializers
    
    class HospitalSerializer(serializers.HyperlinkedModelSerializer):
        class Meta:
            model = Hospital 
            fields = '__all__' 
    
    class HospitalPicSerializer(serializers.HyperlinkedModelSerializer):
        hospital = HospitalSerializer()
    
        class Meta:
            model = HospitalPic
            fields = '__all__'
    

    4.8 流量限制

    REST_FRAMEWORK = {
        'DEFAULT_THROTTLE_CLASSES': (
            'rest_framework.throttling.AnonRateThrottle',
            'rest_framework.throttling.UserRateThrottle'
        ),
        'DEFAULT_THROTTLE_RATES': {
            'anon': '100/day',
            'user': '1000/day'
        }
    }
    
    class ExampleView(APIView):
        throttle_classes = (UserRateThrottle,)
    
        def get(self, request, format=None):
            content = {
                'status': 'request was permitted'
            }
            return Response(content)
    

    限制API查询的频率,可以根据用户不同,精确到每天、每小时、每分钟。

    4.9 Mixins

    Django-rest-framework为我们提供了许多现成的mixins,可以用于快速组合接口。

    • GenericAPIView提供了view核心的功能
    • ListModelMixin提供了.list()方法
    • CreateModelMixin提供了.create()方法

    在View函数中,可以这样使用:

    from .models import Fruit
    from .serializers import FruitSerializer
    from rest_framework import mixins
    from rest_framework import generics
    
    class FruitList(mixins.ListModelMixin, mixins.CreateModelMixin, generics.GenericAPIView):
        queryset = Fruit.objects.all()
        serializer_class = FruitSerializer
    
        def get(self, request, *args, **kwargs):
            return self.list(request, *args, **kwargs)
    
        def post(self, request, *args, **kwargs):
            return self.create(request, *args, **kwargs)
    

    5. 参考