Quickstart

本章内容中我们将创建一个简单的API来允许管理员编辑用户和群组。

Project setup（创建项目）

创建一个名为tutorial的Django项目，然后新建一个名为quickstart的应用。

#创建项目文件夹
mkdir tutorial
cd tutorial

#创建一个虚拟环境，使我们的安装包保持隔离
python3 -m venv env
source env/bin/activate  # On Windows use `env\Scripts\activate`

#在虚拟环境中安装Django和Django REST framework
pip install django
pip install djangorestframework

#新建一个Django项目，在项目中新建一个应用
django-admin startproject tutorial .  # 注意后面的“.”
cd tutorial
django-admin startapp quickstart
cd ..

项目目录应该如下所示：

$ pwd
<some path>/tutorial
$ find .
.
./manage.py
./tutorial
./tutorial/__init__.py
./tutorial/quickstart
./tutorial/quickstart/__init__.py
./tutorial/quickstart/admin.py
./tutorial/quickstart/apps.py
./tutorial/quickstart/migrations
./tutorial/quickstart/migrations/__init__.py
./tutorial/quickstart/models.py
./tutorial/quickstart/tests.py
./tutorial/quickstart/views.py
./tutorial/settings.py
./tutorial/urls.py
./tutorial/wsgi.py

这种项目结构可以避免应用与外部模块重名。

现在同步数据库：

python manage.py migrate

我们可以创建一个初始的管理员账户admin，密码为password123,：

python manage.py createsuperuser --email admin@example.com --username admin

创建好管理员账户之后，打开应用目录

Serializers（序列化器）

在tutorial/quickstart/serializers.py 中新建一个模型，用来代表我们的数据。

from django.contrib.auth.models import User, Group
from rest_framework import serializers


class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups']


class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

注意我们使用HyperlinkedModelSerializer来表示超链接关系，这是一个不错的RESTful设计。

Views（视图）

在tutorial/quickstart/views.py中键入一下代码：

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer


class UserViewSet(viewsets.ModelViewSet):
    """
    允许查看或者编辑用户的API接口
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer


class GroupViewSet(viewsets.ModelViewSet):
    """
    允许查看或者编辑群组的API接口
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

我们没有写很多的views，而是把所有的常见操作整合进了ViewSets，这是一个非常简洁的设计。

URLs（链接）

现在打开tutorial/urls.py 使我们的API 链接生效：

from django.urls import include, path
from rest_framework import routers
from tutorial.quickstart import views

router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)

# 向routers类注册自动完成URL映射
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因为我们使用viewsets，我们可以通过在rest_framework.routers注册来自动生成URL。最后，使用默认的登录登出视图，如果你的API需要认证并且你想使用可以浏览的API，你就应该使用它。

Pagination（分页）

分页允许你控制每次返回多少对象，在tutorial/settings.py中键入以下代码：

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

在INSTALLED_APPS中加入'rest_framework'：

INSTALLED_APPS = [
    ...
    'rest_framework',
]

完成。

Testing our API （测试API）

启动Django

python manage.py runserver

在浏览器中键入http://127.0.0.1:8000/users/

userlist