01.速覽Django REST framework

我們將創建一個簡單的API，以允許管理員用戶查看和編輯系統中的用戶和組。

項目設置

創建一個名爲的新Django項目tutorial，然後啓動一個名爲的新應用quickstart。

# 創建項目文件夾
mkdir tutorial
cd tutorial

# 創建虛擬環境
python3 -m venv env
# 啓動虛擬環境
source env/bin/activate  # 在 Windows系統裏使用 `env\Scripts\activate`

# 在虛擬環境裏安裝 Django 和 Django REST framework
pip install django
pip install djangorestframework

# 創建一個Django項目
django-admin startproject tutorial .  # 注意後面有一個'.'號
cd tutorial
# 創建一個app
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 [email protected] --username admin

建立數據庫並創建初始用戶並準備好使用後，打開應用程序的目錄，我們將進行編碼…

序列化器 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']

請注意，在這種情況下，我們將使用超鏈接關係HyperlinkedModelSerializer。也可以使用主鍵和其他各種關係，但是超鏈接是一種很好的RESTful設計。

Views

好的，那我們最好寫一些views。打開tutorial/quickstart/views.py並輸入內容。

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


class UserViewSet(viewsets.ModelViewSet):
    """
    允許用戶查看或編輯的API端點。
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]


class GroupViewSet(viewsets.ModelViewSet):
    """
    允許用戶查看或編輯的API端點。
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

而不是編寫多個視圖，我們將所有常見行爲分組到稱爲類中ViewSets。

如果需要，我們可以輕鬆地將它們分解爲單個視圖，但是使用視圖集可以使視圖邏輯組織得很好並且非常簡潔。

URLs

好的，現在讓我們連接API URL。繼續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)

# 使用自動URL路由連接我們的API。
# 此外，我們還包含了browsable API的登錄url。
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因爲我們使用的是viewsets而不是views，所以我們只需爲路由類註冊viewsets即可自動爲我們的API生成URL conf。

同樣，如果我們需要對API URL的更多控制，我們可以簡單地使用常規的基於類的views，並顯式編寫URL conf。

最後，我們包括用於可瀏覽API的默認登錄和註銷views。這是可選的，但在您的API需要身份驗證並且您想使用可瀏覽的API時很有用。

分頁

分頁可讓您控制每頁返回多少個對象。要啓用它，請將以下行添加到tutorial/settings.py

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

Settings

添加'rest_framework'到INSTALLED_APPS。設置模塊將位於tutorial/settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
]

好的，我們完成了。

---

測試我們的API

現在，我們準備測試我們構建的API。讓我們從命令行啓動服務器。

python manage.py runserver

現在，我們可以使用諸如curl…之類的工具從命令行訪問API 。

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": "[email protected]",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },
        {
            "email": "[email protected]",
            "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": "[email protected]",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "[email protected]",
            "groups": [                ],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

或直接通過瀏覽器訪問URL http://127.0.0.1:8000/users/…

如果使用瀏覽器，請確保使用右上角的控件登錄。

太好了，就是這麼簡單！

如果您想更深入地瞭解REST框架如何組合在一起，請繼續閱讀本教程，或者開始瀏覽API指南。