Django REST framework 中文文档

最开始是2015年还在搜狗上班的时候，有个项目用到DRF框架的时候随手翻译的。

如果本文对你有帮助，请在github上 star 该项目。

当然我也十分欢迎你加入该项目并提交PR推送你的翻译。

（说句题外话，一个翻译项目就没有必要抄袭了吧。。。我都无奈了。。。）

Django REST framework 技术交流QQ群

QQ群号：930578836

翻译人员

• Q1mi
• ScienceYuan
• leveleven
• Liniian
• belingud
• Core00077

以下章节已完成翻译

教程

• Quickstart
• 1-Serialization
• 2-requests-and-responses
• 3-class-based-views
• 4-authentication-and-permissions
• 5-relationships-and-hyperlinked-apis
• 6-viewsets-and-routers
• 7-schemas-and-client-libraries

API指南

• Requests
• Responses
• Views
• Generic Views
• Viewets
• Routers
• Parsers
• Renderers
• Serializers
• Serializer fields
• Validators
• Throttling
• Filtering
• Pagination
• Authentication
• Permissions
• Caching
• Versioning
• Content negotiation
• Format suffixes
• Metadata
• Returning URLs
• Exceptions
• Status codes
• Testing

主题

• ajax-csrf-cors

要求

REST framework 需要满足以下要求:

• Python (3.5, 3.6, 3.7, 3.8, 3.9)
• Django (2.2, 3.0, 3.1)

我们强烈推荐且仅官方支持Python和Django的每个系列(大版本)的最新版本。

以下包为可选项：

• PyYAML, uritemplate (5.1+, 3.0.0+) - Schema生成支持。
• Markdown (3.0.0+) - 为browsable API 提供Markdown支持。
• Pygments (2.4.0+) - 为Markdown处理提供语法高亮。
• django-filter (1.0.1+) - Filtering支持。
• django-guardian (1.1.1+) - 对象级别的权限支持。

安装

用 pip来安装，可以包括任何你想安装的可选包…

pip install djangorestframework
pip install markdown       # 为browsable API 提供Markdown支持。
pip install django-filter  # Filtering支持。

...或者直接从github clone该项目。

git clone https://github.com/encode/django-rest-framework

在INSTALLED_APPS中添加 'rest_framework' 项。

INSTALLED_APPS = [
    ...
    'rest_framework',
]

如果你正打算用browsable API，你可能也想用REST framework的登录注销视图。把下面的代码添加到你根目录的urls.py文件。

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

请注意，URL路径可以随意改。

举个例子

让我们来看看一个用REST framework构建的简单的模型支撑的API后端案例。

我们会创建一个读写API来访问我们项目的用户信息。

REST framework API的所有全局设定都会放在一个叫REST_FRAMEWORK的配置词典里。首先把下面的内容添加到你的settings.py模块中：

REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

不要忘了你还要rest_framework添加到你的INSTALLED_APPS里。

这样我们就可以开始创建我们的API了。

这是我们根目录的urls.py模块：

from django.urls import path, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets

# 序列化器是用来定义API的表示形式。
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'is_staff']

# ViewSets定义视图的行为。
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# 路由器提供一个简单自动的方法来决定URL的配置。
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# 通过URL自动路由来给我们的API布局。
# 此外，我们还要把登录的URL包含进来。
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

现在你可以在浏览器中打开http://127.0.0.1:8000/，查看你的'user' API了。如果你用了右上角的登录控制，那你还可以在系统中添加、创建并删除用户。

Quickstart

迫不及待想上手了？快速入门指南是你上手、运行并构建REST framewrok API的最快方法。