这篇文章会从由 rest framework 的 viewsets, router, ModelSerializer 构建的一个基础的 API 开始, 然后对其进行自定义.
建议阅读部分 rest framework 的教程
版本 :
Django==2.0.1
djangorestframework==3.7.7
Github地址

其它:

通过 viewsets, router, ModelSerializer 构建一个关于博客的 API

构建博客的 model

一篇文章需要有:

标题
文章主体
发布时间
标签
作者

标签和文章的关系应该是多对多(一篇文章可以有多个标签,一个标签可以关联多篇文章)
作者和文章的关系应该是一对多(一个作者可以有多篇文章,一篇文章只有一个作者)
需要的model有三个: 文章(Post), 标签(Tag), 作者(User)

class Post(models.Model):
    """
    title:标题
    body:主体
    pub_time:发布时间
    tag:标签,多对多
    author:作者,一对多
    """
    title = models.CharField(max_length=100, blank=True, default='')
    body = models.TextField()
    pub_time = models.DateTimeField(auto_now_add=True)
    tags = models.ManyToManyField('Tag', related_name='posts', blank=True)
    author = models.ForeignKey('auth.User', related_name='posts', on_delete=models.CASCADE)

    class Meta:
        ordering = ('-pub_time',)


class Tag(models.Model):
    name = models.CharField(max_length=50)

作者model 使用 Django 的 User model, 便利验证和权限管理

构建 Serializer

Serializer 是 rest framework 非常重要的一个部分
在 Django 中一般是 Model 和 View 之间交互,由 View 处理请求,把数据传给Model, View 展现从 Model 得到的数据
而在 rest framework 中 Serializer 就相当于 Model 和 View 的中间处理,将从 Model 中得到的数据序列化后交给 View, 将从 View 中得到的数据反序列化后交给 Model

新建 serializer.py 使用 HyperlinkedModelSerializer 构建 Serializer:

from django.contrib.auth.models import User
from restAPI.models import Post, Tag


class PostSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Post
        fields = ('url', 'id', 'title', 'pub_time', 'author', 'body', 'tags')


class TagSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Tag
        fields = ('url', 'id', 'name', 'posts')


class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'id', 'username', 'posts')

HyperlinkedModelSerializer 默认会为关系数据生成 url, 所以不用在 Tag 和 User中声明 fields 中的 'posts'

构建 View

设置权限, 新建 permission.py:

from rest_framework import permissions


class IsAuthorOrReadOnly(permissions.BasePermission):
    """
    只允许作者修改但允许所有人读的权限设置
    """

    def has_object_permission(self, request, view, obj):
        # 所有用户都允许读取,所以安全的http方法会直接放行
        # SAFE_METHODS = ('GET', 'HEAD', 'OPTIONS')
        if request.method in permissions.SAFE_METHODS:
            return True

        # 写入权限需要作者本人
        return obj.author == request.user

用 viewsets 构建 View:

from rest_framework import viewsets, permissions, mixins
from django.contrib.auth.models import User
from restAPI.models import Post, Tag
from restAPI.serializers import PostSerializer, TagSerializer, UserSerializer
from restAPI.permissions import IsAuthorOrReadOnly


class PostViewSet(viewsets.ModelViewSet):
    """
    处理 /api/posts/ GET POST , 处理 /api/post/<pk>/ GET PUT PATCH DELETE
    """
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly, IsAuthorOrReadOnly)
    
    def perform_create(self, serializer):
    """
    重写 perform_create
    user 信息不在 request.data 中, 在保存时加入 user 信息
    """
    serializer.save(author=self.request.user)
    

class TagViewSet(mixins.CreateModelMixin,
                 mixins.ListModelMixin,
                 mixins.RetrieveModelMixin,
                 viewsets.GenericViewSet):
    """
    处理 /api/tags/ GET POST, 处理 /api/tags/<pk>/ GET
    """
    queryset = Tag.objects.all()
    serializer_class = TagSerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly,)


class UserViewSet(viewsets.ReadOnlyModelViewSet):
    """
    处理 /api/users/ GET, 处理 /api/users/<pk>/ GET
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer

ModelViewSet 通过 create() 中 get_serializer(data=request.data) 将数据传给 serializer, 但是 user 信息并不在 request.data 中,而是作为 request 的一个属性, 所以通过重写 perform_create() 在保存时添加 user

构建 urls

因为使用的是 viewsets 所有通过 router 构建 urls 非常简单: 项目 urls:

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('restAPI.urls'))
]

app urls:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from restAPI.views import PostViewSet, TagViewSet, UserViewSet

router = DefaultRouter()
router.register(r'posts', PostViewSet)
router.register(r'tags', TagViewSet)
router.register(r'users', UserViewSet)

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

include(router.urls) 会帮我们直接生成好

/api/posts/
/api/posts/<pk>/
/api/users/
/api/users/<pk>/
/api/tags/
/api/tags/<pk>/

结尾

到此基础的 API 就构建完了, 但是还留有一些问题:

GET /api/posts/ 得到的序列中的 'body' 是全部的信息, 我们在获取 posts 列表的时候不需要那么完整的信息, 导致流量浪费, 在tag author中只有链接,信息太少
GET /api/tags/ posts 只有链接, 信息太少

这些会在下一篇中解决

用Django REST framework 编写RESTful API(2.对viewsets和modelseriaizer自定义)

其它:

用Django REST framework 编写RESTful API(3.添加评论模块)