Django REST framework快速入门(官方文档翻译翻译)

开始

我们将创建一个简单的API来允许管理员用户查看和编辑系统中的用户和组。

项目设置

创建一个新的django项目，命名为：<tutorial>，然后创建一个新的应用程序(app)，命名为：<quickstart>。

# Create the project directory

mkdir tutorial

cd tutorial

# Create a virtual environment to isolate our package dependencies locally

python3 -m venv env

source env/bin/activate  # On Windows use `env\Scripts\activate`

# Install Django and Django REST framework into the virtual environment

pip install django

pip install djangorestframework

# Set up a new project with a single application

django-admin startproject tutorial .  # Note the trailing '.' character

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

当你设置好数据库，初始用户创建完成后，打开应用程序<quickstart>目录，然后就可以开始写代码啦~

序列化工具(Serializers)

第一步我们将定义一些序列化工具(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']

注意我们现在使用的序列化工具<UserSerializer>和<GroupSerializer>都继承至<HyperlinkedModelSerializer>这个父类。这个父类允许我们以超链接的方式来描述数据表之间的关系。你也可以使用主键<primary key>或者其他方式来关联数据表之间的关系，但是使用超链接这种设计方式是非常符合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 endpoint that allows users to be viewed or edited.

    """

    queryset = User.objects.all().order_by('-date_joined')

    serializer_class = UserSerializer

class GroupViewSet(viewsets.ModelViewSet):

    """

    API endpoint that allows groups to be viewed or edited.

    """

    queryset = Group.objects.all()

    serializer_class = GroupSerializer

我们通过类<ViewSets>这个类，将视图函数中功能一致的部分都整合到一起。这样就不需要写很多的视图函数了。

当然， 在一些需要自定义的情况下我们也可以轻易地将整合好的视图分离，但是使用<ViewSets>可以让我们的逻辑整理的更加清晰同时代码也更加简洁。

路由设置(URLs)

接下来我们该设置我们的API路由了。打开<tutorial/urls.py>。

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)

# Wire up our API using automatic URL routing.

# 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>实例替代了原始的视图，这让我们可以通过在<DefaultRouter>的实例中，中注册我们的<ViewSets>实例即可自动地为我们生成相应的路由。

当然，如果我们希望自定义路由使其功能更加丰富，也可以抛弃这个功能转而使用普通的基于类的视图，然后定义路由。

最后一步，将用户登录和登出视图放置在了可浏览的API页面内。这是一个可选择项，如果你的需要使用可浏览的API页面和用户管理。

分页

分页功能让你可以控制每页显示多少个对象。要使用它的话请在文件<tutorial/settings.py>内添加以下代码：

REST_FRAMEWORK = {

    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',

    'PAGE_SIZE': 10

}

设置

打开设置模块<tutorial/settings.py>，将<’rest_framework’>添加到<INSTALLED_APPS>。如下：

INSTALLED_APPS = [

    ...

    'rest_framework',

]

以上，我们已经做完了。一个简单的用户管理API，并且可以在浏览器上快速访问，测试的API。看完以上东西你可能会想：”wtf？？？！！！。这是什么东西？”。接下来我们将做一些测试，来帮助你理解。我们到底做了个什么的东西。

测试API

现在我们可以开始测试刚刚搭建好的API。不过在这之前我们先定一个小目标，比如先让程序跑起来。

python manage.py runserver

如果小目标没有实现。请查看错误信息，然后翻回去仔细看看代码。

接下来我们就可以访问我们的API了。可以通过命令行访问，使用curl工具：

bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 http://127.0.0.1:8000/users/

{

    "count": 2,

    "next": null,

    "previous": null,

    "results": [

        {

            "email": "admin@example.com",

            "groups": [],

            "url": "http://127.0.0.1:8000/users/1/",

            "username": "admin"

        },

        {

            "email": "tom@example.com",

            "groups": [                ],

            "url": "http://127.0.0.1:8000/users/2/",

            "username": "tom"

        }

    ]

}

或者使用Httpie工具：

bash: http -a admin:password123 http://127.0.0.1:8000/users/

HTTP/1.1 200 OK

...

{

    "count": 2,

    "next": null,

    "previous": null,

    "results": [

        {

            "email": "admin@example.com",

            "groups": [],

            "url": "http://localhost:8000/users/1/",

            "username": "paul"

        },

        {

            "email": "tom@example.com",

            "groups": [                ],

            "url": "http://127.0.0.1:8000/users/2/",

            "username": "tom"

        }

    ]

}

或者直接使用浏览器。打开链接：http://127.0.0.1:8000/users/

如果你是通过浏览器访问的，你需要在右上角登录。因为这个管理工具是给admin用的。游客无法访问。

如果还要深入学习和理解REST framework是如何将这些功能一步一步封装到一起的。请继续收看之后的指导文章，或者直接阅读我们的API。

以上就是本文全部内容，如果你看不懂，那大概需要用django再做几个小项目来熟悉一下django web应用的业务流程。